protocol-analysis
/protocol-analysis
Use when decoding I2C, SPI, or UART captures with sigrok or PulseView, checking bus traffic against a datasheet, or post-processing captures in Python. Not for bus drivers: use spi-i2c-baremetal.
- Author
- OutlineDriven ↗
- Repository
- outline-driven-development ↗
- Licence
- Apache-2.0
- Last repository change
- 28.09.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 28.09.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Use when decoding I2C, SPI, or UART captures with sigrok or PulseView, checking bus traffic against a datasheet, or post-processing captures in Python. Not for bus drivers: use spi-i2c-baremetal.
Original author description
Use when decoding I2C, SPI, or UART captures with sigrok or PulseView, checking bus traffic against a datasheet, or post-processing captures in Python. Not for bus drivers: use spi-i2c-baremetal.
How it works
- Contract
- Inputs
- Procedure
- Failure and recovery
- Output
SKILL.md preview
---
name: protocol-analysis
description: 'Use when decoding I2C, SPI, or UART captures with sigrok or PulseView, checking bus traffic against a datasheet, or post-processing captures in Python. Not for bus drivers: use spi-i2c-baremetal.'
disable-model-invocation: true
---
# Protocol analysis (I2C / SPI / UART)
## Contract
| Field | Bound contract |
|---|---|
| Trigger | A serial bus capture needs decoding, a device does not answer on I2C/SPI/UART, or a logic-analyzer capture needs correlation with the firmware driver. |
| Authority | Read-only. Emits analysis and commands for the operator to run on the capture setup; no file writes, no rollback needed. No remote mutation. |
| Side effect | Capture and decode commands plus a verdict in chat. Nothing is written. |
| Done | The bus fault is named (wrong address, wrong mode, missing pull-up, baud drift) or the capture is confirmed clean against the datasheet. |
## Inputs
1. Capture or symptom (required): a sigrok/PulseView capture, a CSV export, or a description of the failing transaction.
2. Datasheet or reference manual (required): the expected transaction format for the device.
3. Firmware driver source (optional): for correlating the capture with register writes.
## Procedure
1. Set up the capture stack.
```text
Physical probe -> logic analyzer hardware (or GPIO bit-bang)
|-- sigrok-cli / PulseView GUI
|-- protocol decoder (i2c, spi, uart)
+-- export VCD/CSV for scripts
```
sigrok drives the common open-source path, including cheap FX2-based boards. Done when: the analyzer records edges on the probed lines.
2. Capture with sigrok-cli or PulseView.
```bash
pulseview # GUI: pick device, channels, decoder
sigrok-cli --driver fx2lafw --config samplerate=1MHz \
--channels 0=SDA,1=SCL \
--samples 1m \
-P i2c # -P attaches the protocol decoder
```
Done when: the decoder emits transactions, not raw edges.
3. Check I2C against the expected phases.
| Phase | Lines |
|---|---|
| START | SDA falls while SCL is high |
| Address plus R/W | 7 bits, then ACK |
| Data bytes | ACK per byte |
| STOP | SDA rises while SCL is high |
A NACK at the address phase means the address is wrong or the device is held in reset. Done when: each phase matches, or the failing phase is named.
4. Check SPI. Confirm the mode (CPOL/CPHA), bit order (MSB first is typical), CS polarity, and word size against the device datasheet and the driver's `spi_setup()`. Done when: mode and framing match on both ends.
5. Check UART. Set the baud rate (9600 or 115200 are common), the frame (8N1 is typical), and signal polarity. UART is asynchronous: sample at least 4x the baud rate, higher for marginal signals. Done when: decoded bytes match the expected output.
6. Post-process a CSV export in Python.
```python
import csv
with open("capture.csv") as f:
for ts, ch0, ch1 in csv.reader(f):
# edge-detect, then reconstruct bits
pass
```
Done when: the script extracts the transactions of interest.
7. Correlate the capture with the firmware.
```text
Logic capture timestamp
|-- match the driver's register write sequence
|-- compare inter-byte delay against the datasheet maximum
+-- flag extra clock pulses (mode fault)
```
Done when: every bus anomaly maps to a driver line or a datasheet violation.
## Failure and recovery
| Symptom | Cause | Fix |
|---|---|---|
| Garbage decode | Sample rate too low | Sample at least 4x the bus speed |
| Floating lines | Missing pull-ups | Enable internal pulls or fit external resistors |
| SPI bits shifted | Mode mismatch | Take the CPOL/CPHA pair from the reference manual |
| UART framing errors | Baud drift | Measure the actual bit time, do not trust the nominal rate |
| No decoder output | Decoder not attached | Pass `-P i2c` (or `spi`, `uart`) to sigrok-cli, or add the decoder in PulseView |
## Output
A verdict naming the bus fault and its phase, or a confirmation that the capture matches the datasheet, with the decode settings used.
Files in this package (2)
- SKILL.md 4 KB
- agents/openai.yaml 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · OutlineDriven/outline-driven-development | 100 | Apache-2.0 |
| mohitmishra786/low-level-dev-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 79cca4c09fab (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 81bus-debugging
Diagnose SPI, UART, CAN and I2C protocol failures using transaction evidence and electrical constraints. Use when requests involve corrupt bytes, wrong SPI mode, framing, bus-off, chip-select timing or DMA transfers; use I2C bring-up for basic discovery. - 100spi-i2c-baremetal
Use when implementing SPI/I2C master transfers, register read/write protocols, I2C START/STOP, clock phase/polarity, or bus stalls on bare-metal MCUs. Not for Linux drivers: use device-drivers. - 100bus-drivers-i2c-spi
I2C and SPI bus driver skill for Linux client drivers. Use when writing i2c_driver or spi_driver, register access over bus, DMA SPI transfers, or ACPI/DT client binding. Activates on queries about i2c_client, spi_driver, regmap I2C, SPI transfer, or Linux I2C SPI subsystem. - 95scaffold_driver
Scaffold a device driver for one external peripheral chip (header, source and register map) on top of the project's HAL, with every register, address and bus setting taken from the part's datasheet and the board's schematic, and record it in the twin. Use when the user asks to… - 100communication-buses
Bus reference for I2C, SPI, UART, CAN, and USB: addressing, pull-up sizing, bus recovery, SPI mode card, DMA cache rules, ring buffers, CAN bit timing and error states, USB descriptors, and STM32 HAL code for each bus. Use when writing or reviewing a bus driver or diagnosing a misbehaving bus. - 95esp32-spi-and-devices
Use when an ESP32 talks to SPI peripherals - the second device on the bus fails, the bus is initialised twice, transfers are slow or corrupted, or the clock rate is a guess. Covers bus versus device, DMA and chip select.