156 lines
6.2 KiB
Markdown
156 lines
6.2 KiB
Markdown
# adacam-api
|
|
|
|
A small, readable **Python/Flask on-device API** for dashcams in the Hivemapper
|
|
Bee (HDC-S) family. It is a clean-room, open replacement for the device's
|
|
stock `odc-api` — a large Node.js service — reduced to a few hundred lines of
|
|
Python that are easy to audit, modify, and self-host.
|
|
|
|
> Independent open-source project. Not affiliated with, endorsed by, or
|
|
> supported by Hivemapper. "Hivemapper" and "Bee" are used only to describe
|
|
> hardware compatibility.
|
|
|
|
The API runs locally on the device and exposes a small HTTP surface that a
|
|
companion app (or any HTTP client) can use to read GPS, list recent landmark
|
|
detections, check device status, configure WiFi/SSH, and optionally forward
|
|
detections to a map-ingest backend.
|
|
|
|
## Features
|
|
|
|
- **Landmark store + forwarder** — detections are written to a local SQLite
|
|
database and forwarded to a configurable map-ingest API. Forwarding is
|
|
resilient: anything that fails while the device is offline is queued and
|
|
retried by a background thread.
|
|
- **GPS** — reads the latest fix from the device's on-disk recording database
|
|
(`odc-api.db`, `framekms` table), with a Redis fallback for live fixes.
|
|
- **Device control** — WiFi client connect/status, SSH enable/disable, and
|
|
device status/identity endpoints.
|
|
- **WiGLE** — optional wardriving status, stats, and configuration endpoints.
|
|
- **Token auth + pairing** — control endpoints require a bearer token. The
|
|
token is a high-entropy random secret stored on the device; clients obtain it
|
|
through a one-shot, physically-gated pairing window (see
|
|
[Authentication](#authentication)).
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Auth | Description |
|
|
|--------|------|------|-------------|
|
|
| GET | `/api/1/landmarks/last/{N}` | no | Last N detections |
|
|
| POST | `/api/1/landmarks` | yes | Ingest a new detection |
|
|
| GET | `/api/1/gnssConcise/latestValid` | no | Current GPS fix |
|
|
| GET | `/api/1/status` | no | Device status (firmware, uptime, GPS lock) |
|
|
| GET | `/api/1/deviceinfo` | no | Device identity |
|
|
| GET | `/api/1/recording/frames/latest` | no | Path to the most recent frame |
|
|
| GET | `/api/1/info` | no | Device serial + AP info |
|
|
| GET | `/pair` | no* | One-shot pairing — returns the API token while the window is open |
|
|
| GET | `/api/1/wifi/status` | no | WiFi client status |
|
|
| POST | `/api/1/wifi/connect` | yes | Connect to a WiFi network |
|
|
| GET | `/api/1/ssh/status` | no | SSH daemon status |
|
|
| POST | `/api/1/ssh/toggle` | yes | Enable/disable SSH |
|
|
| GET | `/api/1/wigle/status` | no | WiGLE service status |
|
|
| GET | `/api/1/wigle/stats` | no | WiGLE statistics |
|
|
| GET | `/api/1/wigle/config` | no | WiGLE config (secrets masked) |
|
|
| POST | `/api/1/wigle/config` | yes | Update WiGLE config |
|
|
| GET | `/api/1/debug/redis-keys` | yes | List Redis keys (GPS troubleshooting) |
|
|
|
|
`*` `/pair` only returns the token while a pairing window is open; otherwise it
|
|
returns `403`.
|
|
|
|
> Note: there is intentionally no remote command-execution endpoint. The stock
|
|
> firmware's `/api/1/cmd` (the source of a known CVE) is deliberately not
|
|
> implemented here.
|
|
|
|
## Quick start
|
|
|
|
Requirements:
|
|
|
|
- Python 3.8+
|
|
- Redis (optional — used as a live-GPS fallback)
|
|
- `flask`, `redis`, `requests` (see `requirements.txt`)
|
|
|
|
Run it locally:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
python main.py # serves on 0.0.0.0:5000
|
|
```
|
|
|
|
Install on a device (copies files to `/opt/adacam`, installs the pairing
|
|
helper, and enables a systemd service):
|
|
|
|
```bash
|
|
./install.sh
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Config lives at `/data/adacam/config.json` and is created with defaults on
|
|
first start. A device ID (UUID) is generated automatically.
|
|
|
|
```json
|
|
{
|
|
"device_id": "auto-generated UUID",
|
|
"adamaps_key": "<map-ingest API key>",
|
|
"adamaps_api": "https://api.adamaps.org",
|
|
"ap_interface": "wlp1s0f0",
|
|
"tunnel_host": "",
|
|
"tunnel_user": "",
|
|
"tunnel_port": 2222
|
|
}
|
|
```
|
|
|
|
- `adamaps_api` / `adamaps_key` — the upstream map-ingest endpoint and its API
|
|
key. Point these at your own backend; detections are POSTed to
|
|
`<adamaps_api>/api/ingest` with the key in an `X-AdaMaps-Key` header.
|
|
- `ap_interface` — the device's access-point network interface.
|
|
|
|
The API key can be required from the environment instead of being stored
|
|
inline; in that case the service refuses to start until it is set.
|
|
|
|
## Authentication
|
|
|
|
Read-only endpoints are open; control endpoints (WiFi connect, SSH toggle,
|
|
WiGLE config, landmark ingest) require an `Authorization: Bearer <token>`
|
|
header.
|
|
|
|
The token is **not** derived from any public identifier. On first use the
|
|
device generates a random `secrets.token_urlsafe(32)` value, stores it at
|
|
`/data/adacam/api_token` (mode `600`), and compares it in constant time.
|
|
|
|
Clients obtain the token through a **one-shot pairing window**:
|
|
|
|
```
|
|
device: adacam-pair # opens the window (physical/SSH presence)
|
|
client: GET /pair -> { serial, token, ... } # window closes on success
|
|
client: stores token; sends it on all control calls
|
|
```
|
|
|
|
`install.sh` opens the window once on a fresh provision so the first pair works
|
|
out of the box. To re-pair (new client, reset), run `adacam-pair` on the device
|
|
again.
|
|
|
|
## Development
|
|
|
|
The code is a standard Flask app factory (`adacam_api/app.py`) with route
|
|
blueprints under `adacam_api/routes/`. There are no build steps — edit and
|
|
restart.
|
|
|
|
```
|
|
adacam_api/
|
|
app.py # app factory + pairing/wifi/ssh/debug routes
|
|
auth.py # bearer token + pairing window
|
|
config.py # JSON config load/save
|
|
db.py # SQLite: landmarks + offline forward queue
|
|
forwarder.py # background map-ingest forwarder with retry
|
|
redis_client.py # GPS reader (SQLite primary, Redis fallback)
|
|
routes/ # landmarks, gnss, status, frames, wigle blueprints
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Issues and pull requests are welcome. Please keep changes small and focused,
|
|
match the existing style, and avoid adding heavy dependencies — the goal is a
|
|
service small enough to read in one sitting.
|
|
|
|
## License
|
|
|
|
AGPL-3.0-or-later — see [LICENSE](LICENSE).
|