MAUWB-platformiotest/docs/ROADMAP.md

# Indoor Positioning System Roadmap
**MaUWB ESP32-S3 Warehouse Positioning & WiFi Mapping System**

---

## 🎯 Project Overview

**Purpose**: Indoor positioning system for warehouse WiFi strength mapping
- **Hardware**: 1 mobile tag + 8+ battery-powered anchors
- **Connectivity**: Tag connects to PC via USB, anchors are wireless-only
- **Constraint**: Tag connects to 8 closest anchors (auto-switching)
- **Goal**: Quick installation (<15 min) with automatic anchor positioning

---

## 📋 System Requirements

### Hardware Components
- [ ] **Tag Device**: ESP32-S3 with USB connectivity
- [ ] **Anchor Devices**: 8+ ESP32-S3 units (battery powered)
- [ ] **PC Interface**: USB connection for data collection
- [ ] **Power Management**: Battery-powered anchors (no mains/WiFi)

### Core Constraints
- ✅ Battery-powered anchors (no WiFi connectivity)
- ✅ Tag connects to 8 closest anchors (auto-switching)
- ✅ USB-only connection (tag to PC)
- ✅ No WiFi scanning needed (handled by PC)
- ✅ Warehouse too large for simultaneous connection to all anchors

---

## 🏗️ System Architecture

### Data Flow Design
```
Anchors (Battery) → Auto-Position Calibration → Store Coordinates Locally
                                                        ↓
Tag (Mobile) → Collect Raw Data + Anchor Coordinates → PC (USB) → Real-time Display
                                    ↓                                      ↓
                              Two Log Files                        Live Position View
                                    ↓
                            Web Application
                         (Load both files)
```

### Critical Problem Solved
**Challenge**: How do battery-powered anchors transmit calibrated positions to PC?
**Solution**: Dual-file approach - Tag logs raw positioning data + anchor coordinates separately, webapp loads both files for offline processing

---

## 🚀 Implementation Roadmap

### Phase 1: Anchor Auto-Positioning System
**Duration**: 2-3 weeks

#### 1.1 Distributed Positioning Algorithm
- [ ] **Anchor Discovery Protocol**
  - All anchors broadcast discovery signals on startup
  - Build neighbor discovery table for each anchor
  - Implement range-based network topology mapping

- [ ] **Distance Measurement Matrix**
  - Each anchor measures distances to all neighbors in range
  - Store distance measurements locally (EEPROM/flash)
  - Handle partial connectivity (not all anchors can reach each other)

- [ ] **Coordinate System Establishment**
  - Designate anchor with most connections as origin (0,0)
  - Establish coordinate system orientation
  - Implement distributed position calculation algorithm

- [ ] **Position Calculation & Storage**
  - Each anchor calculates its own position using trilateration
  - Store calculated position in local memory
  - Implement position confidence scoring

#### 1.2 Anchor Communication Protocol
- [ ] **Inter-Anchor Data Exchange**
  - Protocol for sharing distance measurements
  - Handle multi-hop communication for distant anchors
  - Implement data consistency checks

- [ ] **Position Refinement**
  - Iterative position improvement algorithm
  - Consensus mechanism for coordinate system alignment
  - Error detection and correction

### Phase 2: Tag Data Relay System
**Duration**: 2 weeks

#### 2.1 Enhanced Tag Functionality
- [ ] **Anchor Discovery & Connection**
  - Scan for available anchors
  - Connect to 8 closest/strongest anchors
  - Implement smooth anchor switching logic

- [ ] **Position Data Collection**
  - Request calibrated positions from connected anchors
  - Aggregate anchor position data
  - Handle missing or incomplete anchor data

- [ ] **Real-time Positioning**
  - Calculate tag position using 8 connected anchors
  - Maintain position continuity during anchor handoffs
  - Implement position smoothing/filtering

#### 2.2 Tag Data Logging System
- [ ] **Dual-File Logging**
  - **File 1**: Raw positioning data (distances, RSSI, timestamps)
  - **File 2**: Anchor coordinates database (collected from connected anchors)
  - USB transfer to PC for both files

- [ ] **Data Collection Protocol**
  - Request anchor coordinates: "Send me your calibrated position"
  - Anchor responds: {anchor_id, x, y, calibration_confidence}
  - Store coordinates locally and update anchor database file
  - Continue logging raw positioning data as current system does

### Phase 3: PC Software Development
**Duration**: 2 weeks

#### 3.1 Real-time PC Application
- [ ] **USB Communication & Live Display**
  - Receive real-time data stream from tag via USB
  - Parse incoming data: raw distances + anchor coordinates
  - Calculate live tag position using anchor coordinates
  - Display real-time position on 2D map

- [ ] **Live Monitoring Features**
  - Show current tag position with live updates
  - Display connected anchors and their positions
  - Real-time signal strength indicators
  - Live path tracking during mapping session

#### 3.2 Dual-File Logging (Background)
- [ ] **Simultaneous Data Logging**
  - **raw_positioning.csv**: Tag positioning data (distances, RSSI, timestamps)
  - **anchor_coordinates.csv**: Anchor position database
  - Log files generated automatically during real-time session
  - Export files for webapp analysis after session

- [ ] **Data Validation**
  - Verify file integrity and format
  - Check timestamp consistency
  - Validate anchor coordinate data

### Phase 4: Web Visualization Application
**Duration**: 2-3 weeks

#### 4.1 Core Web Interface
- [ ] **Dual-File Upload & Processing**
  - Upload **raw_positioning.csv** and **anchor_coordinates.csv**
  - Parse and correlate both datasets
  - Data validation and error handling
  - Calculate actual tag positions using raw data + anchor coordinates

- [ ] **2D Warehouse Visualization**
  - Display anchor positions from coordinates file
  - Calculate and plot tag path using positioning algorithm
  - Interactive warehouse floor plan with scalable coordinate system

#### 4.2 Path Analysis Features
- [ ] **Path Tracking Visualization**
  - Tag movement path overlay
  - Timeline scrubbing and playback
  - Speed and direction indicators

- [ ] **Data Analysis Tools**
  - Path statistics and metrics
  - Export functionality (images, reports)
  - Comparison between multiple mapping sessions

### Phase 5: System Integration & Optimization
**Duration**: 1-2 weeks

#### 5.1 Quick Installation Workflow
- [ ] **Automated Setup Process**
  - Power-on all anchors simultaneously
  - Auto-discovery and network formation
  - Position calibration and verification
  - Tag pairing and PC connection setup
  - Target: Ready-to-use in <15 minutes

#### 5.2 System Validation
- [ ] **Accuracy Testing**
  - Position accuracy validation
  - Anchor auto-positioning verification
  - End-to-end system testing

- [ ] **Performance Optimization**
  - Battery life optimization for anchors
  - Data transmission efficiency
  - Real-time performance tuning

---

## 🎯 Key Technical Challenges

### 1. Distributed Anchor Positioning
**Challenge**: Anchors must calculate positions without central coordination
**Solution**: Implement distributed trilateration with consensus mechanism

### 2. Data Relay Through Tag
**Challenge**: Getting anchor position data to PC without direct connectivity
**Solution**: Tag acts as mobile bridge collecting and relaying data

### 3. Coordinate System Consistency
**Challenge**: Ensuring all anchors use same coordinate system
**Solution**: Distributed coordinate system establishment protocol

### 4. Anchor Handoff Management
**Challenge**: Smooth positioning during anchor switching
**Solution**: Position continuity algorithms and coordinate system alignment

### 5. Partial Connectivity Handling
**Challenge**: Not all anchors can communicate directly
**Solution**: Multi-hop communication and distributed data sharing

---

## 📦 Deliverables

### Software Components
- [ ] **Enhanced Anchor Firmware** - Auto-positioning and data storage
- [ ] **Enhanced Tag Firmware** - Data relay and USB communication
- [ ] **PC Data Collection Software** - USB interface and logging
- [ ] **Web Visualization Application** - Path analysis and mapping

### Documentation
- [ ] **Installation Guide** - Quick setup procedures
- [ ] **User Manual** - Operation and troubleshooting
- [ ] **Technical Documentation** - API and protocol specifications
- [ ] **Calibration Procedures** - System validation and accuracy testing

### Test Results
- [ ] **Positioning Accuracy Report** - Performance metrics
- [ ] **Battery Life Analysis** - Power consumption data
- [ ] **Installation Time Study** - Setup procedure validation

---

## 🔄 Success Criteria

1. **Installation Time**: Complete system setup in <15 minutes
2. **Positioning Accuracy**: <30cm accuracy in warehouse environment
3. **Battery Life**: Anchors operate >8 hours on single charge
4. **System Reliability**: 99%+ uptime during mapping sessions
5. **Data Integrity**: Complete path tracking with <1% data loss
6. **User Experience**: Simple web interface for path visualization


*Last Updated: 2025-01-19*
*Version: 1.0*