docs: add RECON.md — schema, architecture, diagnostic findings
This commit is contained in:
parent
76b177a8e0
commit
91d26e436e
1 changed files with 136 additions and 0 deletions
136
docs/RECON.md
Normal file
136
docs/RECON.md
Normal file
|
|
@ -0,0 +1,136 @@
|
|||
# adacam — Recon & Architecture Notes
|
||||
|
||||
> Read this FIRST before any diagnostic or dev work. Last updated: 2026-03-29.
|
||||
|
||||
---
|
||||
|
||||
## Service: adacam-odc
|
||||
|
||||
**Source:** `services/adacam-odc/adacam_odc.py`
|
||||
**Running as:** `/data/adacam/adacam_odc.py` (deployed to camera)
|
||||
**Port:** 5000 (Flask API)
|
||||
|
||||
### What it does
|
||||
Combined service — two threads:
|
||||
- **Thread 1 (Flask API):** HTTP server on port 5000 — landmarks, GPS, health, forwarder status, device config
|
||||
- **Thread 2 (Forwarder):** Polls SQLite, batches detections, POSTs to ADAMaps API. Checks internet (8.8.8.8:53) before each cycle. Exponential backoff on failure, max 5 min.
|
||||
|
||||
### What it does NOT do
|
||||
- Does not touch the AI/ML stack
|
||||
- Does not process camera frames
|
||||
- Does not interact with here-plugin or Hivemapper upload pipeline
|
||||
- Does not use port 5500 (that was a wrong guess — ignore it)
|
||||
|
||||
### Data pipeline
|
||||
```
|
||||
camera -> map-ai -> SQLite (landmarks table in odc-api.db) -> adacam-odc forwarder -> ADAMaps API
|
||||
```
|
||||
map-ai writes directly to SQLite. adacam-odc reads from it.
|
||||
|
||||
---
|
||||
|
||||
## Key Paths (on camera)
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `/data/recording/odc-api.db` | Main SQLite DB — landmarks, frames, framekms |
|
||||
| `/data/recording/redis_handler/fusion-v*.db` | GNSS/fusion data |
|
||||
| `/data/recording/redis_handler/sensors-v*.db` | Sensor data |
|
||||
| `/data/recording/cached_observations/` | Detection images |
|
||||
| `/data/adacam/config.json` | adacam-odc config (device_id, API URL, poll interval) |
|
||||
| `/data/adacam/forwarder_state.json` | Cursor state (last_detection_id, totals) |
|
||||
| `/data/adacam/forwarder.log` | Forwarder log |
|
||||
| `/data/recording/framekm/` | Raw framekm files (auto-purged after 10 days) |
|
||||
|
||||
---
|
||||
|
||||
## Database Schema (odc-api.db)
|
||||
|
||||
### landmarks table (primary)
|
||||
```
|
||||
id, ts, map_feature_id, framekm_id, image_name, image_id,
|
||||
class_id, class_label, speed_label, speed_label_conf,
|
||||
distance, x_center, y_center, lat, lon, alt, azimuth,
|
||||
width, height, pitch, roll, yaw, confidence,
|
||||
x1, y1, x2, y2, cam_lat, cam_lon, cam_heading,
|
||||
track_id, attributes, model_id, model_hash
|
||||
```
|
||||
|
||||
### Other tables
|
||||
frames, framekms, config — standard Hivemapper Bee schema.
|
||||
|
||||
**There is NO `ai_events_vision` table. Do not look for it.**
|
||||
|
||||
---
|
||||
|
||||
## Forwarder State
|
||||
|
||||
`/data/adacam/forwarder_state.json` format:
|
||||
```json
|
||||
{
|
||||
"last_detection_id": 229787,
|
||||
"last_image_id": 222654,
|
||||
"total_forwarded": 7814,
|
||||
"total_images": 2921,
|
||||
"last_run": 1774216692.601199
|
||||
}
|
||||
```
|
||||
- `last_detection_id` = cursor into landmarks table. Forwarder picks up WHERE id > this value.
|
||||
- Compare to `SELECT MAX(id) FROM landmarks` to see if there is a backlog.
|
||||
|
||||
---
|
||||
|
||||
## Network Layout (on camera)
|
||||
|
||||
| Interface | Purpose |
|
||||
|-----------|---------|
|
||||
| `wlp1s0f0` | AP (192.168.0.10) — SSH access from dashcam AP |
|
||||
| `wlp1s0f1` | WiFi client — home LAN, internet access |
|
||||
|
||||
SSH is only reachable on the AP interface (192.168.0.10), not from home LAN directly.
|
||||
|
||||
**Access path:**
|
||||
1. `ssh cobb@192.168.0.184` (blackbox Pi, eth0)
|
||||
2. Connect wlan0 to dashcam AP: `sudo wpa_supplicant -B -i wlan0 -c /tmp/dashcam.conf`
|
||||
3. Force route: `sudo ip route add 192.168.0.10/32 dev wlan0`
|
||||
4. `ssh root@192.168.0.10`
|
||||
|
||||
**dashcam AP:** SSID `dashcam-4A928016A02C1046`, password `hivemapper`, channel 36 (5GHz)
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic Finding — 2026-03-29
|
||||
|
||||
**Root cause of forwarding stoppage (Mar 23):** DNS broken.
|
||||
|
||||
- WiFi UP, IP connectivity fine (ping 8.8.8.8 works)
|
||||
- `api.adamaps.org` fails to resolve — "bad address"
|
||||
- systemd-resolved running but not resolving external hostnames
|
||||
- Forwarder died on timeouts Mar 23, service restarted Mar 26 but DNS still broken
|
||||
- Directly overwriting `/etc/resolv.conf` does not stick — systemd-resolved manages it
|
||||
|
||||
**State as of 2026-03-29:**
|
||||
- DB: 2,488 landmarks, cursor at max ID 229787 (no backlog — all forwarded)
|
||||
- map-ai: running, last detection Mar 24 (car not driven since)
|
||||
- Forwarder: not cycling (DNS dead)
|
||||
- Total forwarded lifetime: 7,814 detections, 2,921 images
|
||||
|
||||
**Fix needed (not yet applied — awaiting approval):**
|
||||
Add `DNS=8.8.8.8` to `/etc/systemd/resolved.conf` and restart systemd-resolved.
|
||||
Do NOT directly overwrite `/etc/resolv.conf`.
|
||||
|
||||
---
|
||||
|
||||
## ADAMaps API
|
||||
|
||||
- Endpoint: `https://api.adamaps.org`
|
||||
- Ingest: `POST /api/ingest` with `X-AdaMaps-Key` header
|
||||
- Images: `POST /api/images`
|
||||
- Auth key: in `/data/adacam/config.json` (`adamaps_key`)
|
||||
- Health: `GET /api/health`
|
||||
|
||||
---
|
||||
|
||||
## Redis
|
||||
|
||||
Used only for `MAP_AI_READY` health flag. No detection IPC.
|
||||
Loading…
Add table
Add a link
Reference in a new issue