From e8e3a64894d9c1ee4c55b7fc6a7c9f8dc3d55cf7 Mon Sep 17 00:00:00 2001 From: Sulkta Date: Sun, 28 Jun 2026 20:14:11 -0700 Subject: [PATCH] docs: public-facing README + MIT LICENSE; genericize CI workflow comment --- .forgejo/workflows/gitleaks.yml | 16 +--- LICENSE | 21 +++++ README.md | 133 +++++++++++++++++++++++++------- 3 files changed, 128 insertions(+), 42 deletions(-) create mode 100644 LICENSE diff --git a/.forgejo/workflows/gitleaks.yml b/.forgejo/workflows/gitleaks.yml index 10d7847..48fa421 100644 --- a/.forgejo/workflows/gitleaks.yml +++ b/.forgejo/workflows/gitleaks.yml @@ -1,16 +1,6 @@ -# .forgejo/workflows/gitleaks.yml -# -# Sulkta canonical gitleaks workflow. Drop a copy into every public repo at -# `.forgejo/workflows/gitleaks.yml` after the Forgejo act_runner is registered -# (task #295). -# -# Pairs with the pre-receive hook installed on every bare repo — that one is -# the strict enforcement layer (rejects the push); this one provides the -# per-PR red ✗ that branch-protection rules can require before merge. -# -# Layer 1 (this workflow): visible per-PR status, can be a required check. -# Layer 2 (pre-receive hook): strict enforcement at the server. -# Layer 3 (johnny5 cron sweep): nightly full-history sweep across all repos. +# Scan the repository for committed secrets with gitleaks on every push and +# pull request. The job fails (and can be made a required check) if a secret +# is detected, so credentials never land in history. name: gitleaks diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4430ab4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Sulkta + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index ce62f5e..4d0248f 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,121 @@ -# varroa +# Varroa -Android companion for the Hivemapper Bee dashcam. Pulls detection -landmarks off the on-Bee `adacam-api`, queues them in a local Room -DB, forwards to AdaMaps when the phone has real internet. +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. -Sister piece: `blackbox/` — Python aggregator that runs on a truck -Pi (BME680 + PMS5003) and ships air-quality readings into the same -AdaMaps stream. +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 -``` -JDK 17, Android SDK 34 +Requirements: **JDK 17**, **Android SDK 34**. Minimum supported device is +Android 8.0 (API 26). + +```bash ./gradlew :app:assembleDebug ``` -Release signing needs: +The debug APK lands in `app/build/outputs/apk/debug/`. -``` -VARROA_KEYSTORE_PATH=/path/to/varroa-release.keystore -VARROA_KEYSTORE_PASSWORD= -VARROA_KEY_PASSWORD= +### 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 ``` -## Config (set in-app) +If the keystore variables are unset, Gradle falls back to an unsigned release +build. -- **Bee URL** — defaults to `http://192.168.0.10:5000` (Bee AP). -- **AdaMaps URL + ingest key** — required before uploads run. -- **Cardano wallet** — optional. Attaches to detection ingest for - rewards routing. +## Configuration (set in‑app) -## Architecture +- **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. -- `BeeCollectorService` — polls the Bee, writes landmarks to Room. -- `AdaMapsUploadWorker` — drains Room to `api.adamaps.org` once - validated internet is available. -- `ImageCollectorService` — pulls detection JPEGs from the Bee. +## blackbox (air‑quality companion) -## blackbox +`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. -The air-quality side. `air_aggregator.py` reads BME680 + -PMS5003 over USB, posts to AdaMaps every 60s. Systemd unit at -`blackbox/air-aggregator.service` — set `ADAMAPS_KEY` and -`AGGREGATOR_BEE_URL` in the unit before enabling. +```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).