# 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 MIT License. See [`LICENSE`](LICENSE).