Skip to main content
skill CX Codex

protocol-analysis — Claude Code skill: what it does, how to install

protocol-analysis is a Claude Code skill that decodes I2C, SPI, and UART captures with sigrok and PulseView, then checks them against driver code. It handles silent-sensor bus analysis.

MIT 383 installs ★ 298 updated 2026-06-27

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mohitmishra786/low-level-dev-skills --skill protocol-analysis -a claude-code
Open on GitHub

What protocol-analysis does

This skill walks an agent through reading I2C, SPI and UART traffic from a logic analyzer capture. It shows how to run sigrok-cli or PulseView with the fx2lafw driver and export VCD or CSV for your own scripts. For I2C it lays out the phases of a transaction: START, address with the R/W bit, data bytes with ACKs, STOP. A NACK on the address points to a wrong address such as 0x48, or to a device stuck in reset.

For SPI the checklist covers mode (CPOL/CPHA), bit order, CS polarity and word size, compared against spi_setup() in the driver. UART needs the baud rate (9600 or 115200), the 8N1 frame format and a sample rate of at least 4× baud. A short Python snippet reads capture.csv and rebuilds bits from edges.

You bring the capture hardware; the skill mentions cheap FX2LA boards. Without sigrok-cli and its decoders there is nothing to decode with. The final step lines the capture up against the firmware's register write order and the datasheet's inter-byte delays.

What it helps with

  • find out why a sensor NACKs its address
  • decode an I2C dump from PulseView or sigrok-cli
  • pick the right CPOL/CPHA when SPI bits come out shifted
  • trace UART framing errors to baud drift
  • parse a CSV capture in Python by detecting edges

Example prompts for the agent

  • /protocol-analysis The device NACKs after I wrote register 0x0F, decode this I2C capture and tell me why
  • /protocol-analysis My SPI bits look shifted, help me work out CPOL/CPHA
  • Use protocol-analysis to parse capture.csv and rebuild the UART 8N1 bytes at 115200

How to install protocol-analysis

1Skills CLI (Vercel)

npx skills add mohitmishra786/low-level-dev-skills --skill protocol-analysis -a claude-code

2Manually: put the files in place

~/.claude/skills/protocol-analysis/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/protocol-analysis/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about protocol-analysis

How do I install protocol-analysis in Claude Code?

Run npx skills add mohitmishra786/low-level-dev-skills --skill protocol-analysis -a claude-code. The skill file ends up at ~/.claude/skills/protocol-analysis/SKILL.md.

What does protocol-analysis do?

It helps an agent decode I2C, SPI and UART traffic from a logic analyzer capture using sigrok and PulseView, then compare it with driver code and the datasheet.

What do I need before using protocol-analysis?

Some way to capture the signals, plus sigrok-cli with its decoders installed. The sample rate has to be at least 4× the bus speed, otherwise the decoded output is garbage.

Source text

SKILL.md · MIT
---
name: protocol-analysis
description: Protocol analysis skill for serial bus debugging. Use when decoding I2C/SPI/UART with logic analyzer concepts, sigrok/PulseView, or Python capture scripts. Activates on queries about logic analyzer, sigrok, PulseView, decode I2C SPI UART, or bus protocol capture.
---

# 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](https://sigrok.org/) with cheap FX2LA boards.

### 2. PulseView quick start

```bash
# 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)

```python
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

© mohitmishra786 · MIT · mohitmishra786/low-level-dev-skills

Similar skills

All skills for Testing and QA →

From the same set140

The whole set →
kernel-memory-management kernel-memory-management — a skill that walks an AI agent through Linux kernel allocation: kmalloc vs vmalloc vs page allocator, GFP flags, zones and OOM debugging. CX Codex +1 388installs cuda-debugging Walks the agent through CUDA debugging: cuda-gdb, Compute Sanitizer, GPU core dumps, error codes 700 and 702. Useful when a kernel crashes or returns wrong values. CX Codex +1 386installs llvm-ir-and-passes llvm-ir-and-passes teaches the agent to read LLVM IR, understand SSA form, and navigate optimization passes. Useful when tracing what -O2 changed or preparing to write a custom pass. CX Codex +1 384installs spi-i2c-baremetal The spi-i2c-baremetal skill guides bare-metal SPI and I2C driver work, from register reads to bus troubleshooting. Use it when bringing up sensors, flash, or displays. CX Codex +1 384installs gpio-baremetal gpio-baremetal configures GPIO modes, alternate functions, pull resistors, and EXTI interrupts on bare-metal microcontrollers without HAL. CX Codex +1 383installs apple-silicon A skill for developers building on Apple Silicon: tuning code for unified memory, Metal Performance Shaders, Instruments profiling, Rosetta 2 behavior, and 16KB page size quirks. CX Codex +1 383installs code-generation-and-backends code-generation-and-backends explains LLVM backend stages, from IR legalization to assembly output. Use it to investigate llc, TableGen patterns, or the outline of a new target port. CX Codex +1 382installs jit-compilation jit-compilation teaches the agent to build a JIT: LLVM ORC and LLJIT, Cranelift, inline caches, trampolines, Rust dynasm. Useful for interpreter hot paths and REPLs. CX Codex +1 382installs

Project sponsors

Companies that keep this analytics open