Varroa

Varroa is an Android companion app for the Hivemapper Bee dashcam. It pulls detection landmarks off the camera's on-device API, queues them in a local database, and forwards them to an AdaMaps ingest endpoint once the phone has a validated internet connection. The Bee exposes its API only over its own Wi‑Fi access point, so Varroa exists to bridge that gap: collect while you're connected to the camera, upload when you're back on the internet.

The repository also ships blackbox/, a small Python companion that reads an air‑quality sensor on a Linux single‑board computer (e.g. a Raspberry Pi), fuses the readings with GPS from the Bee, and posts them to the same AdaMaps stream.

Features

• Store‑and‑forward collection — BeeCollectorService polls the Bee for detection landmarks and writes them to a local Room database. Nothing is lost if the phone is offline.
• Validated‑internet uploads — AdaMapsUploadWorker (WorkManager) drains the queue to the AdaMaps API only when real connectivity is available, not when you're merely attached to the camera's captive AP.
• Image capture — ImageCollectorService pulls detection JPEGs from the Bee for landmarks that have associated crops.
• Device pairing & status — pair with the camera, view Wi‑Fi/storage/GNSS status, and toggle device options from the in‑app settings screens.
• Optional Cardano wallet linking — attach a wallet address to detection uploads so contribution rewards can be routed to you. Entirely optional.

How it works

Hivemapper Bee  ──HTTP (AP only)──►  Varroa (Android)
   detections                          ├─ Room queue (local DB)
   landmark crops                      └─ AdaMapsUploadWorker
                                              │  (only on validated internet)
                                              ▼
                                        AdaMaps ingest API

The Bee's API is reachable only over the camera's own access point, which serves plain HTTP on a fixed device‑AP address. Varroa scopes an Android cleartext exception to just that one host (see app/src/main/res/xml/network_security_config.xml); everything else is HTTPS‑only.

Build

Requirements: JDK 17, Android SDK 34. Minimum supported device is Android 8.0 (API 26).

./gradlew :app:assembleDebug

The debug APK lands in app/build/outputs/apk/debug/.

Release signing

Release builds are signed from a keystore supplied through environment variables (no secrets are stored in the repo):

export VARROA_KEYSTORE_PATH=/path/to/your-release.keystore
export VARROA_KEYSTORE_PASSWORD=…
export VARROA_KEY_PASSWORD=…        # defaults to the keystore password
./gradlew :app:assembleRelease

If the keystore variables are unset, Gradle falls back to an unsigned release build.

Configuration (set in‑app)

• Bee URL — the camera's API base URL. Defaults to http://192.168.0.10:5000, the factory access‑point address; change it if your camera uses a different AP IP.
• AdaMaps URL + ingest key — required before uploads will run. Both are entered in the app and stored locally; there are no baked‑in defaults.
• Cardano wallet — optional. When set, the address is attached to detection uploads for reward routing.

blackbox (air‑quality companion)

blackbox/air_aggregator.py reads a BME680 (I²C) and a PMS5003 particulate sensor (UART), fuses the readings with GPS pulled from the Bee, and posts them to the AdaMaps ingest endpoint on a fixed interval, buffering to disk while offline.

pip install bme680 requests smbus2 pyserial
BEE_URL=http://192.168.197.1:5000 \
ADAMAPS_URL=https://api.adamaps.org \
ADAMAPS_KEY=your-ingest-key \
python3 blackbox/air_aggregator.py

A sample systemd unit is provided at blackbox/air-aggregator.service.

Documentation

• docs/BEE-CAMERA.md — reverse‑engineering notes on the Hivemapper Bee's internal camera pipeline (Intel Keem Bay / Myriad X VPU, DepthAI, the on‑device REST API). Useful background for anyone building against the camera.
• docs/AIR-QUALITY-INTEGRATION.md — design notes for adding an air‑quality sensor to the Bee and ingesting the readings.

Tech stack

Kotlin · Jetpack Compose · Room · DataStore · WorkManager · OkHttp/Gson · osmdroid (map preview) · Coil (images).

Contributing

Contributions are welcome. Please open an issue to discuss substantial changes before sending a pull request, keep commits focused, and make sure ./gradlew :app:assembleDebug passes before submitting.

License

Released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.