feat: Add project docs - PROJECT, ROADMAP, TASKS, TODO, .gitignore

.gitignore

@@ -0,0 +1,5 @@
+build/
+managed_components/
+sdkconfig.old
+*.pyc
+__pycache__/

PROJECT.md

@@ -0,0 +1,47 @@
+# ESP32 Hacking Project
+
+## Overview
+Firmware customization and experimentation for ESP32 CSI (Channel State Information) sensors used in the [wifi-sensing](~/git/wifi-sensing/) project.
+
+## Goals
+- Document current firmware and configuration
+- Add remote management commands (reboot, identify, status)
+- Implement OTA firmware updates
+- Explore BLE scanning for complementary presence detection
+- Optimize CSI data pipeline (adaptive rate, on-device processing)
+
+## Current State
+- 3x ESP32-DevKitC V1 deployed with stock `csi_recv_router` firmware
+- Firmware sends raw CSI data via UDP at ~100 pkt/s per device
+- No remote management capability (must physically access USB)
+
+## Hardware
+| Device | Chip | IP Address | Location |
+|--------|------|------------|----------|
+| muddy-storm | ESP32-WROOM-32 | 192.168.129.29 | Living Room |
+| amber-maple | ESP32-WROOM-32 | 192.168.129.30 | Office |
+| hollow-acorn | ESP32-WROOM-32 | 192.168.129.31 | Kitchen |
+
+## Software Stack
+| Component | Version | Purpose |
+|-----------|---------|---------|
+| ESP-IDF | v5.x | Development framework |
+| esp-csi | latest | CSI extraction library |
+| FreeRTOS | (bundled) | RTOS kernel |
+
+## Key Paths
+| Path | Description |
+|------|-------------|
+| `~/git/esp32-hacking/` | This project (firmware sources, docs) |
+| `~/git/wifi-sensing/` | Server application (receives CSI data) |
+| `~/esp/esp-idf/` | ESP-IDF toolchain |
+| `~/esp/esp-csi/` | Original esp-csi repo (build from here) |
+
+## Dependencies
+- ESP-IDF toolchain (`~/esp/esp-idf/`)
+- USB cable for initial flash (OTA planned)
+
+## References
+- [ESP-IDF Docs](https://docs.espressif.com/projects/esp-idf/en/latest/)
+- [ESP-CSI GitHub](https://github.com/espressif/esp-csi)
+- [ESP32 WiFi CSI API](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html)

ROADMAP.md

@@ -0,0 +1,50 @@
+# ESP32 Hacking Roadmap
+
+## v0.1 - Documentation & Setup [CURRENT]
+- [x] Copy firmware sources from esp-csi
+- [x] Document current firmware behavior
+- [x] Document CSI data format
+- [x] Document build & flash process
+- [x] List firmware modification ideas with priorities
+- [ ] Create development workflow (build, flash, test cycle)
+
+## v0.2 - Remote Management
+- [ ] Add UDP command listener on ESP32
+- [ ] Implement REBOOT command
+- [ ] Implement IDENTIFY command (blink LED)
+- [ ] Implement STATUS command (uptime, heap, RSSI, temp)
+- [ ] Implement RATE command (change sampling rate)
+- [ ] Add LED status indicator (connected/sending/error)
+- [ ] Pi-side command sender script
+
+## v0.3 - OTA Updates
+- [ ] Modify partition table for dual OTA
+- [ ] Add OTA update handler in firmware
+- [ ] HTTP firmware server on Pi
+- [ ] Pi-side flash script (select device, push firmware)
+- [ ] Rollback on failed update
+
+## v0.4 - Adaptive Sampling
+- [ ] On-device wander calculation (simplified)
+- [ ] Reduce to 10 pkt/s when idle
+- [ ] Increase to 100 pkt/s on motion detection
+- [ ] Rate change notification to Pi
+
+## v0.5 - BLE Scanning
+- [ ] Enable Bluetooth alongside WiFi
+- [ ] Periodic BLE advertisement scanning
+- [ ] Report device MAC, RSSI, name via UDP
+- [ ] Pi-side BLE device tracking
+
+## v1.0 - Production Firmware
+- [ ] mDNS auto-discovery
+- [ ] Watchdog + auto-recovery
+- [ ] On-device CSI processing (send metrics, not raw)
+- [ ] Configuration via UDP (WiFi SSID, target IP)
+- [ ] Comprehensive error handling
+
+## Future
+- ESP-NOW mesh (ESP32-to-ESP32 CSI)
+- Multi-channel scanning
+- External sensor support (PIR, temp/humidity via GPIO)
+- Power management for battery operation

TASKS.md

@@ -0,0 +1,22 @@
+# ESP32 Hacking Tasks
+
+**Last Updated:** 2026-02-04
+
+## Current Sprint: v0.1 - Documentation
+
+### P0 - Critical
+- [x] Copy firmware sources to project
+- [x] Document current firmware and settings
+
+### P1 - Important
+- [ ] Document build & flash workflow step by step
+- [ ] Create .gitignore for build artifacts
+- [ ] Test building firmware from this repo
+
+### P2 - Normal
+- [ ] Document CSI config options (what each sdkconfig flag does)
+- [ ] Compare csi_recv vs csi_recv_router differences
+
+### P3 - Low
+- [ ] Document esp-crab dual-antenna capabilities
+- [ ] Document esp-radar console features

TODO.md

@@ -0,0 +1,36 @@
+# ESP32 Hacking TODO
+
+## Firmware Features
+- [ ] UDP command listener (reboot, identify, status, rate)
+- [ ] LED status indicator
+- [ ] OTA firmware updates
+- [ ] Adaptive sampling rate
+- [ ] BLE scanning
+- [ ] mDNS auto-discovery
+- [ ] On-device wander calculation
+- [ ] Chip temperature reporting
+- [ ] WiFi reconnect on disconnect
+- [ ] Configurable target IP/port via command
+
+## Tools
+- [ ] `esp-cmd` CLI tool to send commands to sensors
+- [ ] Flash script for OTA updates
+- [ ] Sensor discovery script (find all ESP32s on network)
+
+## Testing
+- [ ] Benchmark: CSI callback latency
+- [ ] Benchmark: UDP throughput at different rates
+- [ ] Test: WiFi reconnect reliability
+- [ ] Test: BLE + WiFi coexistence impact on CSI
+
+## Documentation
+- [ ] Pin mapping for ESP32-DevKitC V1
+- [ ] Memory usage analysis (heap, stack)
+- [ ] Power consumption measurements
+- [ ] Compare CSI quality: passive (router) vs active (ESP-NOW)
+
+## Ideas
+- ESP-NOW mesh for direct ESP32-to-ESP32 CSI
+- External PIR sensor for CSI ground truth validation
+- Battery + deep sleep mode for portable deployment
+- Web-based firmware configurator (WiFi credentials, UDP target)