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