# 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 � Store coordinates locally � Report to tags
Tags: Range to anchors � Collect coordinates � USB to PC � 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 22 commands from AT manual v1.1.1 (2025/07/29)
- **Device Role Configuration**: `configureDevice(id, isAnchor)` sets anchor/tag mode with unlimited anchors support
- **Advanced Data Structures**: RangeResult, AnchorPosition, DeviceData for multi-device tracking
- **Position Calculation**: PositionCalculator class with trilateration algorithms
- **Data Filtering**: DistanceFilter for noise reduction
- **Multi-zone Positioning**: Tags auto-detect and select 8 nearest anchors from unlimited deployed anchors

**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 (from unlimited deployed anchors)
- `UWB_TAG_COUNT 64`: Network supports up to 64 tags
- `NETWORK_ID 1234`: UWB network identifier (changeable via AT+SETPAN, default: 1111)
- `DEVICE_TIMEOUT 5000`: Device inactivity timeout (ms)
- `DISPLAY_UPDATE_INTERVAL 500`: OLED refresh rate (ms)
- `ANTENNA_DELAY 16336`: Default antenna calibration value
- `TRANSMISSION_POWER FD`: Default power setting (configurable via AT+SETPOW)

## 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

## AT Command Reference (v1.1.1)

Complete list of 22 supported AT commands for MaUWB module configuration:

### Basic Commands
- `AT?`: Serial port communication test
- `AT+GETVER?`: Get software/hardware version
- `AT+RESTART`: Restart module
- `AT+RESTORE`: Factory reset (clear all configuration)
- `AT+SAVE`: Save configuration to flash (required after changes)

### Configuration Commands
- `AT+SETCFG=(id,role,rate,filter)`: Set device ID (0-unlimited anchors, 0-63 tags), role (0=tag, 1=anchor), data rate (0=850K, 1=6.8M), range filtering (0=off, 1=on)
- `AT+GETCFG?`: Get current configuration
- `AT+SETANT=(delay)`: Set antenna delay for distance calibration (default: 16336)
- `AT+GETANT?`: Get antenna delay
- `AT+SETCAP=(capacity,slot_time,ext_mode)`: Set tag capacity (max 64), time slot duration, extended packet mode
- `AT+GETCAP?`: Get capacity settings

### Network Commands  
- `AT+SETPAN=(network_id)`: Set network ID for device isolation (default: 1111)
- `AT+GETPAN?`: Get network ID
- `AT+SETPOW=(power)`: Set transmission power (default: FD)
- `AT+GETPOW?`: Get transmission power

### Operation Commands
- `AT+SETRPT=(auto_report)`: Enable/disable automatic distance reporting (0=off, 1=on)
- `AT+GETRPT?`: Get auto-report status
- `AT+RANGE`: Active distance measurement and reporting
- `AT+SLEEP=(time_ms)`: Put tag in sleep mode (0-65535ms, 65535=forever)
- `AT+DATA=(length,data)`: Send transparent data (up to 32 bytes, requires ext_mode=1)
- `AT+RDATA`: Receive data command
- `AT+SETPAN`: Network differentiation for multi-system environments
- `AT+GETPAN?`: Get network differentiation settings

### Key Features from Manual
- **Unlimited Anchors**: System supports unlimited anchors with tags auto-selecting 8 nearest
- **Multi-zone Positioning**: Use 6.8Mbps rate with range filtering disabled for optimal performance
- **Data Rates**: 850Kbps and 6.8Mbps modes supported
- **Refresh Rate**: Configurable up to 100Hz (capacity × slot_time relationship)
- **Power Management**: Tag deep sleep current 35uA, working current 34mA
- **Distance Accuracy**: <10cm ranging precision with proper calibration

## Important Notes

- **No Sleep/OTA**: Removed for simplicity, focus on core positioning
- **AT Command Protocol**: Direct UART communication with UWB module (115200 baud)
- **Position Calculation**: Client-side (PC) processing, not on-device
- **Data Logging**: Raw distance data + anchor coordinates for offline analysis
- **Multi-zone Support**: Firmware v1.1.3+ supports unlimited anchors with automatic selection