turov_av/SDR-Rover
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Harden RF handoff and stream OTA decode

Browse Source
This commit is contained in:
LittleSam129
2026-09-22 17:43:58 +03:00
parent 168e03d9e7
commit a94f2db4ee
17 changed files with 1548 additions and 497 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/handoff/RX_AGENT_PROTOCOL.md
View File

@@ -12,7 +12,7 @@ The MAIN-to-RX acknowledgement channel uses the independent origin/tx-node branc
docs/handoff/NEXT_RX_TASK.md starts with these plain key-value fields:
TASK_ID = RF001A_OTA_CAPTURE_003
TASK_ID = RF001A_OTA_CAPTURE_004
TASK_TITLE = Start coordinated RF-001A common-clock OTA capture
SOURCE_BRANCH = video-development
EXPECTED_HEAD = <full 40-character base commit hash>
@@ -73,11 +73,11 @@ After the task actually finishes, mark the local ID complete:
The coordinated RF-001A result is a strict JSON object. Unknown or missing keys are rejected. READY requires:
- task_id = RF001A_OTA_CAPTURE_003;
- task_id = RF001A_OTA_CAPTURE_004;
- state = RX_READY_FOR_TX;
- rx_ready_for_tx, process_alive, file_growing and common_clock_verified all true;
- a positive capture_pid;
- 120-second planned duration;
- 60-second planned duration;
- rf_tx = 0;
- final capture fields set to null.
@@ -95,6 +95,12 @@ Timestamps use timezone-aware ISO-8601. source_head is the actual local 40-chara
## Publishing to rx-node
Before any production hardware access, run
`python -B tools/rx_agent_watcher.py --check-result-write`. It performs an
authenticated fetch, a no-change `git push --dry-run` of the existing rx-node
HEAD to the same ref, and a second remote HEAD check. Failure blocks capture.
The check creates no commit and no READY event.
Publish a prepared local JSON file with:
python -B tools/rx_agent_watcher.py --publish-result <result-json> --result-branch rx-node
@@ -114,7 +120,14 @@ It checks the branch with git fetch and git ls-remote through the real origin co
docs/handoff/results/RX_RESULT.json
docs/handoff/results/RX_RESULT.md
It checks the staged path set, commits, pushes HEAD:rx-node, and confirms that git ls-remote returns the new commit. It then removes the temporary worktree. It never switches the source checkout. It rejects any additional staged path and enforces a 64 KiB limit per result file.
It checks the staged path set, creates one immutable commit, pushes that exact
commit hash to rx-node, and confirms that `git ls-remote` returns it. After a
recognized transient network or authentication error, it first checks whether
the commit already reached the remote. If not, it fetches and may retry that
same commit once. It never creates a second READY commit or changes the payload
between attempts. It then removes the temporary worktree. It never switches
the source checkout. It rejects any additional staged path and enforces a
64 KiB limit per result file.
Raw IQ, video, waveform files, large logs, secrets and machine-local state remain outside Git. A missing result branch or failed push is reported and never authorizes TX.
@@ -132,7 +145,12 @@ For each successfully handled channel-test event, the MAIN watcher publishes a s
The tx-node publisher stages exactly `docs/handoff/results/TX_RESULT.json` and `docs/handoff/results/TX_RESULT.md`, checks the staged path allowlist and enforces 64 KiB per file. A push failure prevents the rx-node cursor from advancing. Duplicate acknowledgements are suppressed by their source binding. No local state, code, IQ, video, waveform or large log is published.
A successful gate writes one local authorization record under .local/tx_authorizations/. The record has rf_tx_started = false and rf_tx = 0. The separately controlled TX executor must re-fetch and compare the result commit and digest immediately before opening hardware.
A successful gate publishes a schema-version-2 `TX_AUTHORIZED` event and writes
one local authorization record under `.local/tx_authorizations/`. The record
has `rf_tx_started = false` and `rf_tx = 0`. The separately controlled TX
executor must re-fetch and compare the result commit and digest immediately
before opening hardware. It then publishes `TX_STARTED` at process start and
`TX_COMPLETE` after exit with UTC timestamps, exit code, underruns and errors.
Duplicate result digests are not shown repeatedly.
@@ -147,6 +165,6 @@ Duplicate result digests are not shown repeatedly.
## Bidirectional channel and dry-run contracts
The completed preflight channel command published synthetic READY and COMPLETE results with TASK_ID RF_HANDOFF_CHANNEL_TEST_001 through origin/rx-node. The MAIN watcher observed both without a RED prompt. The RX watcher now requires exact matching acknowledgements in origin/tx-node before RF001A_OTA_CAPTURE_003 can pass its software gate.
The completed preflight channel command published synthetic READY and COMPLETE results with TASK_ID RF_HANDOFF_CHANNEL_TEST_001 through origin/rx-node. The MAIN watcher observed both without a RED prompt. The RX watcher now requires exact matching acknowledgements in origin/tx-node before RF001A_OTA_CAPTURE_004 can pass its software gate.
Automated coordination tests use a temporary local bare Git repository and independent rx-node and tx-node branches. They cover exact commit and digest binding, duplicate suppression, two commits between polls, stale acknowledgement rejection, missing tx-node, push failure, non-fast-forward protection and a full fake two-way flow without accessing the real remote or SDR hardware and without transmitting RF.