kayos 07d1273618 add master technical report for ADAMaps project

2026-03-22 11:09:36 -07:00

16 KiB

Raw Permalink Blame History

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

Bee Hardware: Intel Keem Bay SoC (ARM Cortex-A53 + Movidius VPU), Sony IMX412 camera, dual WiFi radios, LTE modem
Detection Storage: Files in /data/recording/landmarks/*.json — NOT in SQLite
odc-api is bloat: Can be eliminated by reading landmark files directly (saves 14% CPU)
SSH Tunnel Broken: OpenSSH reverse tunnel relay doesn't forward data — likely platform bug
HTTP Agent Ready: Bee Agent API deployed at /data/adacam/agent.py:8080, tested locally

Immediate Actions Required

Move truck closer for stable WiFi
Test HTTP agent through tunnel (may work even if SSH doesn't)
If tunnel relay is completely broken, deploy chisel as alternative

Hardware Architecture
Firmware & OS
Data Pipeline
ADAMaps Backend
Network & Connectivity
Known Issues
Service Reference
File System Reference
Fix Procedures
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

{
    "ServerURL": "https://docker.mender.io",
    "UpdatePollIntervalSeconds": 1800,
    "TenantToken": "dummy"
}

Blocking updates:

# 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

{
  "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

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

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

# 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)

# 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

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

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

[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:

docs/hivemapper-bee-technical-architecture.md — Hardware/firmware deep dive
docs/ADAMAPS-TECHNICAL.md — Backend API documentation
docs/BEE_DATA_PIPELINE.md — Data flow analysis
memory/bee-ssh-diagnostic-report.md — SSH tunnel diagnostics

End of Report

Generated 2026-03-22 by Kayos for Sulkta Cooperative

16 KiB Raw Permalink Blame History