docs: Add project documentation

- README.md: Quick start, API endpoints, ports - PROJECT.md: Architecture, components, data models - ROADMAP.md: Version milestones (v0.1.x - v1.0.0) - TASKS.md: Current sprint tasks - TODO.md: Backlog items - docs/INSTALL.md: Setup and deployment - docs/USAGE.md: API examples - docs/CHEATSHEET.md: Quick reference
2026-02-05 21:06:05 +01:00
parent a8f616970a
commit e6e7b622b2
8 changed files with 571 additions and 31 deletions
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -0,0 +1,141 @@
+# Usage Guide
+
+## Starting the Server
+
+```bash
+# Activate virtual environment
+cd ~/git/esp32-web
+source .venv/bin/activate
+
+# Start server
+make start
+
+# Check status
+make status
+
+# View logs
+make logs
+```
+
+## API Examples
+
+### Health Check
+
+```bash
+curl http://localhost:5500/health
+```
+
+Response:
+```json
+{"status": "ok", "uptime": "5m23s", "uptime_seconds": 323}
+```
+
+### List Sensors
+
+```bash
+curl http://localhost:5500/api/v1/sensors
+```
+
+Response:
+```json
+{
+  "sensors": [
+    {"id": 1, "hostname": "hollow-acorn", "ip": "192.168.129.31", "status": "online", "last_seen": "..."},
+    {"id": 2, "hostname": "muddy-storm", "ip": "192.168.129.29", "status": "online", "last_seen": "..."}
+  ]
+}
+```
+
+### Get Sensor Details
+
+```bash
+curl http://localhost:5500/api/v1/sensors/hollow-acorn
+```
+
+### Send Command to Sensor
+
+```bash
+curl -X POST http://localhost:5500/api/v1/sensors/hollow-acorn/command \
+  -H "Content-Type: application/json" \
+  -d '{"command": "STATUS"}'
+```
+
+### List Devices
+
+```bash
+# All devices
+curl http://localhost:5500/api/v1/devices
+
+# BLE devices only
+curl "http://localhost:5500/api/v1/devices?type=ble"
+
+# With pagination
+curl "http://localhost:5500/api/v1/devices?limit=50&offset=0"
+```
+
+### Get Device Details
+
+```bash
+curl http://localhost:5500/api/v1/devices/aa:bb:cc:dd:ee:ff
+```
+
+### List Alerts
+
+```bash
+# Last 24 hours (default)
+curl http://localhost:5500/api/v1/alerts
+
+# Last 7 days
+curl "http://localhost:5500/api/v1/alerts?hours=168"
+
+# Filter by type
+curl "http://localhost:5500/api/v1/alerts?type=deauth"
+```
+
+### List Probe Requests
+
+```bash
+# All probes
+curl http://localhost:5500/api/v1/probes
+
+# Filter by SSID
+curl "http://localhost:5500/api/v1/probes?ssid=MyNetwork"
+
+# List SSIDs with counts
+curl http://localhost:5500/api/v1/probes/ssids
+```
+
+### Get Statistics
+
+```bash
+curl http://localhost:5500/api/v1/stats
+```
+
+Response:
+```json
+{
+  "sensors": {"total": 3, "online": 3},
+  "devices": {"total": 42, "ble": 35, "wifi": 7},
+  "alerts": {"count": 5, "hours": 24},
+  "events": {"count": 128, "hours": 24},
+  "probes": {"count": 89, "hours": 24}
+}
+```
+
+## Allowed Sensor Commands
+
+Commands that can be sent via the API:
+
+| Command | Description |
+|---------|-------------|
+| STATUS | Get sensor status |
+| REBOOT | Reboot sensor |
+| IDENTIFY | Flash LED for 5 seconds |
+| BLE ON/OFF | Toggle BLE scanning |
+| ADAPTIVE ON/OFF | Toggle adaptive sampling |
+| RATE <10-100> | Set CSI rate |
+| POWER <2-20> | Set TX power (dBm) |
+| CSIMODE RAW/COMPACT/HYBRID | Set CSI output mode |
+| PRESENCE ON/OFF | Toggle presence detection |
+| CALIBRATE [seconds] | Start baseline calibration |
+| CHANSCAN ON/OFF/NOW | Channel scanning |