Files

1950 lines
31 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.