Martin/MAUWB-platformiotest
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
MAUWB-platformiotest/CLAUDE.md
martin fafc2d5830 Update ESP32 firmware roadmap - focus on hardware development 
- Restructured roadmap to focus on ESP32 firmware development only
- Removed time constraints from all development phases
- Clarified data flow: ESP32 streams to webapp, webapp handles all logging
- Updated deliverables: firmware components, hardware integration, OLED support
- Removed PC software and web visualization phases (handled by separate webapp)
- Updated success criteria for ESP32 firmware performance metrics
- Updated dev notes to reflect webapp integration architecture
2025-08-20 16:07:39 +02:00

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

Development Commands

Build & Flash

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