add master technical report for ADAMaps project

This commit is contained in:
kayos 2026-03-22 11:09:36 -07:00
parent 248a9b6cd1
commit 07d1273618

View file

@ -0,0 +1,582 @@
# ADAMaps Project — Master Technical Report
**Date:** 2026-03-22
**Prepared by:** Kayos (OpenClaw Agent)
**For:** Jacob Hayes (Cobb)
**Classification:** Internal — Sulkta Cooperative
---
## Executive Summary
This report consolidates all technical knowledge regarding the ADAMaps decentralized road mapping platform, the Hivemapper Bee dashcam liberation project, and the current infrastructure state. It serves as the single source of truth for the project.
### Key Findings
1. **Bee Hardware**: Intel Keem Bay SoC (ARM Cortex-A53 + Movidius VPU), Sony IMX412 camera, dual WiFi radios, LTE modem
2. **Detection Storage**: Files in `/data/recording/landmarks/*.json` — NOT in SQLite
3. **odc-api is bloat**: Can be eliminated by reading landmark files directly (saves 14% CPU)
4. **SSH Tunnel Broken**: OpenSSH reverse tunnel relay doesn't forward data — likely platform bug
5. **HTTP Agent Ready**: Bee Agent API deployed at `/data/adacam/agent.py:8080`, tested locally
### Immediate Actions Required
1. Move truck closer for stable WiFi
2. Test HTTP agent through tunnel (may work even if SSH doesn't)
3. If tunnel relay is completely broken, deploy chisel as alternative
---
## Table of Contents
1. [Hardware Architecture](#1-hardware-architecture)
2. [Firmware & OS](#2-firmware--os)
3. [Data Pipeline](#3-data-pipeline)
4. [ADAMaps Backend](#4-adamaps-backend)
5. [Network & Connectivity](#5-network--connectivity)
6. [Known Issues](#6-known-issues)
7. [Service Reference](#7-service-reference)
8. [File System Reference](#8-file-system-reference)
9. [Fix Procedures](#9-fix-procedures)
10. [Appendices](#10-appendices)
---
## 1. Hardware Architecture
### 1.1 Intel Keem Bay SoC
| Component | Specification |
|-----------|--------------|
| **SoC** | Intel Keem Bay (ARM64) |
| **CPU** | 4x ARM Cortex-A53 cores |
| **VPU** | Intel Movidius Myriad X (16 SHAVE cores) |
| **Process** | 10nm |
| **Kernel** | Linux 5.10.32-intel-standard (aarch64) |
### 1.2 Camera System
| Component | Details |
|-----------|---------|
| **Sensor** | Sony IMX412 |
| **Resolution** | 2028x1024 @ 30fps |
| **Pipeline** | Luxonis DepthAI |
| **Output** | JPEG frames + VPU inference |
### 1.3 Network Interfaces
| Interface | MAC | Purpose | Typical IP |
|-----------|-----|---------|------------|
| wlp1s0f0 | b8:f4:4f:c7:a3:55 | WiFi AP | 192.168.0.10/24 |
| wlp1s0f1 | b8:f4:4f:c7:a3:56 | WiFi Client | DHCP (192.168.0.155) |
| wwan0 | - | LTE Modem (Telit) | DHCP when SIM inserted |
| br0 | - | USB Bridge | 192.168.197.55/28 |
### 1.4 Storage
- **Root filesystem**: Read-only (SquashFS)
- **/data partition**: Writable, persistent (ext4, mmcblk1p4)
- **Total storage**: eMMC with A/B partitions for OTA
---
## 2. Firmware & OS
### 2.1 Yocto Linux
| Property | Value |
|----------|-------|
| **Kernel** | 5.10.32-intel-standard |
| **Init System** | systemd |
| **Python** | 3.8 |
| **Node.js** | Present (v14.x) |
| **Shell** | /bin/sh (busybox) |
### 2.2 Mender OTA System
```json
{
"ServerURL": "https://docker.mender.io",
"UpdatePollIntervalSeconds": 1800,
"TenantToken": "dummy"
}
```
**Blocking updates:**
```bash
# Option 1: Disable service
systemctl stop mender-client
systemctl disable mender-client
# Option 2: Firewall
iptables -A OUTPUT -d docker.mender.io -j DROP
# Option 3: DNS sinkhole
echo "127.0.0.1 docker.mender.io" >> /etc/hosts
```
### 2.3 Persistence
**Survives OTA updates:**
- `/data/*` — all contents persist
- `/data/persist/` — custom modifications
- `/data/recording/` — dashcam footage
- `/data/adacam/` — ADAMaps config
**Does NOT survive:**
- `/opt/*` — read-only, replaced on update
- `/usr/*` — read-only
- `/tmp/*` — volatile
---
## 3. Data Pipeline
### 3.1 Capture Pipeline
```
Camera (IMX412) → depthai_gate → VPU (YOLOv8-nano) → Raw detections
map-ai.py
GPS fusion (Redis)
/data/recording/landmarks/*.json
```
### 3.2 Detection Classes
| Class ID | Label | Description |
|----------|-------|-------------|
| 0 | `road_sign` | Traffic signs |
| 1 | `lane_marking` | Road lines, arrows |
| 2 | `traffic_light` | Signal heads |
| 3 | `face` | Privacy (blur) |
| 4 | `license_plate` | Privacy (blur) |
| 5 | `road_marker` | Mile markers |
| 6 | `construction` | Construction signs |
| 7 | `vegetation` | Overgrown vegetation |
**Confidence threshold:** 0.3 minimum
### 3.3 Landmark File Format
**Path:** `/data/recording/landmarks/{timestamp}_{id}.json`
```json
{
"id": 2945056,
"class_label": "road_sign",
"overall_confidence": 0.847,
"lat": 33.841234,
"lon": -118.391234,
"timestamp": 1746377552043,
"bounding_box": {"x1": 1234, "y1": 456, "x2": 1456, "y2": 678},
"image_path": "/data/recording/cached_observations/xxx.jpg",
"speed_mph": 35.2,
"heading_deg": 127.4
}
```
### 3.4 SQLite Schema (odc-api.db)
**IMPORTANT:** SQLite does NOT contain detections. Only sensor data:
- `gnss` — GPS readings
- `imu` — Accelerometer/gyro
- `magnetometer` — Compass
- `framekms` — Video bundle metadata
- `config` / `state` — Service config
### 3.5 Redis Keys
| Key | Type | Purpose |
|-----|------|---------|
| MAP_AI_READY | string | "True" when inference active |
| GNSSFusion30Hz | zset | 30Hz GPS data |
| ImuFusion10Hz | zset | 10Hz IMU data |
| MagnetometerData | list | Compass readings |
---
## 4. ADAMaps Backend
### 4.1 Architecture
```
Bee Dashcam
adacam-forwarder (reads landmark files)
↓ POST /api/ingest
ADAMaps API (Flask on Rackham:5001)
PostGIS (Lucy via VPN at 192.168.254.112)
```
### 4.2 API Endpoints
**Live endpoints:**
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/health` | None | Health check |
| GET | `/api/stats` | None | Detection counts |
| GET | `/api/detections` | None | GeoJSON list |
| POST | `/api/ingest` | X-AdaMaps-Key | Ingest batch |
| POST | `/api/images` | X-AdaMaps-Key | Upload images |
**Agent Training (disabled):**
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/agent/task` | Get labeling task |
| POST | `/api/agent/submit` | Submit label |
### 4.3 Ingest Payload Format
```json
POST /api/ingest
Header: X-AdaMaps-Key: adamaps-ingest-2026
{
"device_id": "dashcam-4A928016A02C1046",
"detections": [
{
"ts": 1746377552043,
"lat": 33.841234,
"lon": -118.391234,
"class_label": "road_sign",
"overall_confidence": 0.847
}
]
}
```
### 4.4 Database Schema
```sql
CREATE TABLE detections (
id SERIAL PRIMARY KEY,
device_id TEXT NOT NULL,
detected_at TIMESTAMPTZ DEFAULT NOW(),
lat DOUBLE PRECISION NOT NULL,
lon DOUBLE PRECISION NOT NULL,
geom GEOMETRY(Point, 4326) GENERATED ALWAYS AS
(ST_SetSRID(ST_MakePoint(lon, lat), 4326)) STORED,
sign_type TEXT,
confidence DOUBLE PRECISION,
image_path TEXT,
raw_json JSONB
);
CREATE INDEX detections_geom_idx ON detections USING GIST(geom);
```
### 4.5 Infrastructure
| Component | Location | Details |
|-----------|----------|---------|
| ADAMaps API | Rackham (142.44.213.229) | Flask:5001 via Gunicorn |
| PostGIS | Lucy (192.168.254.112 via VPN) | PostGIS 16 |
| Image storage | Rackham:/opt/adamaps/images/ | Direct filesystem |
| VPN | WireGuard 192.168.254.0/24 | Rackham ↔ Lucy |
---
## 5. Network & Connectivity
### 5.1 Truck Bee Network Topology
```
┌─────────────────┐
│ Home Router │
│ (OPNsense) │
│ 192.168.0.1 │
└────────┬────────┘
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Lucy │ │ Bee │ │ Phone │
│ .0.5 │ │ .0.155 │ │ (Cobb) │
└──────────┘ │ (client) │ └────┬─────┘
▲ └─────┬────┘ │
│ │ │
│ │ AP 192.168.0.10 │
│ │◀────────────────┘
│ │
└──── tunnel ──────┘
```
### 5.2 SSH Tunnel Issue
**Problem:** SSH reverse tunnel establishes but **does not relay data**.
**Evidence:**
- Raw TCP test from Lucy:2222 received **zero bytes**
- Standalone sshd on port 2223 also failed
- Local SSH from Bee to itself: **WORKS**
- Tunnel port 2222 appears on Lucy but nothing flows through
**Root cause:** Unknown — likely OpenSSH version bug or Keembay kernel quirk.
### 5.3 WiFi Instability
**Problem:** wlp1s0f1 (zerocool client) keeps dropping.
**Cause:** Truck parked too far from router.
**Fix:** Move truck to Abby's parking spot (closer to house).
---
## 6. Known Issues
### 6.1 Critical
| Issue | Impact | Fix |
|-------|--------|-----|
| SSH tunnel relay broken | No remote access | Use HTTP agent API or chisel |
| WiFi drops constantly | Tunnel dies | Move truck closer |
| Bee Unit 2 locked out | Can't SSH in | Recovery mender artifact v5 |
### 6.2 Moderate
| Issue | Impact | Fix |
|-------|--------|-----|
| odc-api consumes 14% CPU | Wasted resources | Kill it, read files directly |
| VPN dependency for Postgres | API fails if VPN drops | Move DB to Rackham |
| Agent training API disabled | No crowdsourced labeling | Enable when image pipeline ready |
### 6.3 Low
| Issue | Impact | Fix |
|-------|--------|-----|
| No clustering job | Duplicated detections | Deploy clustering script |
| MAP token not minted | No rewards | Mint when DAO ready |
---
## 7. Service Reference
### 7.1 Services to KEEP (Liberation)
| Service | Purpose |
|---------|---------|
| depthai_gate | Camera capture + VPU |
| map-ai | Detection processing |
| redis | Sensor data store |
| redis-handler | Sensor fusion |
| hostapd | WiFi AP |
| sshd | Remote access |
### 7.2 Services to KILL (Liberation)
| Service | Reason |
|---------|--------|
| odc-api | Bloated, read files directly |
| mitmproxy | Hivemapper data exfil |
| beekeeper-plugin | Hivemapper control plane |
| hivemapper-data-logger | Data uploader |
| mender-client | OTA (blocks liberation) |
| here-plugin | HERE Maps integration |
| model-zoo | Hivemapper model updates |
### 7.3 New ADAMaps Services
| Service | Path | Port |
|---------|------|------|
| adacam-forwarder | /data/adacam/ | N/A (outbound) |
| bee-agent-api | /data/adacam/agent.py | 8080 |
| bee-tunnel | systemd | SSH tunnel |
---
## 8. File System Reference
### 8.1 Key Paths on Bee
```
/data/ # Writable, survives OTA
├── adacam/ # ADAMaps config
│ ├── config.json
│ ├── agent.py # HTTP agent API
│ └── forwarder_state.json
├── recording/
│ ├── landmarks/ # Detection JSON files ← KEY
│ ├── cached_observations/ # Detection images ← KEY
│ ├── framekm/ # Video bundles
│ └── odc-api.db # SQLite (sensors only)
├── ssh/
│ └── bee_tunnel_key # Tunnel SSH key
└── persist/ # Custom modifications
/opt/ # Read-only
├── map-ai/ # ML Python code
├── odc-api/ # Node.js API (to kill)
└── dashcam/bin/ # Binary tools
/tmp/ # Volatile
├── recording/pics/ # Live frames
└── gate_fw_*/ # VPU firmware
```
### 8.2 Key Paths on Lucy
```
192.168.0.5:
├── /mnt/user/appdata/ # Docker app data
├── /root/.ssh/authorized_keys # SSH keys
└── Port 3001 # Gitea
192.168.254.112 (via VPN):
└── Port 5432 # PostgreSQL
```
### 8.3 Key Paths on Rackham
```
142.44.213.229:
├── /opt/adamaps/ # ADAMaps deployment
│ ├── api/ # Flask API
│ └── images/ # Uploaded images
└── Port 5001 # API (reverse proxied to api.adamaps.org)
```
---
## 9. Fix Procedures
### 9.1 Test HTTP Agent via Tunnel
```bash
# On Bee (via phone SSH):
python3 /data/adacam/agent.py &
ip route add 192.168.0.5/32 dev wlp1s0f1
ssh -i /data/ssh/bee_tunnel_key -R 2222:localhost:8080 -N root@192.168.0.5 &
# On Lucy:
curl -H 'X-Agent-Key: bee-agent-sulkta-2026' http://127.0.0.1:2222/status
# Expected: {"ok": true, "time": ...}
```
### 9.2 Deploy chisel (if HTTP tunnel fails)
```bash
# On Lucy:
wget https://github.com/jpillora/chisel/releases/download/v1.9.1/chisel_1.9.1_linux_amd64.gz
gunzip chisel_1.9.1_linux_amd64.gz && chmod +x chisel_*
./chisel_* server --port 8080 --reverse --auth "sulkta:bee2026"
# On Bee:
wget -O /data/adacam/chisel https://github.com/jpillora/chisel/releases/download/v1.9.1/chisel_1.9.1_linux_arm64.gz
gunzip /data/adacam/chisel.gz && chmod +x /data/adacam/chisel
/data/adacam/chisel client --auth "sulkta:bee2026" 192.168.0.5:8080 R:2222:localhost:22 &
```
### 9.3 Block Hivemapper Domains
```bash
cat >> /etc/hosts << 'EOF'
127.0.0.1 hivemapper.com api.hivemapper.com
127.0.0.1 beemaps.com api.trybeekeeper.ai
127.0.0.1 docker.mender.io s3.mender.io
127.0.0.1 direct.data.api.platform.here.com
127.0.0.1 dashcam-firmware.s3.us-west-2.amazonaws.com
EOF
```
### 9.4 Kill Hivemapper Services
```bash
systemctl stop odc-api mitmproxy beekeeper-plugin hivemapper-data-logger mender-client
systemctl disable odc-api mitmproxy beekeeper-plugin hivemapper-data-logger mender-client
```
### 9.5 Create bee-tunnel.service
```ini
[Unit]
Description=SSH Tunnel to Lucy
After=network-online.target
[Service]
Type=simple
ExecStartPre=/sbin/ip route add 192.168.0.5/32 dev wlp1s0f1
ExecStart=/usr/bin/ssh -i /data/ssh/bee_tunnel_key \
-R 2222:127.0.0.1:8080 \
-N -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
-o StrictHostKeyChecking=no -o ExitOnForwardFailure=yes \
root@192.168.0.5
Restart=always
RestartSec=30
[Install]
WantedBy=multi-user.target
```
---
## 10. Appendices
### A. Credentials
| Service | Key/Password |
|---------|-------------|
| ADAMaps Ingest | `X-AdaMaps-Key: adamaps-ingest-2026` |
| Bee Agent API | `X-Agent-Key: bee-agent-sulkta-2026` |
| PostGIS | `adamaps:adamaps2026` |
| Rackham sudo | `T3mLHfzb` |
| Gitea token | `33a9eb57b58c262f4434c12028bc3a30b1ff7021` |
### B. SSH Keys
**OpenClaw (kayos@openclaw):**
```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOQxwJU91TCxds34P18D3xRbu7rxlrgTUoml/H8nxeDK
```
**Bee tunnel (root@keembay):**
```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAII5ckRf/4SA84JOrmJtElHBT3dU9RC2Le5GBfqhWWVc8
```
### C. IP Addresses
| Device | LAN IP | VPN IP |
|--------|--------|--------|
| Lucy | 192.168.0.5 | 192.168.254.112 |
| Rackham | 142.44.213.229 | 192.168.254.1 |
| Bee AP | 192.168.0.10 | — |
| Bee Client | 192.168.0.155 (DHCP) | — |
| OPNsense | 192.168.0.1 | — |
### D. Gitea Repos
| Repo | Purpose |
|------|---------|
| Sulkta-Coop/adamaps | Backend API, schema, frontend |
| Sulkta-Coop/adacam | Liberation scripts, security |
| Sulkta-Coop/adacam-api | On-device API for Bee |
### E. URLs
| Service | URL |
|---------|-----|
| ADAMaps API | https://api.adamaps.org |
| Gitea | http://192.168.0.5:3001 |
| Home Assistant | http://192.168.0.5:8123 |
---
## Document Manifest
This report was compiled from:
1. `docs/hivemapper-bee-technical-architecture.md` — Hardware/firmware deep dive
2. `docs/ADAMAPS-TECHNICAL.md` — Backend API documentation
3. `docs/BEE_DATA_PIPELINE.md` — Data flow analysis
4. `memory/bee-ssh-diagnostic-report.md` — SSH tunnel diagnostics
---
**End of Report**
*Generated 2026-03-22 by Kayos for Sulkta Cooperative*