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
This commit is contained in:
user
97
docs/CHEATSHEET.md
Normal file
97
docs/CHEATSHEET.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# ESP32-Web Cheatsheet
|
||||
|
||||
## Server Management
|
||||
|
||||
```bash
|
||||
make start # Start server
|
||||
make stop # Stop server
|
||||
make restart # Restart server
|
||||
make status # Show PID + uptime
|
||||
make logs # Tail logs
|
||||
make dev # Run with debug mode
|
||||
```
|
||||
|
||||
## Database
|
||||
|
||||
```bash
|
||||
make migrate # Apply migrations
|
||||
make migrate-init # Initialize migrations
|
||||
make migrate-create msg="description" # Create migration
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
make test # Run all tests
|
||||
pytest -v # Verbose output
|
||||
pytest -k test_sensors # Run specific tests
|
||||
```
|
||||
|
||||
## Container
|
||||
|
||||
```bash
|
||||
make build # Build image
|
||||
make container-run # Run container
|
||||
make container-stop # Stop container
|
||||
make container-logs # View logs
|
||||
```
|
||||
|
||||
## API Quick Reference
|
||||
|
||||
```bash
|
||||
# Health
|
||||
curl localhost:5500/health
|
||||
|
||||
# Sensors
|
||||
curl localhost:5500/api/v1/sensors
|
||||
curl localhost:5500/api/v1/sensors/HOSTNAME
|
||||
curl -X POST localhost:5500/api/v1/sensors/HOSTNAME/command -H "Content-Type: application/json" -d '{"command":"STATUS"}'
|
||||
|
||||
# Devices
|
||||
curl localhost:5500/api/v1/devices
|
||||
curl "localhost:5500/api/v1/devices?type=ble&limit=50"
|
||||
curl localhost:5500/api/v1/devices/MAC
|
||||
|
||||
# Alerts
|
||||
curl localhost:5500/api/v1/alerts
|
||||
curl "localhost:5500/api/v1/alerts?type=deauth&hours=48"
|
||||
|
||||
# Events
|
||||
curl localhost:5500/api/v1/events
|
||||
curl "localhost:5500/api/v1/events?type=presence"
|
||||
|
||||
# Probes
|
||||
curl localhost:5500/api/v1/probes
|
||||
curl localhost:5500/api/v1/probes/ssids
|
||||
|
||||
# Stats
|
||||
curl localhost:5500/api/v1/stats
|
||||
```
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Endpoints | Description |
|
||||
|-----------|-----------|-------------|
|
||||
| type | devices, alerts, events | Filter by type |
|
||||
| hours | alerts, events, probes | Time window (default: 24) |
|
||||
| limit | devices, alerts, events, probes | Max results (default: 100) |
|
||||
| offset | devices, alerts, events, probes | Skip N results |
|
||||
| ssid | probes | Filter by SSID |
|
||||
| sensor_id | alerts, events | Filter by sensor |
|
||||
|
||||
## Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `/tmp/esp32-web.pid` | Server PID file |
|
||||
| `/tmp/esp32-web.log` | Server log file |
|
||||
| `instance/esp32.db` | SQLite database |
|
||||
| `.env` | Environment config |
|
||||
|
||||
## Ports
|
||||
|
||||
| Port | Protocol | Description |
|
||||
|------|----------|-------------|
|
||||
| 5500 | TCP | HTTP API |
|
||||
| 5500 | UDP | Sensor data |
|
||||
| 5501 | UDP | Sensor commands |
|
||||
76
docs/INSTALL.md
Normal file
76
docs/INSTALL.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Installation
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.11+
|
||||
- pip
|
||||
- SQLite (included) or PostgreSQL
|
||||
|
||||
## Development Setup
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
cd ~/git/esp32-web
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install with dev dependencies
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Initialize database
|
||||
flask --app src/esp32_web db init
|
||||
flask --app src/esp32_web db migrate -m "initial"
|
||||
flask --app src/esp32_web db upgrade
|
||||
|
||||
# Verify installation
|
||||
make test
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Copy `.env.example` to `.env` and adjust:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| SECRET_KEY | dev-key | Flask secret key |
|
||||
| DATABASE_URL | sqlite:///esp32.db | Database connection |
|
||||
| UDP_PORT | 5500 | UDP collector port |
|
||||
| CMD_PORT | 5501 | Sensor command port |
|
||||
| SENSOR_TIMEOUT | 60 | Seconds before sensor marked offline |
|
||||
|
||||
## Container Deployment
|
||||
|
||||
```bash
|
||||
# Build image
|
||||
make build
|
||||
|
||||
# Run container
|
||||
make container-run
|
||||
|
||||
# View logs
|
||||
make container-logs
|
||||
|
||||
# Stop container
|
||||
make container-stop
|
||||
```
|
||||
|
||||
## Production
|
||||
|
||||
For production, use gunicorn:
|
||||
|
||||
```bash
|
||||
gunicorn -b 0.0.0.0:5500 -w 4 'esp32_web:create_app()'
|
||||
```
|
||||
|
||||
With PostgreSQL:
|
||||
|
||||
```bash
|
||||
export DATABASE_URL="postgresql://user:pass@localhost/esp32web"
|
||||
flask --app src/esp32_web db upgrade
|
||||
```
|
||||
141
docs/USAGE.md
Normal file
141
docs/USAGE.md
Normal file
@@ -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 |
|
||||
Reference in New Issue
Block a user