# ESP32-Web

REST API backend for ESP32 sensor fleet (OPSEC/OSINT/Purple team).

## Quick Start

```bash
# Clone and install
cd ~/git/esp32-web
python3 -m venv .venv
source .venv/bin/activate
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

# Start server
make start
make status
```

## Server Management

```bash
make start    # Start server (0.0.0.0:5500)
make stop     # Stop server
make restart  # Restart server
make status   # Show PID + uptime
make logs     # Tail log file
```

## API Endpoints

Base URL: `http://localhost:5500`

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check with uptime |
| GET | `/api/v1/sensors` | List sensors |
| GET | `/api/v1/sensors/<hostname>` | Get sensor |
| POST | `/api/v1/sensors/<hostname>/command` | Send command |
| GET | `/api/v1/devices` | List devices |
| GET | `/api/v1/devices/<mac>` | Get device + sightings |
| GET | `/api/v1/alerts` | List alerts |
| GET | `/api/v1/events` | List events |
| GET | `/api/v1/probes` | List probe requests |
| GET | `/api/v1/probes/ssids` | List SSIDs with counts |
| GET | `/api/v1/stats` | Aggregate statistics |

## Network Ports

| Port | Protocol | Description |
|------|----------|-------------|
| 5500 | TCP | HTTP REST API |
| 5500 | UDP | Sensor data collector |
| 5501 | UDP | Sensor commands (outbound) |

## Documentation

- [Installation](docs/INSTALL.md)
- [Usage Guide](docs/USAGE.md)
- [Cheatsheet](docs/CHEATSHEET.md)

## License

MIT