a2e404ec0f
BREAKING CHANGE: Replace separate anchor/tag firmware with single configurable codebase ## Major Changes - **Unified Firmware**: Single main.cpp replaces main_anchor.cpp and main_tag.cpp - **Modular Config**: Organized configuration system in src/config/ directory - **Dynamic Behavior**: Device behavior determined by build flags at compile time - **Simplified Builds**: Reduced from 8+ environments to 3 core environments ## New Architecture - src/main.cpp - Single firmware with config-driven behavior - src/config/device_config.h - Device role detection and unified behavior - src/config/anchor_config.h - Anchor-specific settings (positioning, communication) - src/config/tag_config.h - Tag-specific settings (USB streaming, coordinate collection) - src/config/positioning_config.h - Distributed positioning algorithm framework ## Build System Improvements - Simplified platformio.ini (anchor/tag/debug environments) - Support for custom device ID and network via PLATFORMIO_BUILD_FLAGS - Same firmware for all devices, behavior configured at compile time - Easy device configuration: set PLATFORMIO_BUILD_FLAGS=-DUWB_INDEX=5 -DNETWORK_ID=2000 ## Technical Benefits - Reduced code duplication from ~350 lines to unified ~200 lines - Consistent behavior across device types - Easier maintenance with single codebase - Framework ready for distributed positioning algorithm implementation - Modular configuration system for future algorithm expansion ## Positioning Framework Ready - Anchor discovery protocol framework established - Inter-anchor communication configuration ready - Position calculation algorithm structure in place - Coordinate storage and validation system configured - Tag coordinate collection and USB streaming framework prepared ## Testing - ✅ Anchor build successful (325KB flash usage) - ✅ Tag build successful (325KB flash usage) - ✅ Custom device ID/network configuration working - ✅ UWB initialization sequence fixed for active networks
134 lines
No EOL
6.3 KiB
Markdown
134 lines
No EOL
6.3 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.
|
||
|
||
**Unified Firmware**: Single codebase with config-driven behavior for all device types, organized in modular configuration structure.
|
||
|
||
## Development Commands
|
||
|
||
### Build & Flash (Unified Firmware)
|
||
```bash
|
||
# Build default configurations
|
||
pio run -e anchor # Build anchor (ID=0, Network=1234)
|
||
pio run -e tag # Build tag (ID=1, Network=1234)
|
||
pio run -e debug # Build debug anchor (ID=0, Network=1234)
|
||
|
||
# Build with custom device ID and network
|
||
set PLATFORMIO_BUILD_FLAGS=-DUWB_INDEX=5 -DNETWORK_ID=2000
|
||
pio run -e anchor # Build anchor ID=5, Network=2000
|
||
|
||
# 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 with distributed positioning (default: ID=0, Network=1234)
|
||
- **tag**: Mobile tracker with coordinate collection (default: ID=1, Network=1234)
|
||
- **debug**: Development anchor build with DEBUG_ENABLED=1
|
||
|
||
### Unified Architecture
|
||
All devices now use the same `main.cpp` with config-driven behavior:
|
||
- Device type determined by build flags (`DEVICE_TYPE_ANCHOR`/`DEVICE_TYPE_TAG`)
|
||
- Behavior configured via `anchor_config.h` and `tag_config.h`
|
||
- Positioning algorithm settings in `positioning_config.h`
|
||
- Easy customization via `PLATFORMIO_BUILD_FLAGS` environment variable
|
||
|
||
## 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. Unified Firmware Architecture**
|
||
- `src/main.cpp`: Single firmware for all devices, behavior determined by build flags
|
||
- `src/config/`: Modular configuration system with device-specific settings
|
||
- Dynamic behavior: Device type, peer management, and display logic configured at compile time
|
||
- Shared: UWBHelper library for AT commands, unified communication and display handling
|
||
|
||
**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
|
||
|
||
**4. Modular Configuration System**
|
||
- `src/config/config.h`: Hardware pin definitions and basic system settings
|
||
- `src/config/device_config.h`: Device role detection and unified behavior configuration
|
||
- `src/config/anchor_config.h`: Anchor-specific settings (tag tracking, positioning, inter-anchor communication)
|
||
- `src/config/tag_config.h`: Tag-specific settings (anchor tracking, USB streaming, coordinate collection)
|
||
- `src/config/positioning_config.h`: Distributed positioning algorithm parameters and validation settings
|
||
|
||
## 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**: Unified firmware architecture with config-driven behavior, ready for distributed positioning implementation
|
||
- **Framework**: Configuration structure established for anchor discovery, position calculation, coordinate storage, and data relay
|
||
- **Next**: Implement anchor auto-positioning algorithms, 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
|
||
|
||
### Distributed Positioning Framework Ready
|
||
- **Anchor Behavior**: Framework for inter-anchor communication, discovery protocol, position calculation
|
||
- **Tag Behavior**: Framework for coordinate collection, USB data streaming, real-time positioning
|
||
- **Algorithm Foundation**: Trilateration, consensus mechanisms, coordinate system establishment
|
||
- **Storage System**: EEPROM-based position persistence for battery-powered anchors
|
||
|
||
## 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 |