commit f8e88fa6ed7ac6acdd8f7a4aa6fd61784d206c44 Author: Lars Nolden Date: Mon Aug 31 22:02:05 2026 +0200 initial: dev environment flake and task prompt diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..7294027 --- /dev/null +++ b/flake.nix @@ -0,0 +1,79 @@ +{ + description = "Heltec WiFi LoRa 32 V4.3 wM-Bus C1 repeater HIL development environment"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11"; + esp-dev = { + url = "github:mirrexagon/nixpkgs-esp-dev/5287d6e1ca9e15ebd5113c41b9590c468e1e001b"; + }; + }; + + outputs = { self, nixpkgs, esp-dev }: + let + system = "x86_64-linux"; + pkgs = import nixpkgs { inherit system; }; + + rtl-wmbus = pkgs.stdenv.mkDerivation { + pname = "rtl-wmbus"; + version = "2024-08-26"; + src = pkgs.fetchFromGitHub { + owner = "xaelsouth"; + repo = "rtl-wmbus"; + rev = "34684e655df70867ac86e799561ec6512c45be0a"; + hash = "sha256-hqlvL0EhmxZ5NxyCxOB1a7S9mEnWrkUrrh7EPdXSN7k="; + }; + buildPhase = '' + runHook preBuild + make release + runHook postBuild + ''; + installPhase = '' + runHook preInstall + install -Dm755 build/rtl_wmbus $out/bin/rtl_wmbus + runHook postInstall + ''; + }; + + wmbusmeters = pkgs.stdenv.mkDerivation { + pname = "wmbusmeters"; + version = "unstable-2026"; + src = pkgs.fetchFromGitHub { + owner = "wmbusmeters"; + repo = "wmbusmeters"; + rev = "85532d91fd1e2bfa25b01705dd6aa574287649f7"; + hash = "sha256-rOeeeYVXxGTXdKQMHr/bkODoi6rlE4i3r7ItGhyimjI="; + }; + nativeBuildInputs = [ pkgs.pkg-config ]; + buildInputs = [ pkgs.rtl-sdr ]; + makeFlags = [ "PREFIX=$(out)" ]; + # skip install of systemd units etc. + installPhase = '' + runHook preInstall + install -Dm755 build/wmbusmeters $out/bin/wmbusmeters + runHook postInstall + ''; + }; + + pythonEnv = pkgs.python3.withPackages (ps: with ps; [ + pyserial + numpy + ]); + in + { + packages.${system} = { inherit rtl-wmbus wmbusmeters; }; + + devShells.${system}.default = pkgs.mkShell { + name = "heltec-repeater-dev"; + buildInputs = [ + esp-dev.packages.${system}.esp-idf-esp32s3 + pkgs.rtl-sdr + rtl-wmbus + wmbusmeters + pythonEnv + pkgs.usbutils + pkgs.picocom + pkgs.jq + ]; + }; + }; +} diff --git a/prompt b/prompt new file mode 100644 index 0000000..8ec3818 --- /dev/null +++ b/prompt @@ -0,0 +1,1949 @@ +# Autonomous Hardware-in-the-Loop Development Task: + +# Wireless M-Bus C1 Repeater on Heltec WiFi LoRa 32 V4.3 + +You are an autonomous embedded-firmware development agent working on a Linux/NixOS development machine with real hardware connected over USB. + +Your goal is to implement, test, debug, and stabilize an experimental Wireless M-Bus C1 repeater using exactly: + +* ONE Heltec WiFi LoRa 32 V4.3 +* Model: HTIT-WB32LAF V4.3 +* ONE Nooelec NESDR SMArt v5 RTL-SDR +* Real nearby OMS / Wireless M-Bus meters as RF traffic sources + +The Heltec is the Device Under Test (DUT). + +The Nooelec SDR is an independent RF observer and is used to close the hardware-in-the-loop feedback loop. + +There is NO second Heltec. + +Do not design around a second transmitter. + +Real meters provide the input RF stimulus. + +The SDR independently verifies both the original meter telegram and the Heltec retransmission. + +--- + +# 1. Primary Objective + +Implement a simple experimental: + +``` +Wireless M-Bus C1 RX + -> +validate/capture raw telegram + -> +short configurable delay + -> +retransmit corresponding C1 telegram + -> +immediately return to RX +``` + +on the Heltec WiFi LoRa 32 V4.3. + +The experiment should establish whether the SX1262 + KCT8103L RF frontend on this board can serve as the basis for a future Solenos/Gebos Wireless M-Bus gateway/repeater. + +The initial target is: + +``` +Frequency: 868.950 MHz +Mode: Wireless M-Bus C1 +Modulation: 2-FSK / GFSK as required +Symbol rate: approximately 100 kchip/s +Deviation: approximately ±45 kHz +Region: EU 868 MHz +``` + +Do not blindly trust these approximate values. Verify all important PHY settings against authoritative Wireless M-Bus / OMS sources and existing known-good implementations before finalizing them. + +The important goal is interoperability with real C1 meters. + +--- + +# 2. Scope of This Experiment + +Keep the initial implementation deliberately narrow. + +Implement: + +* C1 reception +* extraction/capture of complete raw Wireless M-Bus telegrams +* CRC/checksum validation where practical +* retransmission +* RX -> TX -> RX switching +* structured diagnostics +* automated SDR verification +* automated build/flash/test +* failure recovery +* long-running reliability tests + +Do NOT initially implement: + +* AES decryption +* meter-specific decoding +* billing logic +* MQTT +* Wi-Fi transport +* LTE-M +* NB-IoT +* LoRaWAN +* BLE provisioning +* production OLED UI +* full OMS repeater semantics +* production security +* cloud connectivity +* OTA +* final commercial firmware architecture + +Those can follow once the RF path is proven. + +For this experiment, prioritize understanding the RF hardware and obtaining reliable measurements. + +--- + +# 3. Important Experimental Simplification + +For this first proof of concept: + +* retransmit the received telegram as directly as technically possible; +* do not decrypt it; +* do not change application payload contents; +* do not perform meter-specific parsing; +* ignore the production repeater hop-counter issue for now; +* do not spend significant development time implementing complete EN 13757-5 repeater behavior before the physical RX/TX loop is proven. + +This is an RF feasibility experiment. + +Clearly document any deviations from actual OMS / EN 13757 repeater requirements in: + +``` +docs/STANDARDS_GAPS.md +``` + +Never silently present an experimental shortcut as standards compliant. + +--- + +# 4. Exact Heltec Hardware + +The DUT is exactly: + +``` +Product: + Heltec WiFi LoRa 32 V4 + +Model: + HTIT-WB32LAF + +Revision: + V4.3 + +MCU: + ESP32-S3 + +Sub-GHz radio: + Semtech SX1262 + +RF frontend: + KCT8103L + +RF board variant: + 868–928 MHz high-power version +``` + +This is NOT: + +* Heltec V3 +* V4.0 +* V4.1 +* V4.2 + +Do not copy older Heltec RF configuration blindly. + +--- + +# 5. Known SX1262 Pin Mapping + +Use the following board mapping as the initial authoritative working configuration: + +``` +SX1262 NSS / CS GPIO 8 +SX1262 SCK GPIO 9 +SX1262 MOSI GPIO 10 +SX1262 MISO GPIO 11 +SX1262 RESET GPIO 12 +SX1262 BUSY GPIO 13 +SX1262 DIO1 / IRQ GPIO 14 +``` + +Before extensive development, verify this mapping against the current Heltec V4.3 source/schematic where possible. + +If a discrepancy is found: + +1. stop; +2. collect evidence; +3. document it; +4. correct docs/HARDWARE.md; +5. only then modify firmware. + +Do not solve unexplained hardware conflicts by randomly changing GPIO numbers. + +--- + +# 6. KCT8103L RF Front-End + +The V4.3 uses an external KCT8103L RF front-end. + +Initial known control mapping: + +``` +FEM POWER GPIO 7 +FEM CSD / ENABLE GPIO 2 +FEM CTX GPIO 5 +``` + +Use the equivalent of Heltec's: + +``` +USE_KCT8103L_PA +``` + +configuration. + +Do NOT use: + +``` +USE_GC1109_PA +``` + +which applies to older board variants. + +The FEM configuration is critical. + +If: + +* receive sensitivity is unexpectedly poor; +* TX cannot be observed; +* RSSI is implausible; +* only extremely strong nearby signals are received; + +treat incorrect FEM configuration as one of the FIRST suspects. + +Do not immediately blame the Wireless M-Bus decoder. + +--- + +# 7. SX1262 TCXO / RF Configuration + +Determine and configure the board's TCXO correctly. + +Verify: + +* TCXO control mechanism +* DIO3 configuration where applicable +* TCXO voltage +* startup delay +* RF switch control +* FEM RX state +* FEM TX state + +Do not assume generic SX1262 breakout-board defaults are correct for this Heltec. + +Before doing any Wireless M-Bus decoding, implement a low-level radio diagnostic that confirms: + +``` +SPI communication PASS/FAIL +radio reset PASS/FAIL +BUSY behavior PASS/FAIL +chip identity/state PASS/FAIL +frequency programmed value +packet mode value +FEM state value +IRQ configuration value +``` + +Prefer machine-readable output. + +--- + +# 8. Development Environment + +The host machine is Linux/NixOS. + +Everything required for normal development must be CLI-compatible. + +Preferred firmware environment: + +``` +ESP-IDF +``` + +PlatformIO may be used if there is a strong technical reason, especially if it substantially reduces risk around known-good SX1262/Heltec support. + +Avoid unnecessary Arduino abstractions when they prevent precise radio control. + +Never require: + +* proprietary Windows software +* old .NET flashing utilities +* vendor GUIs +* manual GUI clicking +* undocumented binary tools where avoidable + +Normal workflow must be scriptable: + +``` +build +flash +reset +monitor +SDR capture +HIL test +analysis +``` + +The final loop should be callable from the shell. + +--- + +# 9. Repository Structure + +Create or maintain a clean Git repository. + +Suggested initial structure: + +``` +firmware/ + CMakeLists.txt + main/ + components/ + +hil/ + run.sh + capture_sdr.sh + capture_serial.sh + correlate.py + report.py + +tools/ + discover_devices.sh + reset_dut.sh + flash.sh + +logs/ + +captures/ + +docs/ + HARDWARE.md + RF_CONFIG.md + TESTING.md + FINDINGS.md + OPEN_QUESTIONS.md + STANDARDS_GAPS.md +``` + +Do not overengineer the repository. + +Prefer simple scripts and observable behavior. + +--- + +# 10. Git Discipline + +Use Git continuously. + +Before risky experiments, preserve the current known-good state. + +Create small commits at meaningful milestones, for example: + +``` +initial ESP32-S3 project boots + +confirmed Heltec V4.3 pin mapping + +SX1262 SPI communication working + +FEM configuration verified + +SDR C1 baseline captured + +first C1 telegram received by Heltec + +Heltec matches SDR meter telegram + +first TX visible on SDR + +first repeated C1 telegram decoded by rtl-wmbus + +automated correlation working + +100 repeat events stable + +500 repeat events stable + +radio recovery implemented +``` + +Do not destroy known-good states while experimenting. + +When an experiment fails, prefer reverting or branching over accumulating random changes. + +--- + +# 11. Device Discovery + +Never assume: + +``` +/dev/ttyACM0 +``` + +and never assume RTL-SDR device index 0. + +Implement deterministic device discovery. + +Use sources such as: + +``` +/dev/serial/by-id/ +lsusb +udev metadata +rtl_test +ESP USB VID/PID/serial information +``` + +The test harness must print which physical devices it selected. + +Example: + +``` +DUT: + /dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_... + +SDR: + Nooelec NESDR SMArt v5 + RTL serial: 00000001 +``` + +If there is ambiguity, abort instead of flashing the wrong serial device. + +--- + +# 12. Nooelec NESDR SMArt v5 Role + +The Nooelec is the independent RF truth source. + +It is RX-only. + +Do not attempt to transmit with it. + +Its job is to independently observe: + +1. real meter C1 telegram; +2. Heltec retransmission. + +The Heltec saying: + +``` +TX successful +``` + +is NOT sufficient evidence that RF transmission worked. + +Actual SDR reception is required. + +--- + +# 13. SDR Tooling + +Prefer open-source Linux tooling such as: + +``` +rtl-sdr +rtl_test +rtl_wmbus +wmbusmeters +``` + +A useful initial pipeline is approximately: + +``` +rtl_sdr \ + -f 868950000 \ + -s 1600000 \ + - \ + 2>/dev/null \ + | rtl_wmbus +``` + +Verify actual optimal parameters rather than blindly copying this command. + +Keep raw logs. + +Where useful, preserve IQ recordings for later offline inspection. + +Example capture structure: + +``` +captures/ + 2026-xx-xxTxx-xx-xx/ + rtlwmbus.log + serial.log + test.json + iq.raw + report.txt +``` + +Do not store huge IQ captures indefinitely without reason. + +--- + +# 14. Phase 0 — SDR Baseline + +Before writing repeater TX code, prove the SDR setup. + +Run the Nooelec alone. + +Capture real nearby C1 traffic. + +Record: + +* timestamp +* telegram bytes +* telegram length +* meter/device ID if extractable +* manufacturer if extractable +* decoder result +* CRC/checksum state where available +* signal level if available +* mode + +Determine which meters are reliably visible. + +The output of this phase should establish a known-good RF baseline. + +Create: + +``` +docs/SDR_BASELINE.md +``` + +Include: + +``` +number of telegrams +unique meters +capture duration +known strong meters +known marginal meters +``` + +Do not continue to debugging the Heltec if the SDR itself cannot reliably detect real meter traffic. + +--- + +# 15. Phase 1 — Low-Level SX1262 Bring-Up + +Do not immediately implement Wireless M-Bus. + +First establish basic radio control. + +Test: + +``` +SX1262 reset +SPI register access +BUSY transitions +DIO1 interrupt +TCXO +FEM power +FEM RX control +``` + +Implement a command or boot diagnostic that logs something similar to: + +``` +{ + "event": "radio_init", + "spi": true, + "busy": false, + "tcxo": true, + "fem_power": true, + "fem_mode": "rx", + "frequency_hz": 868950000, + "result": "ok" +} +``` + +If this cannot be made deterministic, do not proceed to higher-level decoding. + +--- + +# 16. Phase 2 — Heltec C1 Receiver Only + +Implement C1 RX. + +No retransmission yet. + +For every candidate Wireless M-Bus frame, generate structured serial output. + +Example: + +``` +{ + "event": "wmbus_rx", + "timestamp_us": 123456789, + "frequency_hz": 868950000, + "length": 42, + "rssi_dbm": -87, + "crc_ok": true, + "hash": "abcd1234", + "raw": "2F442D..." +} +``` + +Use monotonic timestamps for precise timing. + +If wall-clock time is also available, it may be included separately. + +Do not use only human-readable prose such as: + +``` +Received packet! +``` + +The HIL scripts need deterministic parsing. + +--- + +# 17. Compare Heltec RX Against SDR + +Run both receivers concurrently: + +``` +real meter + | + +-----> Nooelec SDR + | + +-----> Heltec +``` + +Build tooling to correlate receptions. + +For each SDR-observed telegram, determine whether the Heltec also observed it. + +Calculate: + +``` +SDR frames +Heltec frames +matched frames +SDR-only frames +Heltec-only frames +matching ratio +``` + +Break statistics down by meter where possible. + +Example: + +``` +METER SDR HELTEC MATCHED + +60968175 100 99 99 +60752048 100 92 92 +08632791 100 100 100 +``` + +This experiment is more useful than comparing nominal datasheet sensitivity. + +--- + +# 18. LNA / FEM Experiment + +If the V4.3 RF frontend allows configurable LNA behavior, explicitly test relevant configurations. + +For example: + +``` +LNA enabled +LNA disabled +``` + +Compare: + +``` +frame reception rate +RSSI +CRC failure rate +weak-meter performance +sensitivity to strong nearby signals +``` + +Do not assume that maximum gain is always best. + +Strong 868 MHz interferers can potentially make excessive frontend gain worse. + +Record the results in: + +``` +docs/RF_FRONTEND_TESTS.md +``` + +This result is important for the architecture of the future custom gateway PCB. + +--- + +# 19. Phase 3 — TX Proof of Life + +Before implementing full RX -> TX correlation, prove that the Heltec can generate detectable RF at 868.95 MHz. + +Because this is the HTIT-WB32LAF high-power variant with an external PA: + +START AT LOW OUTPUT POWER. + +Do not use maximum board output. + +The Nooelec may be only a few metres away. + +Avoid SDR overload. + +Use: + +* low configured SX1262 TX power; +* reasonable antenna separation; +* low SDR gain where necessary. + +Log the configured TX power during every experiment. + +Do not confuse: + +``` +configured SX1262 PA level +``` + +with: + +``` +actual conducted/radiated board output after external FEM. +``` + +The external KCT8103L changes the RF chain. + +--- + +# 20. Do Not Overdrive the SDR + +Avoid setups like: + +``` +Heltec at high power + -> +antenna 20 cm away + -> +SDR at maximum gain +``` + +That proves nothing useful. + +Prefer an arrangement such as: + +``` +Heltec + | + | low TX power + | + | 2–5 metres / appropriate attenuation + v +Nooelec SDR +``` + +If needed: + +* physically separate antennas; +* reduce SDR gain; +* use attenuation. + +Do not intentionally stress or overload the SDR input. + +--- + +# 21. Phase 4 — RX -> TX -> RX + +Once RX and TX work independently, implement the repeater loop. + +For each accepted C1 telegram: + +1. receive the entire frame; +2. store raw representation; +3. validate frame where appropriate; +4. calculate hash; +5. timestamp RX completion; +6. wait configurable development delay; +7. transition FEM/radio to TX; +8. transmit corresponding C1 frame; +9. wait for TX-done with timeout; +10. return FEM/radio immediately to C1 RX; +11. confirm RX state; +12. log entire transaction. + +The system must return to RX even after TX errors. + +--- + +# 22. Development Repeater Delay + +Use a deliberately short delay during HIL development. + +Default: + +``` +50 ms +``` + +Make configurable. + +Initial allowed range: + +``` +20–200 ms +``` + +The purpose is easy temporal correlation. + +Do not initially use a 5–25 second randomized production repeater delay because it makes development unnecessarily slow and makes SDR correlation harder. + +Document that production timing behavior will differ. + +--- + +# 23. Structured TX Logging + +Every transmission should produce structured output. + +Example: + +``` +{ + "event": "wmbus_tx", + "timestamp_us": 123506789, + "source_rx_timestamp_us": 123456789, + "delay_us": 50000, + "length": 42, + "hash": "abcd1234", + "configured_tx_dbm": -5, + "result": "ok" +} +``` + +Also emit failures: + +``` +{ + "event": "wmbus_tx", + "hash": "abcd1234", + "result": "timeout", + "radio_busy": true +} +``` + +Do not silently discard failed transmissions. + +--- + +# 24. Timing Instrumentation + +Measure at least: + +``` +RX packet complete +processing complete +TX requested +radio switched to TX +TX start if observable +TX done +radio switched to RX +RX ready +``` + +Use microsecond monotonic timing where possible. + +Calculate: + +``` +RX processing time +programmed repeat delay +RX -> TX latency +TX airtime +TX -> RX transition time +total RX deaf time +``` + +These values are important for the future commercial gateway architecture. + +--- + +# 25. SDR Correlation Model + +The SDR should observe approximately: + +``` +ORIGINAL + +telegram X +timestamp = T0 +``` + +then: + +``` +REPEAT + +telegram X +timestamp approximately T0 + repeater_delay +``` + +The Heltec serial log should independently report: + +``` +RX hash X +TX hash X +``` + +The automated tester must correlate: + +``` +SDR original + <-> +Heltec RX + <-> +Heltec TX + <-> +SDR retransmission +``` + +This closes the hardware-in-the-loop. + +--- + +# 26. Correlation Rules + +Prefer exact raw-frame equality. + +If appropriate: + +``` +hash = SHA256(raw frame) +``` + +or another collision-resistant deterministic hash. + +Correlation should use: + +* exact raw bytes +* hash +* timestamp proximity +* expected repeat delay + +Suggested initial timing window: + +``` +earliest repeat: 10 ms after original +latest repeat: 300 ms after original +``` + +Make configurable. + +Do not classify a naturally recurring meter telegram seconds later as a repeater event. + +--- + +# 27. False-Positive Avoidance + +Real meters may: + +* transmit periodic identical data; +* issue similar frames; +* retransmit on their own; +* increment counters; +* transmit rapidly. + +Therefore the test harness must distinguish: + +``` +original +Heltec repeat +natural meter repeat +unrelated meter +duplicate decoder output +``` + +Use exact byte comparison plus timing. + +During early testing, it is acceptable to whitelist one or a small number of known meter IDs at the HIL layer. + +Do not hard-code those IDs into the actual radio driver. + +--- + +# 28. HIL Test Runner + +Create one primary command: + +``` +./hil/run.sh +``` + +It should perform as much of the complete development verification loop as practical. + +Approximately: + +1. discover DUT; +2. discover Nooelec SDR; +3. run basic SDR sanity test; +4. build firmware; +5. flash Heltec; +6. reset Heltec; +7. open structured serial capture; +8. start SDR C1 capture; +9. wait for real meter traffic; +10. collect Heltec RX events; +11. collect Heltec TX events; +12. collect SDR frames; +13. correlate originals and repeats; +14. calculate metrics; +15. detect firmware reset/lockup; +16. save all logs; +17. produce report; +18. return useful shell exit code. + +PASS should return: + +``` +0 +``` + +FAIL should return nonzero. + +This makes the system usable by an autonomous coding agent. + +--- + +# 29. Example HIL Report + +Produce reports approximately like: + +``` +================================================== +SOLENOS WMBUS HIL TEST +================================================== + +DUT: + Heltec WiFi LoRa 32 V4.3 + HTIT-WB32LAF + +RF: + frequency: 868.950 MHz + mode: C1 + configured TX power: -5 dBm + repeat delay: 50 ms + +TEST: + duration: 300 s + +SDR: + original frames: 47 + unique meters: 6 + +HELTEC RX: + frames: 46 + matched originals: 45 + match rate: 95.7 % + +HELTEC TX: + attempts: 45 + reported success: 45 + +SDR VERIFIED REPEATS: + matched: 44 + success rate: 97.8 % + +TIMING: + median repeat delay: 51.4 ms + minimum: 49.8 ms + maximum: 54.1 ms + + median RX deaf time: ... + maximum RX deaf time: ... + +ERRORS: + CRC errors: 2 + TX timeout: 0 + radio recoveries: 0 + MCU resets: 0 + +RESULT: + PASS +``` + +Store a machine-readable JSON version too. + +--- + +# 30. Initial Success Criteria + +The first milestone does NOT require perfect performance. + +It requires evidence that: + +* Nooelec independently receives real C1 telegrams; +* Heltec receives the same real C1 traffic; +* raw frames can be correlated; +* Heltec can transition RX -> TX; +* Heltec generates RF that the SDR detects; +* rtl-wmbus or equivalent recognizes the retransmission as Wireless M-Bus; +* frame data matches as expected; +* Heltec returns to RX after TX; +* multiple cycles work without manual intervention. + +Do not declare success based on one packet. + +--- + +# 31. Progressive Reliability Targets + +After first successful repeat: + +## Milestone A + +``` +>= 10 verified retransmissions +``` + +without firmware restart. + +## Milestone B + +``` +>= 100 verified retransmissions +``` + +Collect detailed metrics. + +## Milestone C + +``` +>= 500 verified retransmissions +``` + +No manual intervention. + +## Milestone D + +``` +>= 1000 events where practical +``` + +Record: + +* TX success rate +* SDR-confirmed TX rate +* RX match rate +* missed meter frames +* CRC failures +* radio recoveries +* MCU resets +* maximum radio lock time +* timing distribution + +Only after longer tests should the implementation be described as stable. + +--- + +# 32. Failure Recovery + +The firmware must not permanently stop because of: + +* malformed frame +* unexpected packet length +* SX1262 TX timeout +* BUSY stuck +* IRQ issue +* CRC failure +* state-machine bug +* buffer overflow +* failed mode transition + +Every blocking radio operation must have a bounded timeout. + +Preferred recovery hierarchy: + +``` +operation retry + -> +clear IRQ/state + -> +radio standby + -> +radio reinitialize + -> +FEM reinitialize + -> +resume RX + -> +MCU watchdog reset only as final fallback +``` + +Log every recovery. + +Example: + +``` +{ + "event": "radio_recovery", + "reason": "tx_timeout", + "level": 3, + "result": "rx_restored" +} +``` + +A recovery that succeeds is still something the test report should count. + +--- + +# 33. Watchdogs + +Use appropriate watchdogs. + +The watchdog should catch catastrophic firmware deadlocks. + +Do NOT use repeated whole-MCU rebooting as normal radio state management. + +The goal is unattended reliability. + +--- + +# 34. Automated Agent Loop + +Operate iteratively and autonomously. + +Preferred loop: + +``` +inspect current state + -> +formulate hypothesis + -> +collect evidence + -> +make minimal change + -> +build + -> +flash + -> +run HIL + -> +inspect serial + -> +inspect SDR result + -> +compare expected/actual + -> +diagnose + -> +commit if improved + -> +repeat +``` + +Prefer evidence over speculation. + +Do not randomly alter: + +* bandwidth +* bitrate +* deviation +* frequency +* preamble +* sync word +* FEM state + +all at once. + +Change one meaningful RF variable at a time. + +Record experimental values and results. + +--- + +# 35. Scientific RF Debugging + +When RX does not work, investigate systematically: + +1. SDR confirms meter exists? +2. frequency correct? +3. radio SPI functioning? +4. TCXO running/configured? +5. FEM powered? +6. FEM in RX state? +7. bandwidth correct? +8. bitrate correct? +9. deviation correct? +10. sync/preamble handling correct? +11. packet mode correct? +12. interrupt firing? +13. raw symbols observable? +14. decoder issue? + +Do not immediately rewrite the decoder. + +--- + +# 36. TX Debugging + +When TX is not observed by the SDR: + +1. confirm firmware reached TX request; +2. inspect BUSY; +3. inspect IRQ; +4. confirm FEM TX state; +5. confirm configured frequency; +6. confirm modem parameters; +7. confirm TX done; +8. verify antenna path; +9. verify SDR is not saturated; +10. verify signal exists in raw spectrum/IQ; +11. verify packet is actually C1-compatible. + +Differentiate: + +``` +no RF +``` + +from: + +``` +RF exists but rtl-wmbus cannot decode it. +``` + +That distinction is extremely important. + +--- + +# 37. IQ Capture as Escalation Tool + +If rtl-wmbus reports nothing but TX appears to happen: + +capture short IQ recordings around TX events. + +Use those only when needed. + +The agent should be able to establish: + +``` +energy exists at 868.95 MHz +``` + +even when packet decoding fails. + +This separates: + +``` +transmitter path broken +``` + +from: + +``` +modulation/framing wrong. +``` + +Keep IQ captures short and correlated with Heltec TX timestamps. + +--- + +# 38. Serial Observability + +The serial console should expose enough state to debug remotely. + +Useful commands may include: + +``` +status +radio status +radio reset +radio rx +test rx +test tx +set tx_power ... +set repeat_delay ... +stats +clear stats +reboot +``` + +Commands should be scriptable. + +Avoid interactive menu systems requiring arrow keys. + +Where appropriate, offer JSON output. + +--- + +# 39. Runtime Configuration + +At minimum make these configurable without source editing if practical: + +``` +repeat delay +TX power +meter whitelist +logging verbosity +retransmission enabled/disabled +``` + +Do not add a giant configuration system. + +Simple serial commands or build-time defaults are acceptable. + +--- + +# 40. Metrics + +Maintain counters inside firmware. + +At minimum: + +``` +uptime +RX candidate frames +RX valid frames +RX CRC failures +RX bytes +TX attempts +TX success +TX failures +TX timeout +radio reinitializations +FEM reinitializations +watchdog resets +buffer overflows +``` + +Expose through: + +``` +stats +``` + +and optionally structured periodic diagnostics. + +--- + +# 41. Memory Safety + +Treat RF packet lengths as hostile/untrusted input. + +Never assume packet length is valid. + +Use bounded buffers. + +Validate: + +``` +minimum frame size +maximum frame size +decoder indexes +CRC region +encoded TX buffer size +``` + +Avoid unsafe memory operations. + +This firmware should eventually run unattended. + +--- + +# 42. Debug Builds vs Release Builds + +Maintain at least: + +``` +debug +``` + +and: + +``` +release/test +``` + +configurations. + +Debug can include: + +* verbose logs +* assertions +* extra timing +* register dumps + +Release/test should avoid excessive serial traffic that could change timing. + +Do not optimize prematurely. + +--- + +# 43. Physical Board Information + +Create: + +``` +docs/HARDWARE.md +``` + +It should explicitly contain: + +``` +Board: + Heltec WiFi LoRa 32 V4.3 + HTIT-WB32LAF + +MCU: + ESP32-S3 + +Radio: + SX1262 + +FEM: + KCT8103L + +SX1262: + NSS GPIO8 + SCK GPIO9 + MOSI GPIO10 + MISO GPIO11 + RESET GPIO12 + BUSY GPIO13 + DIO1 GPIO14 + +FEM: + POWER GPIO7 + CSD GPIO2 + CTX GPIO5 +``` + +Include links/references to the authoritative sources used to confirm these facts. + +If later measurements contradict documentation, clearly distinguish: + +``` +DOCUMENTED +``` + +from: + +``` +EXPERIMENTALLY VERIFIED +``` + +--- + +# 44. Maintain FINDINGS.md + +Continuously update: + +``` +docs/FINDINGS.md +``` + +Use sections such as: + +``` +CONFIRMED +LIKELY +DISPROVEN +NEEDS TESTING +``` + +Examples: + +``` +CONFIRMED: +- Nooelec sees meter X at 868.95 MHz. +- Heltec receives the same exact raw C1 telegram. +- FEM GPIO mapping verified experimentally. +- repeated telegram independently decoded by SDR. + +DISPROVEN: +- RadioLib default Heltec V4 configuration works unchanged. + +NEEDS TESTING: +- LNA improves marginal meter reception. +- TX power setting X corresponds to approximately Y effective output. +``` + +Do not allow assumptions to silently become facts. + +--- + +# 45. Maintain OPEN_QUESTIONS.md + +Examples: + +``` +- exact optimum SX1262 RX bandwidth? +- best C1 synchronization strategy? +- effect of KCT8103L LNA on blocking? +- RX dead time during retransmit? +- ability to receive immediately following TX? +- exact production repeater framing requirements? +- required regulatory output limits? +``` + +Close questions with evidence. + +--- + +# 46. Document Standards Gaps + +Maintain: + +``` +docs/STANDARDS_GAPS.md +``` + +Examples: + +``` +Experimental implementation: + repeats raw telegram with 50 ms delay + +Production requirement: + proper EN 13757-5 / OMS repeater semantics need review +``` + +This prevents experimental shortcuts becoming production assumptions. + +--- + +# 47. No Premature Production Work + +Do not start designing: + +* custom PCB +* LTE integration +* LoRaWAN integration +* production battery subsystem +* enclosure +* certification architecture + +until the core wM-Bus RF feasibility questions are answered. + +This experiment exists to reduce uncertainty for the future Solenos/Gebos gateway. + +--- + +# 48. Capture Information Useful for the Future Dev PCB + +While developing, maintain: + +``` +docs/DEVBOARD_REQUIREMENTS.md +``` + +Whenever a hardware signal becomes useful for debugging, record it. + +For example: + +``` +SX1262 BUSY +SX1262 DIO1 +SPI CLK +MOSI +MISO +RESET +FEM POWER +FEM CSD +FEM CTX +3V3 rail +radio power rail +ESP32 RESET +ESP32 BOOT +``` + +Also record: + +``` +"I needed direct access to this signal because ..." +``` + +The eventual large Solenos development PCB should expose all signals that repeatedly proved useful during this experiment. + +This experiment is therefore also intended to determine the debug/test-point requirements of the custom gateway. + +--- + +# 49. Keep a Dev-Board Pin Wishlist + +Maintain a machine-readable file: + +``` +docs/devboard_signals.csv +``` + +with columns such as: + +``` +signal +device +gpio +direction +voltage +interrupt +timing_critical +test_point_required +header_required +reason +``` + +Example: + +``` +WMBUS_DIO1,SX1262,14,input,3.3,true,true,true,true,RX/TX IRQ debugging +``` + +Use the actual development experience to populate it. + +--- + +# 50. Definition of Done for This Experiment + +The experiment is considered successful only when one shell command can perform an automated HIL test, for example: + +``` +./hil/run.sh --duration 300 +``` + +and produce quantitative evidence similar to: + +``` +SDR receives original real-meter C1 telegram + ✓ + +Heltec receives same raw telegram + ✓ + +Heltec retransmits it + ✓ + +Nooelec independently sees retransmission + ✓ + +retransmitted packet decodes as C1 + ✓ + +bytes correlate + ✓ + +Heltec returns to RX + ✓ + +repeated cycles succeed + ✓ + +no manual interaction needed + ✓ +``` + +The final report must quantify performance rather than merely print: + +``` +TEST PASSED +``` + +--- + +# 51. Final Deliverables + +At the end of the experiment the repository should contain: + +## Working firmware + +Reliable experimental: + +``` +C1 RX -> delay -> C1 TX -> RX +``` + +for: + +``` +Heltec WiFi LoRa 32 V4.3 +HTIT-WB32LAF +``` + +## Automated HIL test + +Using: + +``` +Nooelec NESDR SMArt v5 +``` + +as independent RF observer. + +## Quantitative RF results + +Including: + +``` +Heltec vs SDR reception rate +retransmission success rate +RX dead time +RX->TX latency +radio recovery statistics +LNA/FEM observations +``` + +## Hardware findings + +Including confirmed: + +``` +GPIO mapping +FEM behavior +radio configuration +useful debug signals +``` + +## Future dev-board requirements + +Including: + +``` +devboard_signals.csv +DEVBOARD_REQUIREMENTS.md +``` + +These will be used when designing the large instrumented Solenos/Gebos gateway development PCB. + +--- + +# 52. Development Priorities + +When forced to choose, prioritize in this order: + +1. protect hardware; +2. preserve known-good code; +3. obtain measurable evidence; +4. make testing repeatable; +5. achieve correct RF behavior; +6. improve reliability; +7. improve code architecture; +8. optimize performance; +9. optimize elegance. + +Do not trade observable working behavior for unnecessary abstraction. + +--- + +# 53. Important Autonomy Rules + +You are expected to operate autonomously. + +Do not stop simply because: + +* a build fails; +* a dependency is missing; +* a test fails; +* a radio parameter was wrong; +* a library does not support exactly what is needed. + +Investigate and fix ordinary development problems yourself. + +Install or declaratively add required development dependencies in a way appropriate for NixOS. + +Prefer reproducible environments. + +If useful, create: + +``` +flake.nix +``` + +or equivalent project-local Nix configuration containing the required development tools. + +Do not modify the host system globally without necessity. + +Do not ask the human to perform actions that are scriptable from the machine. + +--- + +# 54. Hard Safety Boundaries + +Do not: + +* intentionally use maximum RF output unnecessarily; +* knowingly violate hardware voltage limits; +* blindly toggle unknown GPIOs that could control power circuitry; +* rewrite USB devices that are not confidently identified; +* repeatedly flash an ambiguous serial device; +* disable hardware protection mechanisms merely to make a test pass. + +When uncertainty could physically damage hardware, stop that specific action and gather information first. + +This does not mean stopping the overall task. + +Continue with safe diagnostics. + +--- + +# 55. Working Philosophy + +Treat the SDR as the RF truth source. + +Treat structured serial telemetry as the firmware truth source. + +Treat repeatable experiments as more valuable than intuition. + +Treat datasheets and authoritative source code as more valuable than forum guesses. + +Treat one controlled variable change as more valuable than ten speculative changes. + +Do not claim something works until it has been independently observed. + +The desired loop is: + +``` +CODE + ↓ +BUILD + ↓ +FLASH + ↓ +REAL RF INPUT + ↓ +HELTEC RX + ↓ +HELTEC TX + ↓ +SDR OBSERVATION + ↓ +AUTOMATED CORRELATION + ↓ +PASS / FAIL + ↓ +DIAGNOSIS + ↓ +NEXT ITERATION +``` + +The final goal is not merely a demo. + +The goal is a reproducible hardware-in-the-loop development environment that can continue to be used for future Solenos/Gebos embedded development. +