username/esp32-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add project documentation

Browse Source 
- 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
2026-02-05 21:06:05 +01:00
parent a8f616970a
commit e6e7b622b2
8 changed files with 571 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
README.md
View File

@@ -5,7 +5,10 @@ REST API backend for ESP32 sensor fleet (OPSEC/OSINT/Purple team).
## Quick Start
```bash
# Install
# Clone and install
cd ~/git/esp32-web
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Initialize database
@@ -13,11 +16,40 @@ flask --app src/esp32_web db init
flask --app src/esp32_web db migrate -m "initial"
flask --app src/esp32_web db upgrade
# Run development server
make dev
# Start server
make start
make status
```
## Ports
## 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 |
|------|----------|-------------|
@@ -25,33 +57,12 @@ make dev
| 5500 | UDP | Sensor data collector |
| 5501 | UDP | Sensor commands (outbound) |
## API Endpoints
## Documentation
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| 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 |
| 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 |
| GET | `/api/v1/stats` | Statistics |
- [Installation](docs/INSTALL.md)
- [Usage Guide](docs/USAGE.md)
- [Cheatsheet](docs/CHEATSHEET.md)
## Container
## License
```bash
make build
make run
make logs
make stop
```
## Testing
```bash
make test
```
MIT