From 2c2702ea6b2871ade194a7ad8ea3d599870b1b5b Mon Sep 17 00:00:00 2001 From: fjoelnir Date: Sun, 22 Mar 2026 11:42:13 +0100 Subject: [PATCH] docs: apply platformio profile baseline --- .agents/context-index.md | 16 ++++++++++++++++ AGENTS.md | 22 ++++++++++++++++++++++ README.md | 12 ++++++++++-- anr.profile.yaml | 20 ++++++++++++++++++++ anr.yaml | 8 ++++++++ docs/STATUS.md | 11 ++++++----- docs/hardware.md | 30 ++++++++++++++++++++++++++++++ docs/operations.md | 29 +++++++++++++++++++++++++++++ docs/topic-contracts.md | 28 ++++++++++++++++++++++++++++ docs/verification.md | 26 ++++++++++++++++++++++++++ 10 files changed, 195 insertions(+), 7 deletions(-) create mode 100644 .agents/context-index.md create mode 100644 anr.profile.yaml create mode 100644 anr.yaml create mode 100644 docs/hardware.md create mode 100644 docs/operations.md create mode 100644 docs/topic-contracts.md create mode 100644 docs/verification.md diff --git a/.agents/context-index.md b/.agents/context-index.md new file mode 100644 index 0000000..4cacae6 --- /dev/null +++ b/.agents/context-index.md @@ -0,0 +1,16 @@ +# Repository Context Index + +Repository structure: + +Source: +* src +* lib +* scripts + +Tests: +* tests + +Documentation: +* docs + +ANR migration generated this file. diff --git a/AGENTS.md b/AGENTS.md index 7b7c175..4d7c14d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,3 +20,25 @@ HiveTech is the beehive monitoring firmware line in the portfolio. Treat it as a ## Delivery Flow Use `feature -> develop -> main`. Keep public-facing docs and topics aligned with the actual firmware scope. + + +## Active Stack Profile + +This repository uses the `platformio-iot` stack profile. + +### Additional Focus + +- PlatformIO build and upload configuration +- board, sensor, and pin assumptions +- telemetry/topic contracts +- hardware validation beyond compile success + +### Additional Working Rules + +- never commit device-specific secrets or local deployment values +- keep hardware assumptions explicit in docs +- treat topic and payload changes as interface changes +- separate build success from real-device verification success +- keep the local `platformio.ini` upload target as developer-local state unless a shared deployment path is intentionally introduced + + diff --git a/README.md b/README.md index e12a6cb..26415f5 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,14 @@ See [docs/STATUS.md](docs/STATUS.md) for the current project state. The firmware expects a local `src/config.h` file that is not committed. Start from [src/config_template.h](src/config_template.h) and adjust the values for your network and MQTT broker. +Additional operating context now lives in: + +- [docs/hardware.md](docs/hardware.md) +- [docs/operations.md](docs/operations.md) +- [docs/topic-contracts.md](docs/topic-contracts.md) +- [docs/verification.md](docs/verification.md) +- [anr.profile.yaml](anr.profile.yaml) + ## Topics Published - `HT_BME280_Temperature` @@ -34,6 +42,6 @@ The firmware expects a local `src/config.h` file that is not committed. Start fr ## Immediate Next Steps 1. Replace the legacy `config.h` flow with a clearer credentials/config separation. -2. Document the intended hardware wiring for the hive node. +2. Add a repeatable local build check that uses placeholder config for compile-only validation. 3. Decide which parts should remain standalone versus moving into `SkySentinel`. -4. Add a simple validation/build workflow once the local config path is standardized. +4. Add hive-specific telemetry beyond the current BME280 baseline once the hardware scope is stable. diff --git a/anr.profile.yaml b/anr.profile.yaml new file mode 100644 index 0000000..3894810 --- /dev/null +++ b/anr.profile.yaml @@ -0,0 +1,20 @@ +profile_id: platformio-iot +category: firmware +focus: + - platformio + - hardware-validation + - device-config + - telemetry +recommended_docs: + - docs/hardware.md + - docs/verification.md + - docs/operations.md + - docs/topic-contracts.md +recommended_skills: + - embedded-debugging + - hardware-bringup + - telemetry-review +recommended_guardrails: + - secret-handling + - hardware-assumption-boundaries + - deployment-safety diff --git a/anr.yaml b/anr.yaml new file mode 100644 index 0000000..2eea1f9 --- /dev/null +++ b/anr.yaml @@ -0,0 +1,8 @@ +anr_version: "0.1" +context_index: .agents/context-index.md +detected_directories: + - src + - lib + - scripts + - tests + - docs diff --git a/docs/STATUS.md b/docs/STATUS.md index 79062c1..607fbaa 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -9,19 +9,20 @@ HiveTech is an ESP32 firmware prototype for live beehive monitoring. It reads BM - Revival candidate with real firmware code, not just a stub - Public again by explicit portfolio decision - Still uses a legacy `config.h` include path +- PlatformIO/IoT profile context is now committed in `anr.profile.yaml` plus focused hardware and operations docs - No modern CI/build validation yet - Local developer deployment settings are still present outside committed templates ## Known Gaps -- No committed configuration template existed before this cleanup pass -- No README or public-facing operational context existed -- Hardware wiring and deployment procedure are not yet documented -- MQTT contract is still implicit in code +- The repo still relies on a simple local `config.h` include model +- Hardware wiring is documented only to the level visible in current firmware assumptions +- Deployment is still local and OTA-target specific +- MQTT contract is documented but still topic-only, without retained/availability semantics ## Next Milestone -Stabilize the public repo baseline, then decide whether HiveTech becomes: +Stabilize the revived public firmware baseline, then decide whether HiveTech becomes: 1. a standalone beehive telemetry node, or 2. a domain-specific branch of the broader SkySentinel ecosystem. diff --git a/docs/hardware.md b/docs/hardware.md new file mode 100644 index 0000000..3faa6f1 --- /dev/null +++ b/docs/hardware.md @@ -0,0 +1,30 @@ +# Hardware + +## Target + +HiveTech currently targets a generic `esp32dev` board definition with a single BME280 environmental sensor. + +Current firmware assumptions from the code: + +- board: ESP32 dev board (`[env:esp32dev]` in `platformio.ini`) +- primary sensor: BME280 via I2C +- I2C address: `0x77` +- sleep cycle: `TIME_TO_SLEEP = 60` seconds +- deep sleep wake source: timer wakeup + +The code calls `Wire.begin()` without explicit pins, so the active SDA/SCL mapping depends on the actual ESP32 board defaults or local hardware wiring. + +## Pin Map + +- `GPIO25`: `redLEDpin` +- `GPIO4`: `greenLEDpin` +- `GPIO15`: `ONE_WIRE_BUS` +- `GPIO5`: `SD_CS` + +Not every declared pin is currently exercised in the active telemetry flow. Treat this list as the current code-level hardware contract, not as proof that every peripheral is physically assembled on the node. + +## Notes + +- The firmware currently uses only BME280 telemetry in the active publish path. +- OTA is enabled, so the deployed node must stay reachable on the local network during maintenance. +- Before adding more hive-specific sensors, document their wiring and topic outputs here first. diff --git a/docs/operations.md b/docs/operations.md new file mode 100644 index 0000000..9ac48f0 --- /dev/null +++ b/docs/operations.md @@ -0,0 +1,29 @@ +# Operations + +## Runtime + +HiveTech is a local-first firmware repo. + +Current runtime flow: + +1. local `src/config.h` provides Wi-Fi SSID, password, and MQTT broker +2. firmware boots on ESP32 +3. node connects to Wi-Fi +4. OTA is initialized +5. BME280 values are read and published to MQTT +6. node returns to timed deep sleep + +`platformio.ini` currently contains a developer-local `upload_port`. Treat that as local machine state, not as committed team-wide truth. + +## Safety Rules + +- separate local credentials from committed templates +- keep `src/config.h` untracked +- verify the target IP/device before OTA uploads +- document any destructive or risky deployment step explicitly + +## Recovery Notes + +- If Wi-Fi or MQTT details change, update only local config files. +- If OTA fails, fall back to a direct flash path rather than repeatedly retrying against the wrong node. +- If BME280 detection fails, check wiring and I2C address assumptions before changing code. diff --git a/docs/topic-contracts.md b/docs/topic-contracts.md new file mode 100644 index 0000000..c9c6934 --- /dev/null +++ b/docs/topic-contracts.md @@ -0,0 +1,28 @@ +# Topic Contracts + +## Purpose + +Document the MQTT topics currently published by HiveTech. + +## Topics + +- `HT_BME280_Temperature` + Payload: numeric value as text + Meaning: ambient temperature from the BME280 in degrees Celsius +- `HT_BME280_Humidity` + Payload: numeric value as text + Meaning: relative humidity from the BME280 +- `HT_BME280_Pressure` + Payload: numeric value as text + Meaning: barometric pressure from the BME280 divided by `100` +- `HT_BME280_Altitude` + Payload: numeric value as text + Meaning: altitude reported by the BME280 library + +Current code publishes these topics once per wake cycle after sensor readout and MQTT reconnect. + +## Change Rules + +- Keep topic names stable unless downstream automations are migrated deliberately. +- Treat unit changes or payload-format changes as interface changes. +- If retained messages, availability topics, or structured payloads are introduced, document them here before rollout. diff --git a/docs/verification.md b/docs/verification.md new file mode 100644 index 0000000..8eb599c --- /dev/null +++ b/docs/verification.md @@ -0,0 +1,26 @@ +# Verification + +## Goal + +Keep firmware changes reproducible and separate "compiles locally" from "works on the hive node". + +## Minimum Checks + +1. Copy `src/config_template.h` to local `src/config.h` or provide an equivalent local config file. +2. Run `platformio run` for `env:esp32dev`. +3. Flash or OTA-update the node using the local deployment path from `platformio.ini`. +4. Confirm serial boot output reaches: + - Wi-Fi connect + - MQTT connect + - BME280 detection + - deep sleep entry +5. Verify these MQTT topics receive fresh values: + - `HT_BME280_Temperature` + - `HT_BME280_Humidity` + - `HT_BME280_Pressure` + - `HT_BME280_Altitude` + +## Separation Of Checks + +- Compile-only validation is useful for refactors and dependency changes. +- Real hardware validation is still mandatory after sensor, networking, OTA, or sleep-logic changes.