122 lines
4.7 KiB
Markdown
122 lines
4.7 KiB
Markdown
# 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).
|
||
|
||
```bash
|
||
./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):
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
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`](LICENSE).
|