UWB-webapp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with the UWB Positioning Web Application.

Project Overview

This is a Next.js 14 web application for visualizing and controlling the ESP32-S3 Ultra-Wideband (UWB) indoor positioning system. It provides real-time positioning visualization and offline data analysis capabilities.

Key Architecture: React-based frontend with Node.js API routes, connects to ESP32 via USB serial, displays real-time positioning data with 2D warehouse visualization.

Development Commands

Setup & Development

npm install              # Install dependencies
npm run dev             # Start development server (http://localhost:3000)
npm run build           # Build for production
npm run start           # Start production server
npm run lint            # Run ESLint

API Testing

curl http://localhost:3000/api/serial/ports          # List available serial ports
curl -X POST http://localhost:3000/api/serial/connect # Connect to device
curl http://localhost:3000/api/uwb/data              # Get positioning data

Core Architecture

Frontend Structure

app/
├── page.tsx                 # Main dashboard page
├── layout.tsx              # Root layout with metadata
└── globals.css             # Global styles (Tailwind CSS)

components/
├── PositioningVisualizer.tsx  # Main visualization component
└── DeviceConnection.tsx       # Serial connection interface

Backend API Routes

pages/api/
├── serial/
│   ├── ports.ts            # GET: List ESP32 devices
│   └── connect.ts          # POST/DELETE/GET: Device connection
└── uwb/
    └── data.ts             # GET/POST: UWB positioning data

Data Flow Architecture

ESP32 (USB Serial) → API Routes → React Components → Canvas Visualization
                                ↓
                          WebSocket Updates → Real-time Display

ESP32 Integration Context

Hardware Communication

• Serial Connection: 115200 baud, USB to ESP32-S3
• AT Command Protocol: Direct integration with UWBHelper library
• Device Detection: Automatic ESP32 port identification (Silicon Labs CP210x, FTDI, CH340)
• Real-time Data: 1-second polling for AT+RANGE responses

UWB Data Processing

• Range Data Format: AT+RANGE=tid:X,timer:X,timerSys:X,mask:X,seq:X,range:(X,X,X...),rssi:(X,X,X...),ancid:(X,X,X...)
• Network Configuration: ID 1234, 8 anchors max, 64 tags supported
• Distance Units: Centimeters from ESP32 → Meters in webapp
• Coordinate System: Standard Cartesian (0,0) at bottom-left

TypeScript Data Structures

// Core types from ESP32 project
interface DeviceData {
  deviceId: number;     // Anchor/Tag ID
  distance: number;     // Range in meters  
  rssi: number;         // Signal strength
  lastUpdate: number;   // Timestamp
  active: boolean;      // Connection status
}

interface RangeResult {
  tagId: number;        // Mobile tag ID
  ranges: number[8];    // Distances to 8 anchors
  rssi: number[8];      // Signal strengths
  anchorIds: number[8]; // Connected anchor IDs
  // ... timing and sequence data
}

Visualization Features

2D Warehouse Map

• Canvas Rendering: HTML5 Canvas with coordinate transformation
• Grid System: 2m grid spacing, 12m x 10m default warehouse
• Real-time Updates: Live anchor positions and tag movement
• Visual Indicators: Color-coded confidence levels (green=high, yellow=low)

Interactive Elements

• Device Connection: Dropdown port selection with auto-detection
• Status Dashboard: Active anchors, tag position, confidence metrics
• Real-time Data: 1-second polling with automatic updates

Configuration Constants

Key values matching ESP32 firmware:

• MAX_ANCHORS: 8 - Maximum connected anchors per tag
• UWB_TAG_COUNT: 64 - Network capacity
• NETWORK_ID: 1234 - UWB network identifier
• BAUD_RATE: 115200 - Serial communication speed
• POLL_INTERVAL: 1000ms - Real-time data update rate

API Endpoints Reference

Serial Communication

• GET /api/serial/ports - List available COM ports with ESP32 filtering
• POST /api/serial/connect - Connect to device: {port: "COM3", baudRate: 115200}
• DELETE /api/serial/connect - Disconnect from device
• GET /api/serial/connect - Get connection status

UWB Data

• GET /api/uwb/data - Get latest positioning data
• POST /api/uwb/data - Send AT command: {command: "AT+GETRPT?"}

Development Roadmap Context

This webapp implements Phase 4 of the UWB positioning project (see main project ROADMAP.md):

• Current: Real-time visualization with ESP32 serial connection
• Next: Dual-file upload (raw_positioning.csv + anchor_coordinates.csv)
• Future: Path playback, session analysis, warehouse mapping tools

Tech Stack Details

Frontend

• Framework: Next.js 14 with App Router
• Language: TypeScript with strict mode
• Styling: Tailwind CSS 3.3+
• UI Components: Custom React components with Canvas rendering
• State Management: React hooks (useState, useEffect, useCallback)

Backend

• Runtime: Node.js with Next.js API routes
• Serial Communication: SerialPort library for ESP32 connection
• Data Processing: Custom AT command parsing
• WebSocket: Real-time data streaming (planned)

Development Tools

• Linting: ESLint with Next.js configuration
• TypeScript: Strict type checking with ESP32 data structures
• Hot Reload: Next.js development server with fast refresh

Important Notes

• Serial Port Access: Requires native Node.js modules, client-side limitations handled via API routes
• ESP32 Detection: Automatic filtering for common ESP32 USB-to-Serial chips
• Data Validation: AT command format validation and error handling
• Coordinate System: Matches ESP32 firmware expectations (meters, Cartesian)
• Real-time Performance: 1-second polling optimized for warehouse-scale positioning

File Upload Integration (Future)

The webapp is designed to support the dual-file approach from the main project:

• raw_positioning.csv: Tag distance measurements with timestamps
• anchor_coordinates.csv: Calibrated anchor positions from auto-positioning
• Offline Analysis: Calculate tag paths using anchor coordinates + raw distances
• Session Playback: Timeline scrubbing and path visualization

This webapp serves as the visualization frontend for the complete ESP32-S3 UWB positioning system, bridging real-time hardware data with interactive web-based analysis tools.