docs: public-facing README + MIT LICENSE; genericize CI workflow comment
This commit is contained in:
Sulkta
parent
c50e47522d
commit
e8e3a64894
3 changed files with 128 additions and 42 deletions
|
|
@ -1,16 +1,6 @@
|
||||||
# .forgejo/workflows/gitleaks.yml
|
# 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
|
||||||
# Sulkta canonical gitleaks workflow. Drop a copy into every public repo at
|
# is detected, so credentials never land in history.
|
||||||
# `.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.
|
|
||||||
|
|
||||||
name: gitleaks
|
name: gitleaks
|
||||||
|
|
||||||
|
|
|
||||||
21
LICENSE
Normal file
21
LICENSE
Normal 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
133
README.md
|
|
@ -1,46 +1,121 @@
|
||||||
# varroa
|
# Varroa
|
||||||
|
|
||||||
Android companion for the Hivemapper Bee dashcam. Pulls detection
|
Varroa is an Android companion app for the **Hivemapper Bee** dashcam. It
|
||||||
landmarks off the on-Bee `adacam-api`, queues them in a local Room
|
pulls detection landmarks off the camera's on-device API, queues them in a
|
||||||
DB, forwards to AdaMaps when the phone has real internet.
|
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
|
The repository also ships `blackbox/`, a small Python companion that reads an
|
||||||
Pi (BME680 + PMS5003) and ships air-quality readings into the same
|
air‑quality sensor on a Linux single‑board computer (e.g. a Raspberry Pi),
|
||||||
AdaMaps stream.
|
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
|
## Build
|
||||||
|
|
||||||
```
|
Requirements: **JDK 17**, **Android SDK 34**. Minimum supported device is
|
||||||
JDK 17, Android SDK 34
|
Android 8.0 (API 26).
|
||||||
|
|
||||||
|
```bash
|
||||||
./gradlew :app:assembleDebug
|
./gradlew :app:assembleDebug
|
||||||
```
|
```
|
||||||
|
|
||||||
Release signing needs:
|
The debug APK lands in `app/build/outputs/apk/debug/`.
|
||||||
|
|
||||||
```
|
### Release signing
|
||||||
VARROA_KEYSTORE_PATH=/path/to/varroa-release.keystore
|
|
||||||
VARROA_KEYSTORE_PASSWORD=<see vault>
|
Release builds are signed from a keystore supplied through environment
|
||||||
VARROA_KEY_PASSWORD=<see vault>
|
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
|
./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).
|
## Configuration (set in‑app)
|
||||||
- **AdaMaps URL + ingest key** — required before uploads run.
|
|
||||||
- **Cardano wallet** — optional. Attaches to detection ingest for
|
|
||||||
rewards routing.
|
|
||||||
|
|
||||||
## 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.
|
## blackbox (air‑quality companion)
|
||||||
- `AdaMapsUploadWorker` — drains Room to `api.adamaps.org` once
|
|
||||||
validated internet is available.
|
|
||||||
- `ImageCollectorService` — pulls detection JPEGs from the Bee.
|
|
||||||
|
|
||||||
## 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 +
|
```bash
|
||||||
PMS5003 over USB, posts to AdaMaps every 60s. Systemd unit at
|
pip install bme680 requests smbus2 pyserial
|
||||||
`blackbox/air-aggregator.service` — set `ADAMAPS_KEY` and
|
BEE_URL=http://192.168.197.1:5000 \
|
||||||
`AGGREGATOR_BEE_URL` in the unit before enabling.
|
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).
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue