Martin/MAUWB-platformiotest
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
MAUWB-platformiotest/CLAUDE.md
martin a2e404ec0f Refactor to unified firmware architecture with modular configuration system 
BREAKING CHANGE: Replace separate anchor/tag firmware with single configurable codebase

## Major Changes
- **Unified Firmware**: Single main.cpp replaces main_anchor.cpp and main_tag.cpp
- **Modular Config**: Organized configuration system in src/config/ directory
- **Dynamic Behavior**: Device behavior determined by build flags at compile time
- **Simplified Builds**: Reduced from 8+ environments to 3 core environments

## New Architecture
- src/main.cpp - Single firmware with config-driven behavior
- src/config/device_config.h - Device role detection and unified behavior
- src/config/anchor_config.h - Anchor-specific settings (positioning, communication)
- src/config/tag_config.h - Tag-specific settings (USB streaming, coordinate collection)
- src/config/positioning_config.h - Distributed positioning algorithm framework

## Build System Improvements
- Simplified platformio.ini (anchor/tag/debug environments)
- Support for custom device ID and network via PLATFORMIO_BUILD_FLAGS
- Same firmware for all devices, behavior configured at compile time
- Easy device configuration: set PLATFORMIO_BUILD_FLAGS=-DUWB_INDEX=5 -DNETWORK_ID=2000

## Technical Benefits
- Reduced code duplication from ~350 lines to unified ~200 lines
- Consistent behavior across device types
- Easier maintenance with single codebase
- Framework ready for distributed positioning algorithm implementation
- Modular configuration system for future algorithm expansion

## Positioning Framework Ready
- Anchor discovery protocol framework established
- Inter-anchor communication configuration ready
- Position calculation algorithm structure in place
- Coordinate storage and validation system configured
- Tag coordinate collection and USB streaming framework prepared

## Testing
- ✅ Anchor build successful (325KB flash usage)
- ✅ Tag build successful (325KB flash usage)
- ✅ Custom device ID/network configuration working
- ✅ UWB initialization sequence fixed for active networks
2025-08-21 21:24:38 +02:00

6.3 KiB
Raw Blame History

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