diff --git a/CLAUDE.md b/CLAUDE.md index ee82241..c64e209 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -127,10 +127,11 @@ Key values matching ESP32 firmware: ## 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 +This webapp is the complete data processing and visualization platform for the UWB positioning system (see ROADMAP.md): +- **Current**: Phase 1 complete - Real-time ESP32 integration with live positioning visualization +- **Next**: Phase 2 - Data logging, CSV analysis, and session management +- **Future**: Advanced analytics, WebSocket streaming, warehouse configuration tools +- **ESP32 Integration**: Handles ALL data logging, processing, and visualization - ESP32 only streams raw data ## Tech Stack Details diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..4ee5dd7 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,216 @@ +# UWB WebApp Development Roadmap +**Next.js Ultra-Wideband Positioning Visualization & Analysis Platform** + +--- + +## 🎯 Project Overview + +**Purpose**: Web application for real-time UWB positioning visualization and offline data analysis +- **Frontend**: Next.js 14 with TypeScript and Tailwind CSS +- **Backend**: Node.js API routes with ESP32 serial communication +- **Data Processing**: Real-time positioning, CSV analysis, path tracking +- **Goal**: Complete positioning workflow from ESP32 data stream to warehouse mapping + +--- + +## 📋 System Requirements + +### Core Functionality +- ✅ **ESP32 Serial Communication** - USB connection with automatic device detection +- ✅ **Real-time Visualization** - 2D warehouse mapping with live positioning updates +- ✅ **Data Processing** - AT command parsing and UWB range data interpretation +- [ ] **File Analysis** - CSV upload and offline positioning calculation +- [ ] **Session Management** - Multiple mapping sessions with comparison tools + +### Technical Stack +- ✅ **Next.js 14** - App Router with TypeScript +- ✅ **Tailwind CSS** - Responsive UI design +- ✅ **SerialPort** - ESP32 USB communication +- ✅ **Canvas API** - High-performance 2D visualization +- [ ] **WebSocket** - Real-time data streaming +- [ ] **File Processing** - CSV parsing and data validation + +--- + +## 🏗️ System Architecture + +### Data Flow Design +``` +ESP32 Tag (USB) → SerialPort API → Real-time Processing → Canvas Visualization + ↓ ↓ + Data Logging (CSV) Live Path Tracking + ↓ ↓ + File Upload Analysis Session Comparison Tools +``` + +### Core Components +- **DeviceConnection**: ESP32 detection, serial communication, connection management +- **PositioningVisualizer**: Canvas-based 2D warehouse map with real-time updates +- **API Routes**: Serial ports, device connection, UWB data processing +- **Data Processing**: AT command parsing, coordinate transformation, filtering + +--- + +## 🚀 WebApp Development Roadmap + +### Phase 1: Real-time Positioning (✅ Completed) + +#### 1.1 ESP32 Integration +- ✅ **Serial Communication** - Automatic ESP32 device detection and connection +- ✅ **AT Command Processing** - UWBHelper library data parsing +- ✅ **Real-time Data Stream** - Live positioning updates via API polling + +#### 1.2 Visualization Engine +- ✅ **Canvas Rendering** - High-performance 2D warehouse mapping +- ✅ **Coordinate System** - Proper Cartesian coordinates with grid display +- ✅ **Live Updates** - Real-time anchor positions and tag movement +- ✅ **Visual Indicators** - Confidence levels, signal strength, connection status + +#### 1.3 User Interface +- ✅ **Device Connection Panel** - Port selection, connection management +- ✅ **Status Dashboard** - Active anchors, tag position, system metrics +- ✅ **Clean Design** - Professional Tailwind CSS styling + +### Phase 2: Data Logging & Session Management + +#### 2.1 Real-time Data Logging +- [ ] **CSV Export** - Automatic session logging during real-time operation +- [ ] **Data Validation** - Timestamp consistency, coordinate bounds checking +- [ ] **Session Metadata** - Start/end times, anchor count, data quality metrics +- [ ] **Background Logging** - Non-blocking CSV generation during live sessions + +#### 2.2 File Upload & Analysis +- [ ] **Dual-file Upload** - raw_positioning.csv + anchor_coordinates.csv support +- [ ] **Data Correlation** - Match positioning data with anchor coordinates +- [ ] **Offline Calculation** - Tag path reconstruction from raw distance measurements +- [ ] **Data Validation** - File format verification, missing data handling + +#### 2.3 Session Management +- [ ] **Session Storage** - Local storage for multiple mapping sessions +- [ ] **Session Comparison** - Side-by-side analysis of different runs +- [ ] **Export Options** - PNG images, PDF reports, JSON data export +- [ ] **Session Metadata** - Notes, timestamps, warehouse configurations + +### Phase 3: Advanced Visualization & Analysis + +#### 3.1 Interactive Mapping +- [ ] **Warehouse Floor Plan** - Background image support with coordinate alignment +- [ ] **Scale Calibration** - Real-world measurements and coordinate scaling +- [ ] **Interactive Elements** - Clickable anchors, draggable coordinate system +- [ ] **Multiple View Modes** - Raw data, filtered paths, heat maps + +#### 3.2 Path Analysis Tools +- [ ] **Timeline Playback** - Scrub through positioning session with time controls +- [ ] **Path Statistics** - Distance traveled, speed analysis, dwell time calculation +- [ ] **Area Coverage** - Warehouse coverage maps, unvisited areas highlighting +- [ ] **Movement Patterns** - Route optimization suggestions, efficiency analysis + +#### 3.3 Data Filtering & Processing +- [ ] **Noise Reduction** - Distance filtering, outlier detection and removal +- [ ] **Path Smoothing** - Movement trajectory optimization +- [ ] **Coordinate Transformation** - Multiple coordinate systems, rotation, scaling +- [ ] **Quality Metrics** - Data confidence scoring, accuracy estimation + +### Phase 4: Advanced Features & Integration + +#### 4.1 WebSocket Real-time Streaming +- [ ] **Live WebSocket** - Replace polling with WebSocket for instant updates +- [ ] **Multiple Clients** - Support multiple browser connections +- [ ] **Real-time Collaboration** - Multiple users viewing same session +- [ ] **Performance Optimization** - Efficient data streaming protocols + +#### 4.2 Warehouse Configuration +- [ ] **Warehouse Setup** - Define warehouse dimensions, obstacles, zones +- [ ] **Anchor Placement** - Optimal anchor positioning suggestions +- [ ] **Calibration Tools** - System accuracy validation and improvement +- [ ] **Configuration Presets** - Save/load warehouse configurations + +#### 4.3 Advanced Analytics +- [ ] **WiFi Strength Mapping** - Integration with WiFi scanning data +- [ ] **Heat Map Generation** - Signal strength visualization overlays +- [ ] **Route Optimization** - Suggest optimal warehouse navigation paths +- [ ] **Performance Monitoring** - System uptime, accuracy tracking, error analysis + +### Phase 5: Production & Deployment + +#### 5.1 Production Optimization +- [ ] **Performance Tuning** - Canvas rendering optimization, memory management +- [ ] **Build Optimization** - Next.js production build, asset optimization +- [ ] **Error Handling** - Comprehensive error boundaries, graceful failures +- [ ] **Loading States** - Professional loading indicators, progress bars + +#### 5.2 Deployment & Distribution +- [ ] **Docker Containerization** - Easy deployment with Docker compose +- [ ] **Environment Configuration** - Development/production environment management +- [ ] **Documentation** - Complete user manual, API documentation +- [ ] **Testing** - Unit tests, integration tests, end-to-end testing + +--- + +## 🎯 Key Technical Challenges + +### 1. Real-time Performance +**Challenge**: Smooth 60fps canvas rendering with continuous data updates +**Solution**: Efficient canvas drawing with requestAnimationFrame, data batching + +### 2. Serial Communication Reliability +**Challenge**: Stable ESP32 connection with automatic reconnection +**Solution**: Robust error handling, connection monitoring, automatic retry logic + +### 3. Large Dataset Processing +**Challenge**: Handle large CSV files with thousands of positioning points +**Solution**: Streaming data processing, virtual scrolling, worker threads + +### 4. Coordinate System Accuracy +**Challenge**: Precise coordinate transformation and calibration +**Solution**: Mathematical coordinate transformations, calibration algorithms + +### 5. Cross-platform Compatibility +**Challenge**: SerialPort native dependencies across Windows/Mac/Linux +**Solution**: Proper webpack configuration, electron packaging options + +--- + +## 📦 WebApp Deliverables + +### Core Application +- ✅ **Next.js 14 Application** - Modern React framework with TypeScript +- ✅ **Real-time Visualization** - Canvas-based positioning display +- ✅ **ESP32 Integration** - Serial communication and AT command processing +- [ ] **Data Analysis Tools** - CSV processing and offline calculation + +### User Interface Components +- ✅ **Device Connection Interface** - ESP32 detection and connection management +- ✅ **Positioning Visualizer** - Interactive 2D warehouse mapping +- [ ] **File Upload Interface** - Drag-drop CSV analysis +- [ ] **Session Management** - Multiple session comparison and export + +### API & Integration +- ✅ **Serial Communication API** - ESP32 device management endpoints +- ✅ **UWB Data Processing** - AT command parsing and data transformation +- [ ] **File Processing API** - CSV upload and analysis endpoints +- [ ] **WebSocket Integration** - Real-time data streaming + +### Documentation & Deployment +- ✅ **Technical Documentation** - CLAUDE.md with complete development context +- ✅ **README** - Installation and usage instructions +- [ ] **User Manual** - Complete application user guide +- [ ] **Deployment Guide** - Production deployment procedures + +--- + +## 🔄 WebApp Success Criteria + +1. **Real-time Performance**: Smooth 30fps positioning updates without lag +2. **ESP32 Compatibility**: Reliable connection to all ESP32 USB-to-Serial chips +3. **Data Processing**: Handle 10,000+ positioning points without performance issues +4. **User Experience**: Intuitive interface requiring no technical knowledge +5. **Accuracy**: <1cm coordinate display precision in webapp visualization +6. **Reliability**: 99%+ uptime during mapping sessions with graceful error handling +7. **Cross-platform**: Works on Windows, macOS, Linux with same feature set + +--- + +**Current Status**: Phase 1 Complete ✅ - Phase 2 In Development 🚧 + +*Last Updated: 2025-01-20* \ No newline at end of file