62 lines
3.1 KiB
Markdown
62 lines
3.1 KiB
Markdown
# MAIN TX watcher usage
|
|
|
|
## Purpose
|
|
|
|
tools/tx_agent_watcher.py is an ordinary local Python process. It polls the small RX result on origin/rx-node. It does not call an LLM and does not open HackRF hardware.
|
|
|
|
## Start
|
|
|
|
From the repository root, double-click:
|
|
|
|
tools\start_tx_watcher.cmd
|
|
|
|
The visible console polls every 5 seconds. A missing rx-node branch or invalid result is reported. No model runs while polling.
|
|
|
|
## Result history cursor
|
|
|
|
The watcher stores `last_processed_rx_node_commit` in `.local\tx_agent_watcher_state.json`. After each fetch it enumerates every commit in:
|
|
|
|
last_processed_rx_node_commit..origin/rx-node
|
|
|
|
It reads `RX_RESULT.json` from each exact commit and processes the commits from oldest to newest. READY therefore remains observable when READY and COMPLETE are both published between two polling cycles.
|
|
|
|
The cursor advances only after that commit has been read, validated and handled successfully. A malformed intermediate commit blocks later commits until the defect is corrected. A non-fast-forward rewrite of `rx-node` is rejected. Duplicate result content is suppressed, but its commit is still marked as processed.
|
|
|
|
State format version 2 retains the existing digest and authorization fields and adds `last_seen_commit` and `last_processed_rx_node_commit`. A version-1 digest-only state is mapped to the newest matching commit in the existing result history. Back up the local state before manual recovery; do not delete it blindly.
|
|
|
|
## READY and RED approval
|
|
|
|
RF_HANDOFF_CHANNEL_TEST_001 READY and COMPLETE states are recorded without a RED prompt and never open the production gate.
|
|
|
|
For a fresh valid RF001A_OTA_CAPTURE_003 READY result, the watcher checks the expected source HEAD, current origin/rx-node commit, common clock and capture window. It then prints the task ID, capture start and expected end and asks for:
|
|
|
|
AUTHORIZE RF TX
|
|
|
|
Any other input blocks authorization.
|
|
|
|
After the exact phrase, the watcher fetches rx-node again. It requires the same result digest and commit, the expected source HEAD, a fresh publication, an active 120-second capture window, verified common clock and at least 10 seconds remaining. An expired historical READY is recorded as observed but cannot create an authorization.
|
|
|
|
On success it writes:
|
|
|
|
.local\tx_authorizations\RF001A_OTA_TX_003_authorized.json
|
|
|
|
This record opens the gate for the separately controlled TX executor. The watcher itself does not run hackrf_transfer. The record explicitly says rf_tx_started = false and rf_tx = 0.
|
|
|
|
The TX executor must re-fetch rx-node and compare the result commit and digest immediately before hardware access.
|
|
|
|
## Stop
|
|
|
|
Double-click:
|
|
|
|
tools\stop_tx_watcher.cmd
|
|
|
|
The stop command writes a local stop request and waits for the watcher PID to clear.
|
|
|
|
## Fake mode
|
|
|
|
Automated tests use a local bare Git repository. For a single local JSON fixture, the CLI dry-run form is:
|
|
|
|
python -B tools/tx_agent_watcher.py --dry-run --once --result-file <ready-json> --approval authorize
|
|
|
|
The --approval option is rejected outside --dry-run. Fake mode writes a local fake authorization and never fetches the production remote or accesses SDR hardware.
|