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
```bash
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
```bash
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
```typescript
// 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.