e6e7b622b2
- 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
142 lines
2.6 KiB
Markdown
142 lines
2.6 KiB
Markdown
# 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 |
|