Reorganize project structure and create development roadmap
- Move documentation to organized docs/ directory structure - Add dev notes - Create comprehensive 5-phase roadmap for indoor positioning system - Move AT command manual and hardware images to docs/ - Update README with hardware links and project overview - Remove sleep mode and OTA functionality for simplification - Clean up project structure for production development
This commit is contained in:
martin
parent
ea370ac702
commit
e7c8fad272
8 changed files with 884 additions and 47 deletions
106
CLAUDE.md
Normal file
106
CLAUDE.md
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
# 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 ’ Store coordinates locally ’ Report to tags
|
||||
Tags: Range to anchors ’ Collect coordinates ’ USB to PC ’ 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 system implements **Phase 1** of a 5-phase indoor positioning project (see docs/ROADMAP.md):
|
||||
- **Current**: Basic anchor-tag ranging with USB data collection
|
||||
- **Next**: Anchor auto-positioning, dual-file logging, PC software, web visualization
|
||||
- **Goal**: <15min warehouse setup, <30cm accuracy, real-time + offline analysis
|
||||
|
||||
## 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue