mohitmishra786/protocol-analysis

Protocol Analysis (I2C / SPI / UART)

Purpose

Guide agents through software-side serial bus analysis: logic analyzer workflow, sigrok/PulseView decoding, correlating captures with firmware drivers, and Python-based parsing — bridging skills/baremetal/spi-i2c-baremetal and hardware bring-up.

When to Use

• Sensor not responding — verify clock and data on bus
• Compare kernel driver transactions vs datasheet
• Document expected transaction format for CI/regression
• Teaching protocol layers without expensive lab gear (sim + decode)

Workflow

1. Capture stack

Physical probe → logic analyzer hardware (or GPIO bit-bang)
├── sigrok-cli / PulseView GUI
├── Protocol decoder (i2c, spi, uart)
└── Export VCD/CSV for scripts

Open-source: sigrok with cheap FX2LA boards.

2. PulseView quick start

# List devices
pulseview

# CLI capture (device-dependent)
sigrok-cli --driver fx2lafw --config samplerate=1MHz \
  --channels 0=SDA,1=SCL \
  --samples 1m \
  --protocols i2c

3. I2C decode expectations

| Phase | Lines | |-------|-------| | START | SDA fall while SCL high | | Address + R/W | 7 bits + ACK | | Data bytes | ACK per byte | | STOP | SDA rise while SCL high |

NACK at address → wrong 0x48 or device held in reset.

4. SPI decode

Check mode (CPOL/CPHA), bit order (MSB first typical), CS polarity, and word size. Compare to spi_setup() in skills/kernel-dev/bus-drivers-i2c-spi.

5. UART decode

Set baud (9600/115200), frame (8N1), and signal polarity. Async — sample rate must be ≥ 4× baud for LA.

6. Python post-process (csv)

import csv

with open("capture.csv") as f:
    for ts, ch0, ch1 in csv.reader(f):
        # edge detect, reconstruct bits
        pass

7. Correlate with firmware

Logic capture timestamp
├── Match driver reg write sequence
├── Compare inter-byte delay vs datasheet max
└── Flag extra clock pulses (mode fault)

8. Agent usage

/protocol-analysis Decode this I2C capture — device NACKs after register 0x0F write

Common Problems

| Symptom | Cause | Fix | |---------|-------|-----| | Garbage decode | Wrong samplerate | ≥ 4× bus speed | | Floating lines | Missing pull-ups | Enable internal pull or external | | SPI shifted bits | Mode mismatch | CPOL/CPHA table from RM | | UART framing errors | Baud drift | Measure actual bit time | | No decoder | Missing sigrok build | Install sigrok-cli + decoders |

Related Skills

• skills/baremetal/spi-i2c-baremetal — firmware-side protocol
• skills/baremetal/uart-serial-baremetal — UART config
• skills/kernel-dev/bus-drivers-i2c-spi — kernel transactions
• skills/profilers/strace-ltrace — userspace syscall trace analog
• skills/embedded/openocd-jtag — scope alongside SWD debug