Initial commit: Next.js UWB positioning webapp
- Complete Next.js 14 app with TypeScript and Tailwind CSS - ESP32 serial communication via API routes - Real-time UWB positioning visualization - Interactive 2D warehouse mapping with Canvas - Device connection interface with auto-detection - AT command parsing for UWBHelper library integration - Clean project structure with comprehensive documentation
This commit is contained in:
martin
commit
fa75faa69d
20 changed files with 7600 additions and 0 deletions
171
CLAUDE.md
Normal file
171
CLAUDE.md
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue