fafc2d5830
- Restructured roadmap to focus on ESP32 firmware development only - Removed time constraints from all development phases - Clarified data flow: ESP32 streams to webapp, webapp handles all logging - Updated deliverables: firmware components, hardware integration, OLED support - Removed PC software and web visualization phases (handled by separate webapp) - Updated success criteria for ESP32 firmware performance metrics - Updated dev notes to reflect webapp integration architecture
107 lines
No EOL
4.4 KiB
Markdown
107 lines
No EOL
4.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
This is an ESP32-S3 based Ultra-Wideband (UWB) indoor positioning system for warehouse WiFi mapping. The system consists of anchor devices (base stations) and tag devices (mobile trackers) using Makerfabs MaUWB modules with Qorvo DW3000 chips.
|
||
|
||
**Key Architecture**: Battery-powered anchors auto-position themselves, mobile tag collects positioning data via USB to PC for real-time display and dual-file logging for offline analysis.
|
||
|
||
## Development Commands
|
||
|
||
### Build & Flash
|
||
```bash
|
||
# Build specific device type
|
||
pio run -e anchor # Build anchor firmware
|
||
pio run -e tag # Build tag firmware
|
||
pio run -e tag2 # Build second tag (ID 2)
|
||
|
||
# Flash to device
|
||
pio run -e tag -t upload
|
||
pio run -e anchor -t upload
|
||
|
||
# Monitor serial output
|
||
pio device monitor
|
||
```
|
||
|
||
### Development Environments
|
||
- **anchor**: Base station (UWB_INDEX=0, tracks tags)
|
||
- **tag**: Mobile tracker (UWB_INDEX=1, reports to anchors)
|
||
- **tag2**: Second mobile tracker (UWB_INDEX=2)
|
||
- **debug**: Development build with DEBUG_ENABLED=1
|
||
|
||
## Core Architecture
|
||
|
||
### Device Roles & Communication Flow
|
||
```
|
||
Anchors: Auto-position <20> Store coordinates locally <20> Report to tags
|
||
Tags: Range to anchors <20> Collect coordinates <20> USB to PC <20> Real-time + logging
|
||
```
|
||
|
||
### Key Technical Patterns
|
||
|
||
**1. Dual Firmware Architecture**
|
||
- `main_anchor.cpp`: Tracks tags, manages UWB_TAG_COUNT devices, displays active tags
|
||
- `main_tag.cpp`: Connects to MAX_ANCHORS, reports to PC via USB, displays anchor distances
|
||
- Shared: config.h for hardware pins, UWBHelper library for AT commands
|
||
|
||
**2. UWBHelper Library Structure**
|
||
- **Complete AT Command Implementation**: All 21 commands from AT manual
|
||
- **Device Role Configuration**: `configureDevice(id, isAnchor)` sets anchor/tag mode
|
||
- **Advanced Data Structures**: RangeResult, AnchorPosition, DeviceData for multi-device tracking
|
||
- **Position Calculation**: PositionCalculator class with trilateration algorithms
|
||
- **Data Filtering**: DistanceFilter for noise reduction
|
||
|
||
**3. Hardware Configuration**
|
||
- **UWB Communication**: UART2 (pins 17/18) at 115200 baud
|
||
- **Display**: SSD1306 OLED via I2C (pins 38/39)
|
||
- **Reset**: Pin 16 for UWB module reset
|
||
- **Network**: ID 1234, 6.8Mbps mode, range filtering enabled
|
||
|
||
### Critical Implementation Details
|
||
|
||
**Device Identification**: Each device gets unique UWB_INDEX via build flags, determines network role and behavior
|
||
|
||
**Data Flow Pattern**:
|
||
- Anchors parse range data from tags: `parseRangeData(response, tags[], UWB_TAG_COUNT)`
|
||
- Tags parse range data from anchors: `parseRangeData(response, anchors[], MAX_ANCHORS)`
|
||
- Serial passthrough enabled for debugging: `uwbSerial.write(Serial.read())`
|
||
|
||
**Display Logic**:
|
||
- Anchors show active tags with distances/RSSI
|
||
- Tags show connected anchors with distances/RSSI
|
||
- Both show network status and device counts
|
||
|
||
**Timeout Management**: Devices marked inactive after DEVICE_TIMEOUT (5000ms) with no updates
|
||
|
||
## Configuration Constants
|
||
|
||
Key values in config.h:
|
||
- `MAX_ANCHORS 8`: Tag connects to 8 closest anchors
|
||
- `UWB_TAG_COUNT 64`: Network supports up to 64 tags
|
||
- `NETWORK_ID 1234`: UWB network identifier
|
||
- `DEVICE_TIMEOUT 5000`: Device inactivity timeout (ms)
|
||
- `DISPLAY_UPDATE_INTERVAL 500`: OLED refresh rate (ms)
|
||
|
||
## Development Roadmap Context
|
||
|
||
This ESP32 firmware implements the hardware foundation for the UWB positioning system (see docs/ROADMAP.md):
|
||
- **Current**: Basic anchor-tag ranging with USB data streaming via UWBHelper library
|
||
- **Next**: Anchor auto-positioning, coordinate relay through tag, battery optimization
|
||
- **Goal**: <15min anchor setup, <30cm ranging accuracy, reliable USB data streaming to webapp
|
||
- **WebApp Integration**: All data logging, visualization, and analysis handled by separate Next.js webapp
|
||
|
||
## Hardware Requirements
|
||
|
||
- **Modules**: Makerfabs MaUWB ESP32-S3 with built-in UWB + OLED
|
||
- **Power**: USB for development, battery for production anchors
|
||
- **Range**: Tested up to 100m line-of-sight, 30m through walls
|
||
- **Network**: No WiFi required, pure UWB communication
|
||
|
||
## Important Notes
|
||
|
||
- **No Sleep/OTA**: Removed for simplicity, focus on core positioning
|
||
- **AT Command Protocol**: Direct UART communication with UWB module
|
||
- **Position Calculation**: Client-side (PC) processing, not on-device
|
||
- **Data Logging**: Raw distance data + anchor coordinates for offline analysis |