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