Sulkta-OSS/varroa
3
0
Fork 0
Code Issues 1 Pull requests 10 Projects Releases Packages Wiki Activity Actions

docs: public-facing README + MIT LICENSE; genericize CI workflow comment

Browse source
This commit is contained in:
Sulkta 2026-06-28 20:14:11 -07:00
parent c50e47522d
commit e8e3a64894
3 changed files with 128 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

16
.forgejo/workflows/gitleaks.yml
View file

@ -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

21
LICENSE Normal file
View file

@ -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.

133
README.md
View file

@ -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=<see vault>
VARROA_KEY_PASSWORD=<see vault>
### 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).