SDR-Rover/docs/handoff/NEXT_RX_TASK.md

TASK_ID = RF001A_CAPTURE_001 TASK_TITLE = Start RF-001A common-clock IQ capture SOURCE_BRANCH = video-development EXPECTED_HEAD = 442451bdfb 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 = START RF-001A COMMON-CLOCK IQ CAPTURE

This is a new task. Do not reuse approval or completion state from RF001A_CLKIN_001. This task requires its own explicit [A] Approve decision before any hardware access or capture starts.

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;
• COMMON CLOCK = VERIFIED from completed task RF001A_CLKIN_001;
• the cable remains connected from MASTER CLKOUT to SLAVE CLKIN;
• the command below contains the exact line CLKIN status: clock signal detected:

& '<verified hackrf_clock.exe path>' -d 000000000000000097c063dc2e5327d3 -i

Run the existing hardware-independent shared RF-001A spec test:

python -B -m pytest tests/test_rf001a_prepare.py -q -p no:cacheprovider --basetemp .local/pytest-rf001a-capture

Require it to pass and confirm the shared spec matches the capture parameters below. If any condition fails, do not start hackrf_transfer. Report the failed condition, set RX CAPTURE STARTED = NO and RX READY FOR TX = NO, keep RF TX = 0, and STOP.

2. Authorized finite RX capture

Only this finite capture is authorized:

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 command arguments are:

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

3. Controlled background start

Keep one PowerShell session open for the start and completion sequence. Resolve the verified local path to hackrf_transfer.exe, then prepare and start the process:

$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_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.

If both checks pass, immediately print this status. Do not wait for completion, calculate SHA256, or perform another slow action before printing it:

TASK_ID =
RF001A_CAPTURE_001

RX CAPTURE STARTED =
YES

RX READY FOR TX =
YES

CAPTURE PID =
<PID>

CAPTURE PATH =
<absolute path>

CAPTURE DEADLINE / EXPECTED DURATION =
20 s

RF TX =
0

RX READY FOR TX = YES means only that this RX capture is active. RF TX on the RX laptop remains forbidden. The user coordinates any separately authorized TX action on the main PC.

4. Capture completion

Only after printing the start status, wait for the same process in the same PowerShell session:

$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()

Check and report the exit code, actual file size, actual duration, RX overruns, USB errors, file write errors and raw IQ SHA256. Inspect the saved stdout and stderr. The capture is complete only if the exit code is zero, the file size is exactly 320000000 bytes, and the saved output contains no RX overrun, USB error or file write error. A smaller file is incomplete. Preserve the evidence and do not retry automatically.

Write machine-readable metadata to a new file in $captureDirectory. Include the task ID, RX serial, requested settings, PID, start and finish timestamps, exit code, file size, duration, error counts and SHA256. The metadata and logs remain outside Git.

First report the immediate start status shown above. After completion, provide:

TASK_ID =
RF001A_CAPTURE_001

RX CAPTURE STARTED =
YES / NO

RX READY FOR TX =
YES / NO

CAPTURE PID =

CAPTURE PATH =

RF TX =
0

RX CAPTURE COMPLETE =
YES / NO

CAPTURE SIZE =

CAPTURE DURATION =

RX OVERRUNS =

USB ERRORS =

FILE WRITE ERRORS =

RAW IQ SHA256 =

STOP.

5. 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.