firmwareloop 0.0.8__py3-none-any.whl

tools/logic_capture.ps1

@@ -0,0 +1,261 @@
+<#
+.SYNOPSIS
+    Logic analyzer capture (Spec §13). Saleae is the primary path (Logic 2 MCP
+    in Qoder); this wrapper covers the sigrok fallback for non-Saleae hardware
+    and provides a deterministic SIMULATOR backend so the capture->decode->
+    assert pipeline can be exercised without any LA hardware.
+
+    Every capture saves (Spec §13): raw capture file, decoder config snapshot,
+    and a metadata JSON with the timestamp - under artifacts/captures/.
+
+    Usage:
+        .\tools\logic_capture.ps1 -Protocol spi -Json            # simulator (default)
+        .\tools\logic_capture.ps1 -Protocol uart -Backend sigrok -Json
+#>
+[CmdletBinding()]
+param(
+    [ValidateSet('spi', 'uart', 'i2c')]
+    [string]$Protocol = 'spi',
+    [ValidateSet('auto', 'simulator', 'sigrok')]
+    [string]$Backend = 'auto',
+    [double]$DurationSec = 0.002,
+    [int]$SampleRateHz = 1000000,
+    [string]$OutDir,                          # default: artifacts/captures/<stamp>
+    [switch]$Json
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+
+function Exit-WithError {
+    param([string]$Class, [string]$Message, [string]$Detail)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
+    exit 2
+}
+
+# ---- decide backend -----------------------------------------------------------
+if ($Backend -eq 'auto') {
+    $g = Get-Command sigrok-cli -ErrorAction SilentlyContinue
+    $sigrok = if ($g) { $g.Source } else { $null }
+    $Backend = if ($sigrok) { 'sigrok' } else { 'simulator' }
+}
+if ($Backend -eq 'sigrok') {
+    $g = Get-Command sigrok-cli -ErrorAction SilentlyContinue
+    $sigrok = if ($g) { $g.Source } else { $null }
+    if (-not $sigrok) {
+        Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message 'sigrok-cli not found; install sigrok or use -Backend simulator' -Detail 'https://sigrok.org/wiki/Downloads'
+    }
+}
+
+# ---- output layout ------------------------------------------------------------
+$stamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+$runId = Get-FwRunId
+if (-not $OutDir) { $OutDir = Join-Path $repoRoot "artifacts\captures\$runId" }
+New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
+
+# decoder config snapshot (read from lab/protocol-decode.yaml if present)
+$decodeCfg = Join-Path $repoRoot 'lab\protocol-decode.yaml'
+$configOut = Join-Path $OutDir 'decoder-config.yaml'
+if (Test-Path -LiteralPath $decodeCfg) {
+    Copy-Item -LiteralPath $decodeCfg -Destination $configOut -Force
+} else {
+    Set-Content -LiteralPath $configOut -Value "# decoder config snapshot (protocol-decode.yaml not found at capture time)" -Encoding utf8
+}
+
+$meta = [ordered]@{
+    schema       = 'lab-logic-capture/v1'
+    ok           = $true
+    run_id       = $runId
+    protocol     = $Protocol
+    backend      = $Backend
+    duration_sec = $DurationSec
+    sample_rate_hz = $SampleRateHz
+    timestamp    = Get-FwTimestamp
+    files        = @()
+}
+
+# ---- simulator waveform generation --------------------------------------------
+if ($Backend -eq 'simulator') {
+    $rawFile = Join-Path $OutDir 'capture.csv'
+    $meta.protocol = $Protocol
+    switch ($Protocol) {
+        'spi' { $generator = 'SPI transaction: 0x9F read + 24-bit response 0xEF4018' }
+        'uart' { $generator = 'UART frame: "HIL" at 115200 8N1' }
+        'i2c' { $generator = 'I2C write to 0x50 then read 3 bytes' }
+        default { $generator = 'unknown' }
+    }
+    $rows = New-Object System.Collections.Generic.List[string]
+    $rows.Add('time_s,D0,D1,D2,D3')
+
+    function Add-Sample {
+        param([double]$T, [int[]]$Levels)
+        $rows.Add(('{0:F8},{1},{2},{3},{4}' -f $T, $Levels[0], $Levels[1], $Levels[2], $Levels[3]))
+    }
+
+    $dt = 1.0 / $SampleRateHz
+    $t = 0.0
+
+    if ($Protocol -eq 'spi') {
+        # Channels: D0=SCLK, D1=MOSI, D2=MISO, D3=CS (low active)
+        # One bit = 1us at 1 MHz SCLK === 1 sample per half-bit at 1MHz? Use
+        # 2 samples per bit: low phase then high (rising edge sampled).
+        $bitUs = 2e-6   # 2us per bit -> 500 kHz SCLK
+        $bits = @()    # command bits MSB first
+        foreach ($b in (0x9F)) { for ($i = 7; $i -ge 0; $i--) { $bits += ($b -shr $i) -band 1 } }
+        $resp = @(0xEF, 0x40, 0x18)
+        $respBits = @()
+        foreach ($bb in $resp) { for ($i = 7; $i -ge 0; $i--) { $respBits += ($bb -shr $i) -band 1 } }
+
+        # idle (CS high)
+        $idleSamples = [math]::Max(2, [int](0.00005 / $dt))
+        for ($i = 0; $i -lt $idleSamples; $i++) {
+            Add-Sample $t @(0, 0, 0, 1)
+            $t += $dt
+        }
+        # CS assert
+        $csLevels = @(0, 0, 0, 0)
+        for ($i = 0; $i -lt 2; $i++) { Add-Sample $t $csLevels; $t += $dt }
+        # command + response bits: first 8 bits drive MOSI, next 24 drive MISO
+        $allBits = $bits + $respBits
+        for ($idx = 0; $idx -lt $allBits.Count; $idx++) {
+            $bit = $allBits[$idx]
+            $isCmd = $idx -lt 8
+            $mosi = if ($isCmd) { $bit } else { 0 }
+            $miso = if ($isCmd) { 0 } else { $bit }
+            # low phase
+            for ($i = 0; $i -lt [int]($bitUs / 2 / $dt); $i++) {
+                if ($mosi -eq 1) { Add-Sample $t @(0, 1, $miso, 0) } else { Add-Sample $t @(0, 0, $miso, 0) }
+                $t += $dt
+            }
+            # high phase (rising edge; MISO valid here)
+            for ($i = 0; $i -lt [int]($bitUs / 2 / $dt); $i++) {
+                if ($mosi -eq 1) { Add-Sample $t @(1, 1, $miso, 0) } else { Add-Sample $t @(1, 0, $miso, 0) }
+                $t += $dt
+            }
+        }
+        # CS deassert
+        for ($i = 0; $i -lt 2; $i++) { Add-Sample $t @(0, 0, 0, 1); $t += $dt }
+    } elseif ($Protocol -eq 'uart') {
+        # Channels: D0=TX, D1=RX, D2=unused, D3=unused
+        $bitTime = 1.0 / 115200.0
+        function Add-Bit {
+            param([double]$TT, [int]$Level, [double]$BitLen)
+            $n = [math]::Max(1, [int]($BitLen / $dt))
+            for ($i = 0; $i -lt $n; $i++) {
+                Add-Sample $TT @($Level, 1, 0, 0)
+                $TT += $dt
+            }
+            return $TT
+        }
+        $payloadBytes = [System.Text.Encoding]::ASCII.GetBytes('HIL')
+        $idleN = [math]::Max(2, [int]((10 * $bitTime) / $dt))
+        for ($i = 0; $i -lt $idleN; $i++) { Add-Sample $t @(1, 1, 0, 0); $t += $dt }
+        foreach ($byte in $payloadBytes) {
+            $t = Add-Bit $t 0 $bitTime           # start bit
+            for ($i = 0; $i -lt 8; $i++) {        # LSB first
+                $t = Add-Bit $t (($byte -shr $i) -band 1) $bitTime
+            }
+            $t = Add-Bit $t 1 $bitTime            # stop bit
+            # inter-frame gap (like software-driven UART transmit)
+            $gapN = [math]::Max(2, [int]((10 * $bitTime) / $dt))
+            for ($i = 0; $i -lt $gapN; $i++) { Add-Sample $t @(1, 1, 0, 0); $t += $dt }
+        }
+    } else {  # i2c
+        # Channels: D0=SCL, D1=SDA; write transaction: START, addr 0xA0,
+        # reg 0x00 with ACKs, STOP.
+        $bitTime = 1.0 / 100000.0
+        function Add-I2CBit {
+            param([double]$TT, [int]$SdaLevel, [double]$BitLen)
+            $n = [math]::Max(1, [int]($BitLen / $dt))
+            for ($i = 0; $i -lt $n; $i++) {
+                Add-Sample $TT @(0, $SdaLevel, 0, 0)
+                $TT += $dt
+            }
+            # clock high
+            $nh = [math]::Max(1, [int]($BitLen / $dt))
+            for ($i = 0; $i -lt $nh; $i++) {
+                Add-Sample $TT @(1, $SdaLevel, 0, 0)
+                $TT += $dt
+            }
+            return $TT
+        }
+        function Add-I2CHold {
+            param([double]$TT, [int]$SdaLevel, [double]$Secs)
+            $n = [math]::Max(1, [int]($Secs / $dt))
+            for ($i = 0; $i -lt $n; $i++) {
+                Add-Sample $TT @(1, $SdaLevel, 0, 0)   # SCL stays high
+                $TT += $dt
+            }
+            return $TT
+        }
+        $hold = $bitTime / 2
+
+        # idle (bus free: SCL high, SDA high)
+        $idleN = [math]::Max(2, [int]((4 * $bitTime) / $dt))
+        for ($i = 0; $i -lt $idleN; $i++) { Add-Sample $t @(1, 1, 0, 0); $t += $dt }
+        # START: SDA falls while SCL is high
+        $t = Add-I2CHold $t 0 $hold
+        Add-Sample $t @(1, 0, 0, 0); $t += $dt
+        $t = Add-I2CHold $t 0 $hold
+        # address + data bytes with ACK after each
+        foreach ($byte in @(0xA0, 0x00)) {
+            foreach ($i in 7..0) {
+                $t = Add-I2CBit $t (($byte -shr $i) -band 1) $bitTime
+            }
+            $t = Add-I2CBit $t 0 $bitTime  # ACK
+        }
+        # STOP: SDA rises while SCL is high
+        $t = Add-I2CHold $t 0 $hold
+        Add-Sample $t @(1, 1, 0, 0); $t += $dt
+        $t = Add-I2CHold $t 1 $hold
+    }
+
+    Set-Content -LiteralPath $rawFile -Value $rows -Encoding utf8
+    $meta.files += (Resolve-Path -LiteralPath $rawFile).Path
+    $meta.generator = $generator
+}
+
+# ---- sigrok backend ------------------------------------------------------------
+else {
+    $rawFile = Join-Path $OutDir 'capture.sr'
+    $probeArgs = @(
+        "--driver=auto",
+        "--config", "samplerate=$SampleRateHz",
+        "--channels", "0-7",
+        "--output-format", "binary",
+        "--output-file", $rawFile,
+        "--time", "$([int]([math]::Ceiling($DurationSec * 1000)))ms",
+        "$Protocol"
+    )
+    $res = Invoke-FwProcess -FilePath $sigrok -Arguments $probeArgs -WorkingDirectory $repoRoot -TimeoutMs 120000
+    if ($res.timed_out) {
+        Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message 'sigrok-cli capture timed out.' -Detail $rawFile
+    }
+    if ($res.exit_code -ne 0 -or -not (Test-Path -LiteralPath $rawFile)) {
+        Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message 'sigrok-cli capture failed.' -Detail ($res.stdout + $res.stderr)
+    }
+    $meta.files += (Resolve-Path -LiteralPath $rawFile).Path
+}
+
+$metaFile = Join-Path $OutDir 'capture.json'
+$meta | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $metaFile -Encoding utf8
+$meta.files += (Resolve-Path -LiteralPath $metaFile).Path
+
+$result = [ordered]@{
+    schema         = 'lab-logic-capture/v1'
+    ok             = $true
+    protocol       = $Protocol
+    backend        = $Backend
+    capture        = (Resolve-Path -LiteralPath $rawFile).Path
+    metadata       = (Resolve-Path -LiteralPath $metaFile).Path
+    decoder_config = (Resolve-Path -LiteralPath $configOut).Path
+    files          = @($meta.files)
+    run_id         = $runId
+    timestamp      = Get-FwTimestamp
+}
+if ($Json) { Write-FwJson ([pscustomobject]$result) -Compact } else { Write-FwJson ([pscustomobject]$result) }
+exit 0

tools/logic_decode.ps1

@@ -0,0 +1,307 @@
+<#
+.SYNOPSIS
+    Logic decoder (Spec §13 fallback). Decodes a raw capture (CSV with a
+    time_s first column and one column per channel) into JSON frames using the
+    channel/protocol layout from lab/protocol-decode.yaml.
+
+    SPI  : D0=SCLK, D1=MOSI, D2=MISO, D3=CS (low active), MSB first
+    UART : D0=TX (idle high), 8N1, LSB first, baud from config
+    I2C  : D0=SCL, D1=SDA (basic byte/ACK extraction)
+
+    Every decoded result is saved next to the capture and carries the
+    timestamp. Optional -Expect/-ExpectKind asserts the result and exits 1
+    with TEST_FAILED on mismatch (for HIL assertions).
+
+    Usage:
+        .\tools\logic_decode.ps1 -Capture artifacts\captures\20260817-000000 -Json
+        .\tools\logic_decode.ps1 -CaptureFile x.csv -Protocol spi -Expect EF4018 -ExpectKind hex -Json
+#>
+[CmdletBinding()]
+param(
+    [string]$Capture,                 # capture dir containing capture.csv + capture.json
+    [string]$CaptureFile,             # direct path to the raw CSV
+    [ValidateSet('spi', 'uart', 'i2c')]
+    [string]$Protocol,                # override protocol (else read from metadata)
+    [string]$Expect,                  # expected decoded value (hex string or text)
+    [ValidateSet('hex', 'text')]
+    [string]$ExpectKind = 'hex',
+    [switch]$Json
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+Import-Module (Join-Path $PSScriptRoot 'common\fw.psm1') -Force
+
+$repoRoot = Get-FwRepoRoot
+
+function Exit-WithError {
+    param([string]$Class, [string]$Message, [string]$Detail)
+    $body = New-FwError -ErrorClass $Class -Message $Message -Detail $Detail
+    if ($Json) { Write-FwJson $body -Compact } else { Write-FwJson $body; Write-Error "$Class : $Message" -ErrorAction Continue }
+    exit 2
+}
+
+# ---- locate raw capture -------------------------------------------------------
+$rawFile = $null
+$meta = $null
+if ($Capture) {
+    if (Test-Path -LiteralPath $Capture -PathType Container) {
+        $rawFile = Join-Path $Capture 'capture.csv'
+        $metaPath = Join-Path $Capture 'capture.json'
+        if (Test-Path -LiteralPath $metaPath) {
+            $meta = Get-Content -LiteralPath $metaPath -Raw | ConvertFrom-Json
+        }
+        if (-not (Test-Path -LiteralPath $rawFile)) {
+            $srFile = Join-Path $Capture 'capture.sr'
+            if (Test-Path -LiteralPath $srFile) {
+                Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message 'sigrok binary capture needs sigrok-cli decode; export CSV from PulseView or pass -CaptureFile <csv>.' -Detail $srFile
+            }
+            Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message 'no capture.csv or capture.sr found in capture dir.' -Detail $Capture
+        }
+    } elseif (Test-Path -LiteralPath $Capture -PathType Leaf) {
+        $rawFile = $Capture   # direct file path (capture.csv)
+        $metaPath = Join-Path (Split-Path $Capture) 'capture.json'
+        if (Test-Path -LiteralPath $metaPath) {
+            $meta = Get-Content -LiteralPath $metaPath -Raw | ConvertFrom-Json
+        }
+    } else {
+        Exit-WithError -Class 'CONFIG_ERROR' -Message 'Capture path does not exist.' -Detail $Capture
+    }
+} elseif ($CaptureFile) {
+    $rawFile = $CaptureFile
+} else {
+    Exit-WithError -Class 'CONFIG_ERROR' -Message 'pass -Capture <dir> or -CaptureFile <csv>'
+}
+
+if (-not (Test-Path -LiteralPath $rawFile)) {
+    Exit-WithError -Class 'ARTIFACT_NOT_FOUND' -Message 'capture file does not exist.' -Detail $rawFile
+}
+
+# ---- protocol/config resolution ------------------------------------------------
+$cfg = @{}
+$cfgPath = Join-Path $repoRoot 'lab\protocol-decode.yaml'
+# YAML is not natively parseable in PowerShell; the decoder only needs the
+# baud rate for UART and channel mapping. Fall back to sane defaults.
+if ($meta -and $meta.protocol) { $reqProtocol = [string]$meta.protocol } else { $reqProtocol = $null }
+if ($Protocol) { $reqProtocol = $Protocol }
+if (-not $reqProtocol) {
+    Exit-WithError -Class 'CONFIG_ERROR' -Message 'protocol unknown; pass -Protocol or run capture first' -Detail $metaPath
+}
+
+$baud = 115200
+if ($reqProtocol -eq 'uart' -and $meta) {
+    $bProp = $meta.PSObject.Properties['baud']
+    if ($bProp -and $bProp.Value) { $baud = [int]$bProp.Value }
+}
+
+# ---- load samples --------------------------------------------------------------
+$rows = Import-Csv -LiteralPath $rawFile
+if ($rows.Count -lt 3) {
+    Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message 'capture has too few samples to decode.' -Detail $rawFile
+}
+$cols = $rows[0].PSObject.Properties.Name
+foreach ($c in @('time_s')) { if ($c -notin $cols) { Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message "missing column '$c' in capture" -Detail $rawFile } }
+$ch = @{}
+foreach ($c in $cols) { if ($c -ne 'time_s') { $ch[$c] = $true } }
+
+function Get-Ch {
+    param([int]$Index)
+    $names = @($cols | Where-Object { $_ -ne 'time_s' })
+    if ($Index -ge $names.Count) { return $null }
+    return $names[$Index]
+}
+
+# normalize levels (CSV values may be 0/1, true/false, high/low)
+function Lev([string]$v) {
+    $s = $v.Trim().ToLowerInvariant()
+    if ($s -in @('1', 'true', 'high', 'h')) { return 1 }
+    if ($s -in @('0', 'false', 'low', 'l')) { return 0 }
+    return 0
+}
+
+# ---- decoders -------------------------------------------------------------------
+$frames = @()
+$bytes = @()
+$text = ''
+
+switch ($reqProtocol) {
+    'spi' {
+        $cClk = Get-Ch 0; $cMosi = Get-Ch 1; $cMiso = Get-Ch 2; $cCs = Get-Ch 3
+        if (-not ($cClk -and $cMosi -and $cMiso -and $cCs)) {
+            Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message "SPI needs 4 channels (SCLK,MOSI,MISO,CS); found: $($cols -join ',')"
+        }
+        $inWindow = $false
+        $cmdBits = @(); $respBits = @(); $prevClk = 0
+        foreach ($r in $rows) {
+            $cs = Lev $r.$cCs
+            if (-not $inWindow -and $cs -eq 0) { $inWindow = $true; $cmdBits = @(); $respBits = @() }
+            if ($inWindow -and $cs -eq 1) { break }   # window closed
+            if ($inWindow) {
+                $clk = Lev $r.$cClk
+                if ($clk -eq 1 -and $prevClk -eq 0) {        # rising edge
+                    $mosi = Lev $r.$cMosi
+                    $miso = Lev $r.$cMiso
+                    if ($cmdBits.Count + $respBits.Count -lt 8) {
+                        $cmdBits += $mosi
+                    } else {
+                        $respBits += $miso
+                    }
+                }
+                $prevClk = $clk
+            }
+        }
+        if ($cmdBits.Count + $respBits.Count -ne 32) {
+            Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message "expected 32 SPI edges (8 cmd + 24 resp), got $($cmdBits.Count + $respBits.Count)" -Detail $rawFile
+        }
+        $cmdByte = 0; foreach ($b in $cmdBits) { $cmdByte = ($cmdByte -shl 1) -bor $b }
+        $respBytes = @()
+        for ($k = 0; $k -lt 24; $k += 8) {
+            $v = 0
+            for ($j = 0; $j -lt 8; $j++) { $v = ($v -shl 1) -bor $respBits[$k + $j] }
+            $respBytes += $v
+        }
+        $bytes = @($cmdByte) + $respBytes
+        $frames = @([ordered]@{
+            type = 'command'; bytes_hex = ('0x{0:X2}' -f $cmdByte)
+        }, [ordered]@{
+            type = 'response'; bytes_hex = (($respBytes | ForEach-Object { '0x{0:X2}' -f $_ }) -join ' ')
+        })
+    }
+
+    'uart' {
+        $cTx = Get-Ch 0
+        if (-not $cTx) { Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message "UART needs a TX channel (D0); found: $($cols -join ',')" }
+        $samples = @($rows | ForEach-Object { Lev $_.$cTx })
+        # Estimate bit width from the MODE of adjacent edge spacings - robust
+        # against data bits that are low for more than one bit (e.g. 0x48).
+        $edges = @()
+        for ($k = 0; $k -lt $samples.Count - 1; $k++) {
+            if ($samples[$k] -ne $samples[$k + 1]) { $edges += $k + 1 }
+        }
+        $spacings = @()
+        for ($k = 1; $k -lt $edges.Count; $k++) {
+            $spacings += ($edges[$k] - $edges[$k - 1])
+        }
+        if ($spacings.Count -eq 0) {
+            Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message 'no edges found on UART TX channel; is the capture from a real UART?'
+        }
+        $bitSamples = ($spacings | Group-Object | Sort-Object Count -Descending | Select-Object -First 1).Name
+        $bitSamples = [math]::Max(2, [int]$bitSamples)
+
+        $i = 0
+        while ($i -lt $samples.Count - 1) {
+            # Frame boundary: falling edge preceded by >= 3 bits of idle high.
+            # A real start bit has stop + inter-frame idle before it; mid-data
+            # runs of 1s are at most 2 bits before a data falling edge.
+            $preHigh = $true
+            for ($c = 0; $c -lt 3 * $bitSamples; $c++) {
+                $pi = $i - $c
+                if ($pi -lt 0) { $preHigh = $false; break }
+                if ($samples[$pi] -ne 1) { $preHigh = $false; break }
+            }
+            if ($samples[$i] -eq 1 -and $samples[$i + 1] -eq 0 -and $preHigh) {
+                $collected = @()
+                for ($b = 0; $b -lt 8; $b++) {
+                    $idx = $i + 1 + [int]((1.5 + $b) * $bitSamples)
+                    $bitVal = if ($idx -lt $samples.Count) { $samples[$idx] } else { 1 }
+                    $collected += $bitVal   # LSB first
+                }
+                # stop bit must be high (idle level) for a valid UART frame
+                $stopIdx = $i + 1 + [int](10.0 * $bitSamples)
+                $stopOk = ($stopIdx -lt $samples.Count) -and ($samples[$stopIdx] -eq 1)
+                if (-not $stopOk) {
+                    $i++   # not a real frame boundary (mid-data flip); keep scanning
+                    continue
+                }
+                $val = 0
+                for ($b = 7; $b -ge 0; $b--) { $val = ($val -shl 1) -bor $collected[$b] }
+                $bytes += $val
+                $frames += [ordered]@{ type = 'frame'; bytes_hex = '0x{0:X2}' -f $val }
+                $i += $bitSamples  # advance into the frame interior; the scan
+                # re-hits the next boundary via the idle-high precondition
+                continue
+            }
+            $i++
+        }
+        $text = -join ($bytes | ForEach-Object { [char]$_ })
+    }
+
+    'i2c' {
+        $cScl = Get-Ch 0; $cSda = Get-Ch 1
+        if (-not ($cScl -and $cSda)) {
+            Exit-WithError -Class 'LOGIC_CAPTURE_ERROR' -Message "I2C needs SCL (D0) and SDA (D1); found: $($cols -join ',')"
+        }
+        # Collect the SDA value at every SCL rising edge; one byte = 8 data
+        # bits + 1 ACK. START (SDA falls while SCL high) opens the stream.
+        $prevScl = 0
+        $bits = [System.Collections.Generic.List[int]]::new()
+        $inStream = $false
+        foreach ($r in $rows) {
+            $scl = Lev $r.$cScl
+            $sda = Lev $r.$cSda
+            if ($scl -eq 1 -and $prevScl -eq 0) {          # rising edge
+                if ($inStream) { $bits.Add($sda) }
+            } elseif ($scl -eq 1 -and $prevScl -eq 1) {
+                # SCL high window: SDA falling => START, rising => STOP
+                if ($lastSclHighSda -eq 1 -and $sda -eq 0) { $inStream = $true; $bits.Clear() }
+                elseif ($lastSclHighSda -eq 0 -and $sda -eq 1) { $inStream = $false }
+                $lastSclHighSda = $sda
+            }
+            $prevScl = $scl
+            if ($scl -eq 1) { $lastSclHighSda = $sda }
+        }
+        # group 8-bit chunks (skip the ACK bit every 9th sample)
+        $payload = [System.Collections.Generic.List[int]]::new()
+        $idx = 0
+        while ($idx + 8 -le $bits.Count) {
+            $v = 0
+            for ($b = 0; $b -lt 8; $b++) { $v = ($v -shl 1) -bor $bits[$idx + $b] }
+            $payload.Add($v)
+            $idx += 9   # skip ACK
+        }
+        foreach ($v in $payload) {
+            $bytes += $v
+            $frames += [ordered]@{ type = 'byte'; bytes_hex = '0x{0:X2}' -f $v }
+        }
+    }
+}
+
+$hexStr = (($bytes | ForEach-Object { '{0:X2}' -f $_ }) -join '')
+$outDir = Split-Path -Parent (Resolve-Path -LiteralPath $rawFile).Path
+$outJson = Join-Path $outDir 'decoded.json'
+
+$decoded = [ordered]@{
+    schema    = 'lab-logic-decode/v1'
+    ok        = $true
+    protocol  = $reqProtocol
+    source    = (Resolve-Path -LiteralPath $rawFile).Path
+    bytes_hex = $hexStr
+    text      = $text
+    frames    = $frames
+    timestamp = Get-FwTimestamp
+}
+$decoded | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $outJson -Encoding utf8
+$decoded.out_file = (Resolve-Path -LiteralPath $outJson).Path
+
+# ---- assertion ----------------------------------------------------------------
+if ($Expect) {
+    $actual = if ($ExpectKind -eq 'hex') { $hexStr } else { $text }
+    if ($actual -ne $Expect) {
+        $body = [ordered]@{
+            schema       = 'lab-logic-decode/v1'
+            ok           = $false
+            error_class  = 'TEST_FAILED'
+            error        = 'decoded value did not match expectation'
+            protocol     = $reqProtocol
+            expected     = $Expect
+            actual       = $actual
+            decoded_file = $outJson
+            timestamp    = Get-FwTimestamp
+        }
+        if ($Json) { Write-FwJson ([pscustomobject]$body) -Compact } else { Write-FwJson ([pscustomobject]$body) }
+        exit 1
+    }
+}
+
+if ($Json) { Write-FwJson ([pscustomobject]$decoded) -Compact } else { Write-FwJson ([pscustomobject]$decoded) }
+exit 0