MAUWB-platformiotest/CLAUDE.md

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)

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