Fix RF-001A common-clock verification

docs/handoff/NEXT_RX_TASK.md

@@ -7,45 +7,76 @@ stop and report the conflict.
 # Current RX task
 
 TASK =
-PREPARE RF-001A COMMON-CLOCK RX
+VERIFY RF-001A SLAVE CLKIN
 
-1. In the project path from RX_NODE_STATE.md, record branch, HEAD and `git status --short --untracked-files=no`. Require clean tracked state and `video-development`. Run `git pull origin video-development`; then require local HEAD = `origin/video-development`. Do not commit or push.
-2. Read `configs/rf/rf001a_common_clock.json` and `docs/rf/RF_001A_PREPARATION.md`. Run `python -B -X utf8 tools/rf001a_prepare.py --verify-dir <TX artifact directory>` only if the TX artifact has been transferred locally; otherwise run `python -B -X utf8 -c "from tools.rf001a_prepare import load_spec; print(load_spec())"` to check the shared spec against the existing PHY. Do not substitute a video fixture or alter the expected hashes.
-3. Run fixture-independent RF TARGETED PYTEST, Ruff, Pyright and `git diff --check`:
-```powershell
-python -B -m pytest tests/test_packet.py tests/test_video003_modem.py tests/test_video005_iq.py tests/test_rf001_preparation.py tests/test_rf001a_prepare.py tests/test_clock001.py tests/test_hackrf_process_check.py -q
-python -B -m ruff check tools/rf001a_prepare.py tests/test_rf001a_prepare.py tools/qpsk_rf_common.py tools/qpsk_rf_tx.py tools/qpsk_rf_rx.py
-python -B -m pyright --project pyrightconfig.json
-git diff --check
-```
-These checks do not use the VIDEO-001 file or historical Lab064 metadata. Repeat the existing offline RF-001 100/100 packet check in new local paths. Missing prerequisites remain failures; do not label blocked video tests PASS.
-4. Run `hackrf_info`, save full output, and confirm this is the RX device. Check shared-spec center frequency 1400000000 Hz, sample rate 8000000/s, RX LNA 24 dB, RX VGA 24 dB, RF amp OFF, antenna bias OFF and digital carrier +125000 Hz. Confirm `hackrf_transfer -h` maps `-l` to RX LNA, `-g` to RX VGA, `-a 0` to amp OFF and `-p 0` to bias OFF. Record actual RX serial.
-5. Prepare a new unique raw IQ output directory outside Git, preserving existing captures. Check at least 320000000 bytes plus comfortable free-space margin on the destination volume. The 20 s finite capture is 160000000 complex samples in signed interleaved I/Q cs8, exactly 320000000 bytes (about 320 MB / 305.2 MiB). Prepare this command with the actual RX serial and a new path; **do not run it in this preparation task**:
-```powershell
-& '<verified hackrf_transfer.exe path>' -d <RX_SERIAL> -r <NEW_RAW_IQ_PATH.cs8> -f 1400000000 -s 8000000 -n 160000000 -l 24 -g 24 -a 0 -p 0 -B
-```
-6. Manual checkpoint for a future coordinated session: both antennas and USB connections, 10 MHz reference → MASTER → MASTER CLKOUT → SLAVE CLKIN, roles, polarization and safe distance. Freshly verify MASTER/SLAVE reg29 and SLAVE CLKIN. Old 0x26/DETECTED readings are historical only. Record `COMMON CLOCK VERIFIED = YES / NO`; until YES, RF TX is prohibited. RX capture also waits for the later coordinated task.
-7. Future session sequence: start finite RX capture, confirm it is active, then a separately authorized one-shot TX, finish capture, preserve full raw IQ plus stdout/stderr and every available intermediate/final overrun or underrun observation, then decode the same raw IQ offline with existing `qpsk_rf_rx.py --iq-format cs8`. Record size, sample count, duration and SHA256. Missing or incomplete counters are NOT_REPORTED, never zero.
-8. Report readiness and STOP. No RX capture now, RF TX, continuous RX, firmware/CPLD updates, hackrf_spiflash, Zadig, USB driver changes, commit or push. Keep large IQ/video out of Git.
+The main PC has already completed the official source-side command for MASTER serial `000000000000000097c063dc323b97d3`:
 
+```powershell
+hackrf_clock.exe -d 000000000000000097c063dc323b97d3 -o 1
+```
+
+The command returned exit code 0. Treat this as `MASTER CLKOUT COMMAND = PASS`. Do not use `hackrf_clock -r 3` or Si5351 register 29 as a blocking test of physical CLKOUT. The common clock is still unverified until this RX task confirms the signal at SLAVE CLKIN before and after a short RX-start. RF TX remains 0.
+
+1. In the project path from RX_NODE_STATE.md, record `git status --short --untracked-files=no`, branch and HEAD. Require a clean tracked checkout and branch `video-development`. Run `git pull origin video-development`; then require local HEAD = `origin/video-development`. Do not commit or push.
+
+2. Run `hackrf_info` with the verified local host tools and preserve its complete stdout. Require exactly this RX serial:
+
+```text
+000000000000000097c063dc2e5327d3
+```
+
+Stop if the device is absent or the serial differs. Do not change firmware, CPLD, USB drivers or Zadig.
+
+3. With the physical cable connected from MASTER CLKOUT to SLAVE CLKIN, run the official partner-side check with the explicit RX serial and preserve complete stdout:
+
+```powershell
+& '<verified hackrf_clock.exe path>' -d 000000000000000097c063dc2e5327d3 -i
+```
+
+Accept only the exact line `CLKIN status: clock signal detected` as `SLAVE CLKIN BEFORE RX = DETECTED`. If the signal is not detected, set `COMMON CLOCK RX VERIFIED = NO` and stop. Do not alter clock configuration automatically.
+
+4. If CLKIN was detected, perform one short, finite RX-start on SLAVE. This opens receive mode only; it does not transmit and does not create the 20-second capture:
+
+```powershell
+& '<verified hackrf_transfer.exe path>' -d 000000000000000097c063dc2e5327d3 -r NUL -f 1400000000 -s 8000000 -n 65536 -l 0 -g 0 -a 0 -p 0 -B
+```
+
+Require exit code 0 and a complete transfer of 65536 complex samples. Record all reported overruns and errors. Any nonzero overrun, USB error, incomplete transfer or nonzero exit code means `SHORT RX START = FAIL` and stops the task.
+
+5. Immediately after the short RX-start, repeat the same explicit `hackrf_clock.exe ... -i` command and preserve complete stdout. Require the exact line `CLKIN status: clock signal detected`. Set `COMMON CLOCK RX VERIFIED = YES` only when CLKIN was detected before RX, the short RX-start passed, and CLKIN remained detected after RX.
+
+6. Register 29 may be read only as optional diagnostic information with the already verified read-only command. It is not a PASS/FAIL criterion. Do not use `hackrf_debug` to write registers. Do not use `hackrf_clock -r 3` as a blocking criterion.
+
+7. Set `RX READY TO CAPTURE = YES` only if the branch/HEAD checks, RX serial check and all three clock checks in step 5 pass. This readiness does not authorize a capture or transmission. Do not start the 20-second RF-001A capture, RF TX, continuous RX, RF-001B, firmware/CPLD updates, `hackrf_spiflash`, Zadig or USB driver changes.
+
+8. Finish with this exact report and STOP:
+
+```text
 TASK =
-PREPARE RF-001A COMMON-CLOCK RX
+VERIFY RF-001A SLAVE CLKIN
+
 BRANCH =
 HEAD =
-SHARED TEST SPEC =
-RF TARGETED PYTEST =
-RUFF =
-PYRIGHT =
-GIT DIFF CHECK =
-OFFLINE RF-001 =
-HACKRF INFO =
+
 RX SERIAL =
-RX CAPTURE COMMAND PREPARED =
-RX CAPTURE FREE SPACE =
-COMMON CLOCK VERIFIED =
-PHYSICAL CHECKPOINT =
+
+SLAVE CLKIN BEFORE RX =
+DETECTED / NOT_DETECTED
+
+SHORT RX START =
+PASS / FAIL
+
+SLAVE CLKIN AFTER RX =
+DETECTED / NOT_DETECTED
+
+COMMON CLOCK RX VERIFIED =
+YES / NO
+
 RX READY TO CAPTURE =
 YES / NO
+
 RF TX =
 0
+
 STOP.
+```

docs/handoff/NEXT_TX_TASK.md

@@ -4,32 +4,37 @@ Read TX_NODE_STATE.md first. If chat history, this file, the shared spec, and cu
 # Current TX task
 
 TASK =
-PREPARE RF-001A COMMON-CLOCK TX
+WAIT FOR RF-001A SLAVE CLKIN VERIFICATION
 
-1. Record branch, HEAD and tracked Git status. Require video-development and agreement with origin/video-development.
-2. Read configs/rf/rf001a_common_clock.json and docs/rf/RF_001A_PREPARATION.md. Check all parameters against the shared spec; do not adjust them silently.
-3. Run hackrf_info and record board, serial, libhackrf and firmware. Stop if HackRF is absent. Do not invoke transmit.
-4. Verify the local canonical waveform and cs8 file using `python -B -X utf8 tools/rf001a_prepare.py --verify-dir data/raw/rf001/rf001a_common_clock_001`. Require both exact SHA256 values from the shared spec, count, duration, I/Q order, signed format, zero rail codes and checked quantization error. If local files are absent, create a new unique directory with `--output-dir`, then verify; never overwrite prior files. Keep raw IQ out of Git.
-5. Repeat the offline RX of that exact cs8 file with `tools/qpsk_rf_rx.py --iq-format cs8`, `tx_metadata.json` truth and a new report path. Require 100/100 CRC-valid and 100/100 exact packets. Preserve stdout and JSON.
-6. Check center frequency, sample rate, +125 kHz digital offset and gains against the shared spec. Prepare the one-shot command shown in RF_001A_PREPARATION.md, but do not execute it.
-7. Manual physical checkpoint: TX and RX antennas, both USB links, 10 MHz reference, MASTER/SLAVE roles, same antenna polarization, safe lab distance (about 1.2 m LOS if applicable), and no direct unattenuated TX RF → RX RF connection. Freshly verify MASTER and SLAVE reg29 and SLAVE CLKIN detection. Historical values 0x26/DETECTED do not count. Record COMMON CLOCK VERIFIED = YES / NO. If NO or unknown, TX remains prohibited.
-8. Read RX preparation report. Do not infer RX readiness from older preflight. End before first RF TX. No firmware/CPLD, hackrf_spiflash, Zadig or driver changes.
+MASTER SERIAL =
+000000000000000097c063dc323b97d3
+
+MASTER CLKOUT COMMAND =
+PASS
+
+The official source-side command completed with exit code 0:
+
+```powershell
+hackrf_clock.exe -d 000000000000000097c063dc323b97d3 -o 1
+```
+
+The earlier `hackrf_clock -r 3` output and register 29 are diagnostic information only. They do not prove whether the physical MASTER output reaches SLAVE. Do not use them as blocking criteria for common-clock verification.
+
+The common clock remains unverified until RX laptop task `VERIFY RF-001A SLAVE CLKIN` reports the exact `CLKIN status: clock signal detected` line both before and after its finite 65536-sample RX-start. Only then may the combined result be recorded as `COMMON CLOCK VERIFIED = YES`.
+
+The physical checkpoint reported by the user is: both antennas connected, both SDR USB links connected, MASTER CLKOUT connected by coaxial cable to SLAVE CLKIN, about 2 m LOS, and equal antenna polarization.
+
+Do not repeat RF-001A transmission preparation or start RF TX in this task. Do not change PLL, sample clock, other clock outputs, registers, firmware, CPLD, Zadig or USB drivers.
 
 TASK =
-PREPARE RF-001A COMMON-CLOCK TX
+WAIT FOR RF-001A SLAVE CLKIN VERIFICATION
 BRANCH =
 HEAD =
-HACKRF INFO =
-CANONICAL SHA256 =
-HARDWARE CS8 SHA256 =
-HARDWARE-FORMAT OFFLINE ROUNDTRIP =
-CENTER FREQUENCY =
-SAMPLE RATE =
-DIGITAL CARRIER OFFSET =
-TX GAIN =
+MASTER SERIAL =
+MASTER CLKOUT COMMAND =
+RX COMMON CLOCK REPORT =
 COMMON CLOCK VERIFIED =
-PHYSICAL CHECKPOINT =
-RX READY TO CAPTURE =
+YES / NO
 TX READY FOR RF-001A =
 YES / NO
 RF TX =

docs/rf/RF_001A_PREPARATION.md

@@ -28,7 +28,7 @@
 
 Предусмотрены TX VGA 20 дБ (`-x 20`), RX LNA 24 дБ (`-l 24`), RX VGA 24 дБ (`-g 24`), RF amplifier OFF (`-a 0`), питание антенны OFF (`-p 0`). Это baseline Lab066; назначения флагов и шаги проверены по установленному `hackrf_transfer -h`. На основном ПК `hackrf_info` обнаружил HackRF One r9, serial `000000000000000097c063dc323b97d3`, libhackrf/firmware 2024.02.1, API 1.08. Название устройства в задаче: Auron HackRF Plus. RX serial надо заново снять на ноутбуке; не переносить serial TX на RX.
 
-Общая опора: 10 МГц reference → MASTER → MASTER CLKOUT → SLAVE CLKIN. Старые `reg29=0x26` на обоих устройствах и `SLAVE CLKIN=DETECTED` из `RF_001_PLAN.md` не доказывают текущую синхронизацию. Перед будущим TX требуется ручная отметка `COMMON CLOCK VERIFIED = YES` после свежей проверки MASTER/SLAVE, проводов и признака CLKIN на SLAVE. Также вручную подтвердить подключённые антенны, оба USB, согласованную поляризацию и безопасную дистанцию. Если прежняя геометрия применима, около 1,2 м, LOS, одинаковая поляризация. Прямой кабель TX RF → RX RF допустим лишь с нужным ослаблением. Геометрию A/B не менять.
+Общая опора: 10 МГц reference → MASTER → MASTER CLKOUT → SLAVE CLKIN. Основной критерий RF-001A: штатная команда `hackrf_clock -o 1` на MASTER завершилась успешно; SLAVE через `hackrf_clock -i` выдал точную строку `CLKIN status: clock signal detected`; после короткого конечного RX-start SLAVE продолжает видеть этот сигнал. Только при выполнении всех трёх условий допустима отметка `COMMON CLOCK VERIFIED = YES`. Вывод `hackrf_clock -r 3` и register 29 служат диагностикой и не являются обязательным PASS/FAIL-критерием физического CLKOUT. Старые результаты прошлых Lab не заменяют свежую проверку на SLAVE. Пользователь подтвердил подключённые антенны, оба USB, кабель MASTER CLKOUT → SLAVE CLKIN, около 2 м LOS и одинаковую поляризацию. Прямой кабель TX RF → RX RF допустим лишь с нужным ослаблением. Геометрию A/B не менять.
 
 **Будущая команда TX, только для подготовки, не запускать сейчас:**