From f7f821a475e3cad211fe48ddee2a795d15151139 Mon Sep 17 00:00:00 2001
From: ua1zbe <ua1zbe@git2.ua1zbe.ru>
Date: Tue, 9 Jun 2026 15:48:51 +0300
Subject: [PATCH] Add AGENTS.md with full project context for opencode

---
 AGENTS.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..016accc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,125 @@
+# Project: MeshCore Relay Radio (for opencode)
+
+## Goal
+
+Modify MeshCore `companion_radio` firmware for Heltec T114 to control a relay and read DS18B20 temperature sensor via LoRa mesh private messages.
+
+## Hardware
+
+- **Board:** Heltec T114 (nRF52840 + SX1262)
+- **Relay:** GPIO 4 (RELAY_PIN)
+- **DS18B20:** GPIO 5 (ONE_WIRE_BUS) with 4.7k pull-up
+- **BLE PIN (for BLE variant):** 123456
+
+## Radio Parameters
+
+- Frequency: 868.731018 MHz
+- Bandwidth: 62.5 kHz
+- Spreading Factor: 7
+- Coding Rate: 7
+- Path Hash: 1 byte (mode 0)
+
+## Commands (via private mesh messages)
+
+| Command  | Response                        | Action                |
+|----------|---------------------------------|-----------------------|
+| `on1234` | `relay on`                      | Relay ON              |
+| `off1234`| `relay off`                     | Relay OFF             |
+| `temp`   | `temp: 23.5 C`                  | Read DS18B20 temp     |
+| `state`  | `temp: 23.5 C, relay: ON`       | Temp + relay state    |
+
+Numbers in commands (e.g. `1234`) are a PIN code, not validated by firmware.
+
+## Source Files
+
+Modified files (relative to MeshCore root):
+
+- `examples/relay_radio/MyMesh.h` — class declaration, relay/temp fields
+- `examples/relay_radio/MyMesh.cpp` — relay on/off logic, temp reading, command parsing
+- `examples/relay_radio/main.cpp` — entry point, BLE config, pin setup
+- `platformio.ini` — added OneWire/DallasTemperature libs, 2 new envs for T114
+
+## Build Environments
+
+Two envs defined in `platformio.ini`:
+
+1. `Heltec_t114_relay_radio_usb` — Serial USB interface
+2. `Heltec_t114_relay_radio_ble` — BLE interface with PIN 123456
+
+Both based on existing `Heltec_t114` variant.
+
+## Build & Flash
+
+```bash
+# Build
+pio run -e Heltec_t114_relay_radio_usb
+pio run -e Heltec_t114_relay_radio_ble
+
+# Flash
+pio run -e Heltec_t114_relay_radio_ble -t upload --upload-port <port>
+```
+
+### UF2 Drag-and-Drop
+
+1. Double-tap reset button on T114 to enter UF2 mode
+2. Copy `firmware.uf2` from `.pio/build/Heltec_t114_relay_radio_ble/` to mounted disk
+
+## Key Implementation Details
+
+- Commands received via `onMessageRecv()` callback
+- Response sent via `sendMessage()` (reuses encrypted chat channel)
+- Timer-based advert in `MyMesh::loop()` every 30 min (1800000 ms)
+- OneWire/DallasTemperature initialized in constructor
+- Temperature read on demand (not periodically)
+- All parameters settable via build flags in `platformio.ini`
+
+## Auto-Advert Timing
+
+- Interval: 30 minutes (1800000 ms)
+- Advert name: "Relay" (set via `ADVERT_NAME` define)
+- Implemented in `MyMesh::loop()` with `_next_advert_ms` field
+
+## Repository
+
+- Gitea: https://git2.ua1zbe.ru/ua1zbe/MeshCore-RelayRadio
+- Release v1.0.0 with UF2 binaries (BLE + USB)
+- User credentials: ua1zbe / Personal Access Token: `067f4415552ac62ba4ff8e7704c924da17dd3fbf`
+
+## Updating Gitea
+
+```bash
+cd /tmp/opencode/fresh-repo
+git add -A
+git commit -m "message"
+git push origin main
+```
+
+## Creating a New Release
+
+```bash
+TOKEN="067f4415552ac62ba4ff8e7704c924da17dd3fbf"
+VERSION="v1.1.0"
+
+# Tag and push
+git tag -a "$VERSION" -m "Release $VERSION"
+git push origin "$VERSION"
+
+# Create release
+curl -s -X POST "https://git2.ua1zbe.ru/api/v1/repos/ua1zbe/MeshCore-RelayRadio/releases" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $TOKEN" \
+  -d "{\"tag_name\":\"$VERSION\",\"name\":\"$VERSION\",\"body\":\"Release description\"}"
+
+# Upload assets (get RELEASE_ID from response)
+curl -s -X POST "https://git2.ua1zbe.ru/api/v1/repos/ua1zbe/MeshCore-RelayRadio/releases/$RELEASE_ID/assets" \
+  -H "Authorization: token $TOKEN" \
+  -F "attachment=@path/to/file.uf2" \
+  -F "name=Heltec_T114_BLE_firmware.uf2"
+```
+
+## Ongoing Maintenance
+
+- Firmware is based on upstream MeshCore. To update, re-clone MeshCore, re-apply the `examples/relay_radio/` modifications, and rebuild.
+- The `relay_radio` example lives in `examples/relay_radio/` — it is a modified copy of `examples/companion_radio/`.
+- Compiled UF2 files are kept in `/home/ua1zbe/Рабочий стол/relay_radio_firmware/` on the developer machine.
+- Full build/usage instructions: `README.md`