# ESP32 Hacking Project

## Overview

Firmware and tooling for ESP32 CSI (Channel State Information) sensors used for passive wireless sensing, device tracking, and security monitoring (OPSEC/OSINT/Purple team).

## Goals

- Custom ESP32 firmware with remote management, OTA updates, adaptive sampling
- BLE scanning and WiFi probe/deauth detection for device intelligence
- CSI-based presence detection without cameras
- Flask REST API backend for data aggregation and OSINT queries
- Fleet management for multiple sensors

## Components

| Component | Location | Description |
|-----------|----------|-------------|
| Firmware | `get-started/csi_recv_router/` | ESP32 sensor firmware (C, ESP-IDF) |
| CLI Tools | `~/git/esp-tools/` | `esp-ctl`, `esp-fleet`, `esp-ota` |
| Flask API | `~/git/esp32-web/` | REST API backend (v0.1.5, Python, Flask) |

## Current State

### Firmware: v1.11.0 (+ unreleased v1.12 changes)

- 3x ESP32-DevKitC V1 deployed with custom firmware
- 31 UDP commands (ALERT, HELP, CONFIG, FACTORY, STATUS, PING, LOG, CSI, CALIBRATE, PRESENCE, ...)
- 28 NVS-persisted configuration keys
- UDP data streams: CSI_DATA, BLE_DATA, PROBE_DATA, ALERT_DATA, EVENT
- Remote management via UDP commands (port 5501)
- OTA firmware updates (HTTP/HTTPS) with rollback
- Presence detection via CSI baseline calibration
- Multi-channel scanning for broader WiFi coverage
- BLE fingerprinting (company_id, tx_power, flags)
- LED quiet mode (default off, solid on motion/presence)

### Web Backend: v0.1.5

- Flask + SQLAlchemy + SQLite (WAL mode)
- UDP collector (all 5 sensor streams)
- REST API: sensors, devices, alerts, probes, events, stats, export, zones
- Intelligence dashboard: vendor treemap, SSID graph, fingerprint clusters, presence timeline
- 3D floorplan, OpenAPI/Swagger, 77 tests passing

## 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 |

## Network Ports

| Port | Protocol | Direction | Description |
|------|----------|-----------|-------------|
| 5500 | UDP | Sensors → Flask | Sensor data streams (CSI, BLE, probes, alerts, events) |
| 5500 | TCP | Clients → Flask | REST API (HTTP) |
| 5501 | UDP | Flask → Sensors | Sensor commands |

## Data Streams (UDP 5500)

| Stream | Format | Use Case |
|--------|--------|----------|
| CSI_DATA | hostname,count,mac,rssi,... | Motion/presence detection |
| BLE_DATA | hostname,mac,rssi,type,name,company_id,tx_power,flags | Device fingerprinting |
| PROBE_DATA | hostname,mac,rssi,ssid,channel | Device tracking, SSID enumeration |
| ALERT_DATA | hostname,type,source,target,rssi | Wireless IDS (deauth detection) |
| EVENT | hostname,key=value pairs | Motion, presence, calibration events |

## Software Stack

| Component | Version | Purpose |
|-----------|---------|---------|
| ESP-IDF | v5.5.2 | Firmware development framework |
| Flask | 3.x | REST API backend |
| SQLAlchemy | 2.x | Database ORM |
| SQLite/PostgreSQL | - | Data storage |
| podman | - | Container runtime |

## Key Paths

| Path | Description |
|------|-------------|
| `~/git/esp32-hacking/` | This project (firmware sources, docs) |
| `~/git/esp32-web/` | Flask API backend (v0.1.5) |
| `~/git/esp-tools/` | CLI tools (esp-ctl, esp-fleet, esp-ota) |
| `~/esp/esp-idf/` | ESP-IDF toolchain |

## API Endpoints

Base URL: `http://<host>:5500/api/v1`

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/sensors` | List sensors with status |
| GET | `/sensors/<id>` | Sensor detail |
| GET | `/sensors/<id>/config` | Sensor configuration |
| PUT | `/sensors/<id>/config` | Update sensor config |
| POST | `/sensors/<id>/command` | Send UDP command |
| POST | `/sensors/<id>/ota` | Trigger OTA update |
| POST | `/sensors/<id>/calibrate` | Trigger calibration |
| GET | `/devices` | List discovered devices |
| GET | `/devices/<id>` | Device detail |
| GET | `/alerts` | Alert feed with filters |
| GET | `/probes` | Probe requests |
| GET | `/events` | Sensor events |
| GET | `/stats` | Aggregate statistics |
| GET | `/zones` | List zones |
| POST | `/zones` | Create zone |
| PUT | `/zones/<id>` | Update zone |
| GET | `/export/devices.csv` | Export devices |
| GET | `/intelligence/*` | Vendor treemap, SSID graph, fingerprints, presence |

## References

- [ESP-IDF Docs](https://docs.espressif.com/projects/esp-idf/en/latest/)
- [ESP-CSI GitHub](https://github.com/espressif/esp-csi)
- [IEEE OUI Database](https://standards-oui.ieee.org/)
- [Bluetooth Company Identifiers](https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/)