288 lines
8.9 KiB
Markdown
288 lines
8.9 KiB
Markdown
TASK_ID = RF001A_VERIFY_AND_CAPTURE_001
|
|
TASK_TITLE = Verify RF-001A common clock and start IQ capture
|
|
SOURCE_BRANCH = video-development
|
|
EXPECTED_HEAD = fa370ccfa23dedc633346d688547e9c1c77ff8eb
|
|
REQUIRES_APPROVAL = YES
|
|
HARDWARE_ACCESS = YES
|
|
RF_RX = YES
|
|
RF_TX = NO
|
|
ALLOW_COMMIT = NO
|
|
ALLOW_PUSH = RX_RESULT_ONLY
|
|
RISK_LEVEL = YELLOW
|
|
|
|
This file is the authoritative current task for the RX laptop.
|
|
The RX assistant must read RX_NODE_STATE.md first, then execute this file.
|
|
If chat history conflicts with these files and current Git HEAD, stop and report the conflict.
|
|
|
|
# Current RX task
|
|
|
|
TASK =
|
|
VERIFY RF-001A COMMON CLOCK AND START IQ CAPTURE
|
|
|
|
This is one combined YELLOW task. One explicit `[A] Approve` authorizes the bounded CLKIN verification, the bounded short RX-start and, only after that gate passes, the finite 20-second RX capture. Do not request a second approval between those steps.
|
|
|
|
Do not reuse the approval, state or completion record from either old task ID:
|
|
|
|
```text
|
|
RF001A_CLKIN_001
|
|
RF001A_CAPTURE_001
|
|
```
|
|
|
|
## 1. Preconditions
|
|
|
|
After approval, run `git pull --ff-only origin video-development`, then verify:
|
|
|
|
- branch = `video-development`;
|
|
- `git status --short --untracked-files=no` produces no output;
|
|
- local HEAD equals `origin/video-development` and `EXPECTED_HEAD` is its ancestor;
|
|
- `hackrf_info` = PASS;
|
|
- RX serial = `000000000000000097c063dc2e5327d3`;
|
|
- the physical cable is connected from MASTER CLKOUT to SLAVE CLKIN;
|
|
- the existing hardware-independent shared RF-001A spec test passes:
|
|
|
|
```powershell
|
|
python -B -m pytest tests/test_rf001a_prepare.py -q -p no:cacheprovider --basetemp .local/pytest-rf001a-verify-capture
|
|
```
|
|
|
|
If any precondition fails, do not start the short RX or the 20-second capture. Report the failed condition, keep `RF TX = 0`, and STOP.
|
|
|
|
## 2. Verify SLAVE CLKIN before RX
|
|
|
|
Run the official read-only partner-side check with the explicit RX serial and preserve its complete stdout:
|
|
|
|
```powershell
|
|
& '<verified hackrf_clock.exe path>' -d 000000000000000097c063dc2e5327d3 -i
|
|
```
|
|
|
|
Accept only the exact line:
|
|
|
|
```text
|
|
CLKIN status: clock signal detected
|
|
```
|
|
|
|
Set `SLAVE CLKIN BEFORE RX = DETECTED` only when that line is present. Otherwise set `COMMON CLOCK VERIFIED = NO`, do not start the short RX or capture, keep `RF TX = 0`, and STOP.
|
|
|
|
## 3. Bounded short RX-start
|
|
|
|
If SLAVE CLKIN was detected, perform one short, finite RX-start on the same device:
|
|
|
|
```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
|
|
```
|
|
|
|
This is RX only. It must not transmit. Require:
|
|
|
|
- exit code = `0`;
|
|
- exactly `65536` complex samples transferred;
|
|
- RX overruns = `0`;
|
|
- USB errors = `0`;
|
|
- file write errors = `0`.
|
|
|
|
If any condition fails, set `SHORT RX START = FAIL` and `COMMON CLOCK VERIFIED = NO`. Do not start the 20-second capture. Keep `RF TX = 0` and STOP.
|
|
|
|
## 4. Verify SLAVE CLKIN after RX
|
|
|
|
Immediately repeat the same read-only check and preserve its complete stdout:
|
|
|
|
```powershell
|
|
& '<verified hackrf_clock.exe path>' -d 000000000000000097c063dc2e5327d3 -i
|
|
```
|
|
|
|
Accept only the exact line `CLKIN status: clock signal detected`.
|
|
|
|
Set `COMMON CLOCK VERIFIED = YES` only when all three conditions pass:
|
|
|
|
- `SLAVE CLKIN BEFORE RX = DETECTED`;
|
|
- `SHORT RX START = PASS`;
|
|
- `SLAVE CLKIN AFTER RX = DETECTED`.
|
|
|
|
If CLKIN is not detected after the short RX-start, set `COMMON CLOCK VERIFIED = NO`, do not start the capture, keep `RF TX = 0`, and STOP. Do not alter clock configuration automatically.
|
|
|
|
## 5. Authorized finite RX capture
|
|
|
|
When and only when `COMMON CLOCK VERIFIED = YES`, continue immediately under this same task ID and the same YELLOW approval. Start this finite RX capture:
|
|
|
|
```text
|
|
RX serial = 000000000000000097c063dc2e5327d3
|
|
center frequency = 1400000000 Hz
|
|
sample rate = 8000000 samples/s
|
|
RX LNA = 24 dB
|
|
RX VGA = 24 dB
|
|
RF amp = OFF
|
|
antenna bias = OFF
|
|
duration = 20 s
|
|
sample count = 160000000 complex samples
|
|
hardware format = cs8
|
|
expected file size = 320000000 bytes
|
|
```
|
|
|
|
Create a new directory outside the Git checkout for every attempt. Use a timestamp plus a random suffix, refuse an existing path, and never overwrite an earlier capture. Keep the IQ file, stdout, stderr and metadata there. Do not add them to Git.
|
|
|
|
The required capture arguments are:
|
|
|
|
```text
|
|
hackrf_transfer.exe
|
|
-d 000000000000000097c063dc2e5327d3
|
|
-r <unique_capture_path>\rf001a_capture.cs8
|
|
-f 1400000000
|
|
-s 8000000
|
|
-n 160000000
|
|
-l 24
|
|
-g 24
|
|
-a 0
|
|
-p 0
|
|
-B
|
|
```
|
|
|
|
## 6. Controlled background start
|
|
|
|
Keep one PowerShell session open for the start and completion sequence. Resolve the verified local path to `hackrf_transfer.exe`, then start the controlled background process:
|
|
|
|
```powershell
|
|
$runId = '{0}_{1}' -f (Get-Date -Format 'yyyyMMdd_HHmmss'), ([guid]::NewGuid().ToString('N').Substring(0, 8))
|
|
$captureRoot = Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'SDR_Rover_Captures'
|
|
$captureDirectory = Join-Path $captureRoot "RF001A_VERIFY_AND_CAPTURE_001_$runId"
|
|
if (Test-Path -LiteralPath $captureDirectory) { throw "Capture directory already exists: $captureDirectory" }
|
|
New-Item -ItemType Directory -Path $captureDirectory -ErrorAction Stop | Out-Null
|
|
|
|
$capturePath = Join-Path $captureDirectory 'rf001a_capture.cs8'
|
|
$stdoutPath = Join-Path $captureDirectory 'hackrf_transfer.stdout.log'
|
|
$stderrPath = Join-Path $captureDirectory 'hackrf_transfer.stderr.log'
|
|
$hackrfTransfer = '<verified absolute path to hackrf_transfer.exe>'
|
|
$startedAt = Get-Date
|
|
$captureArguments = @(
|
|
'-d', '000000000000000097c063dc2e5327d3',
|
|
'-r', $capturePath,
|
|
'-f', '1400000000',
|
|
'-s', '8000000',
|
|
'-n', '160000000',
|
|
'-l', '24',
|
|
'-g', '24',
|
|
'-a', '0',
|
|
'-p', '0',
|
|
'-B'
|
|
)
|
|
$captureProcess = Start-Process -FilePath $hackrfTransfer -ArgumentList $captureArguments `
|
|
-RedirectStandardOutput $stdoutPath -RedirectStandardError $stderrPath `
|
|
-PassThru -WindowStyle Hidden
|
|
|
|
$growthDeadline = (Get-Date).AddSeconds(2)
|
|
do {
|
|
Start-Sleep -Milliseconds 100
|
|
$captureProcess.Refresh()
|
|
$captureBytes = if (Test-Path -LiteralPath $capturePath) {
|
|
(Get-Item -LiteralPath $capturePath).Length
|
|
} else {
|
|
0
|
|
}
|
|
} until ($captureProcess.HasExited -or $captureBytes -gt 0 -or (Get-Date) -ge $growthDeadline)
|
|
```
|
|
|
|
The start passes only if the process remains active and the capture file exists and has grown above zero bytes. If either check fails, report `RX CAPTURE STARTED = NO`, `RX READY FOR TX = NO`, preserve the logs, keep `RF TX = 0`, and STOP.
|
|
|
|
When both checks pass, immediately output:
|
|
|
|
```text
|
|
TASK_ID =
|
|
RF001A_VERIFY_AND_CAPTURE_001
|
|
|
|
COMMON CLOCK VERIFIED =
|
|
YES
|
|
|
|
RX CAPTURE STARTED =
|
|
YES
|
|
|
|
RX READY FOR TX =
|
|
YES
|
|
|
|
CAPTURE PID =
|
|
|
|
CAPTURE PATH =
|
|
|
|
RF TX =
|
|
0
|
|
```
|
|
|
|
Do not wait for capture completion, calculate SHA256, or perform another slow action before sending this status. `RX READY FOR TX = YES` only reports that the RX capture is active. It does not authorize RF TX on either computer. RF TX on the RX laptop remains forbidden.
|
|
|
|
## 7. Capture completion
|
|
|
|
Only after sending the immediate start status, wait for the same process in the same PowerShell session:
|
|
|
|
```powershell
|
|
$captureProcess.WaitForExit()
|
|
$finishedAt = Get-Date
|
|
$captureProcess.Refresh()
|
|
$exitCode = $captureProcess.ExitCode
|
|
$captureSize = (Get-Item -LiteralPath $capturePath).Length
|
|
$captureDurationSeconds = ($finishedAt - $startedAt).TotalSeconds
|
|
$captureHash = (Get-FileHash -LiteralPath $capturePath -Algorithm SHA256).Hash.ToLowerInvariant()
|
|
```
|
|
|
|
Inspect the saved stdout and stderr. Record the exit code, actual file size, actual duration, RX overruns, USB errors, file write errors and raw IQ SHA256.
|
|
|
|
The capture is complete only if:
|
|
|
|
- exit code = `0`;
|
|
- file size = exactly `320000000` bytes;
|
|
- RX overruns = `0`;
|
|
- USB errors = `0`;
|
|
- file write errors = `0`.
|
|
|
|
A smaller file is incomplete. Preserve the evidence and do not retry automatically. Write machine-readable metadata to a new file in `$captureDirectory`, including the task ID, RX serial, requested settings, clock results, PID, timestamps, exit code, size, duration, error counts and SHA256. The metadata and logs remain outside Git.
|
|
|
|
Finish with:
|
|
|
|
```text
|
|
TASK_ID =
|
|
RF001A_VERIFY_AND_CAPTURE_001
|
|
|
|
SLAVE CLKIN BEFORE RX =
|
|
DETECTED / NOT_DETECTED
|
|
|
|
SHORT RX START =
|
|
PASS / FAIL / NOT_RUN
|
|
|
|
SLAVE CLKIN AFTER RX =
|
|
DETECTED / NOT_DETECTED / NOT_RUN
|
|
|
|
COMMON CLOCK VERIFIED =
|
|
YES / NO
|
|
|
|
RX CAPTURE STARTED =
|
|
YES / NO
|
|
|
|
RX READY FOR TX =
|
|
YES / NO
|
|
|
|
CAPTURE PID =
|
|
|
|
CAPTURE PATH =
|
|
|
|
RX CAPTURE COMPLETE =
|
|
YES / NO / NOT_RUN
|
|
|
|
CAPTURE SIZE =
|
|
|
|
CAPTURE DURATION =
|
|
|
|
RX OVERRUNS =
|
|
|
|
USB ERRORS =
|
|
|
|
FILE WRITE ERRORS =
|
|
|
|
RAW IQ SHA256 =
|
|
|
|
RF TX =
|
|
0
|
|
|
|
STOP.
|
|
```
|
|
|
|
## 8. Prohibited actions
|
|
|
|
On the RX laptop, do not perform RF TX, firmware or CPLD updates, Zadig operations, USB driver changes, clock reconfiguration, continuous RX, automatic retries, commits to `video-development`, or pushes to `video-development`.
|
|
|
|
`ALLOW_PUSH = RX_RESULT_ONLY` permits only a separately approved small result publication under the handoff protocol. It does not permit raw IQ, large logs, a commit to `video-development`, or a push to `video-development`.
|