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