sigrok

name	sigrok
description	Control logic analyzers via sigrok-cli to capture, decode, and analyze digital signals. Use when the user mentions: logic analyzer, signal capture, protocol decoding, sigrok, bus traces, I2C/SPI/UART/JTAG capture, waveform acquisition, or wants to debug digital signals on hardware. Covers live capture, offline decoding from .sr files, and automated analysis of decoded protocol data.

Sigrok Logic Analyzer Skill

Control logic analyzers through sigrok-cli. This skill handles: device setup, signal capture, protocol decoding, and output analysis.

Capture-First Principle

ALWAYS capture raw data to a .sr file first, then decode offline.

sigrok-cli is single-threaded. Running protocol decoders during live capture at high sample rates overwhelms the pipeline and causes dropped samples or early termination. The two-phase approach (capture → decode) prevents this.

Workflow

Mode Selection

Interactive (default): Use when the setup is new or the user hasn't specified all parameters. Walk through each step, confirm with the user.

Autonomous: Use when the user gives a complete request with all needed info (protocol, channels, rate, duration). Skip confirmations, go straight to capture→decode→analyze. Still ask for save location.

Steps

1. Detect device

   sigrok-cli --scan
   

   Parse the output to identify the connected device. Then read the matching device profile from ~/.claude/commands/sigrok/ to get device-specific capabilities. Match by driver name in the scan output:

   • sipeed-slogic-analyzer → read ~/.claude/commands/sigrok/sipeed-slogic16u3.md

   If no device found, check if running on WSL:

   test -f /proc/sys/fs/binfmt_misc/WSLInterop && echo "WSL" || echo "native"
   

   On WSL, the USB device must be forwarded from Windows via usbipd-win. Look for the attach script and run it:

   # Find and run slogic-attach from the sigrok-skill repo
   SCRIPT=$(find ~/Documents /mnt/c/Users -maxdepth 5 -name "slogic-attach" -path "*/sigrok-skill/*" 2>/dev/null | head -1)
   if [[ -n "$SCRIPT" ]]; then bash "$SCRIPT"; fi
   

   Then retry sigrok-cli --scan. If the script isn't found, tell the user to install it from https://github.com/jguy/sigrok-skill (scripts/ directory) or run manually:

   "/mnt/c/Program Files/usbipd-win/usbipd.exe" list    # find the device
   "/mnt/c/Program Files/usbipd-win/usbipd.exe" bind --busid <BUSID>
   "/mnt/c/Program Files/usbipd-win/usbipd.exe" attach --wsl --busid <BUSID>
   

   On native Linux: check USB connection, suggest USB 3.0 port, check permissions (sudo sigrok-cli --scan).

2. Ask save location Ask the user where to save capture files. Suggest a timestamped filename like <protocol>_capture_YYYYMMDD_HHMMSS.sr.

3. Configure channels (interactive mode) Ask which device channels are connected to which signals. Use the device profile's channel naming convention. Example for I2C:

   • "Which channels are SCL and SDA connected to? (e.g., D0 and D1)"

4. Configure protocol settings (interactive mode) Ask for protocol-specific parameters:

   • I2C: bus speed (100k/400k/1M) — affects sample rate choice
   • SPI: CPOL, CPHA, word size, bit order, CS polarity
   • UART: baud rate, parity, data bits, stop bits, inversion
   • JTAG: just channel mapping (no protocol options)

5. Configure triggers (optional) Ask if the user wants to trigger on a specific condition:

   • Rising edge (r), falling edge (f), any edge (e)
   • High level (1), low level (0)
   • Which channel to trigger on Example: "Trigger on D1 falling edge to catch I2C START conditions"

   If triggers are used, add --wait-trigger to suppress pre-trigger data unless the user wants pre-trigger context.

6. Select sample rate Use the Sample Rate Selection Guide below. Validate the rate against the device profile's supported rates. Never use a rate not in the device profile's list.

7. Capture

   sigrok-cli -d <driver> \
     --config samplerate=<rate> \
     --channels <channel-spec> \
     --time <duration> \
     -o <output-file>.sr
   

   Add trigger flags if configured. Use --samples instead of --time if the user specified a sample count.

8. Decode

   sigrok-cli -i <capture-file>.sr \
     -P <decoder-stack> \
     -A <annotation-filter>
   

   Use the Protocol Decode Recipes below for correct syntax.

9. Analyze Read the decoded output and summarize findings:

   • I2C: addresses seen, NACKs, register read/write patterns
   • SPI: data exchanged, CS activity
   • UART: text content, framing errors
   • JTAG: state transitions, IR/DR values

Protocol Decode Recipes

I2C

Capture:

sigrok-cli -d <driver> \
  --config samplerate=10m \
  --channels D0=SCL,D1=SDA \
  --time 3s \
  -o i2c_capture.sr

Decode (addresses + data):

sigrok-cli -i i2c_capture.sr \
  -P i2c:scl=SCL:sda=SDA \
  -A i2c=address-read:address-write:data-read:data-write

Check for NACKs:

sigrok-cli -i i2c_capture.sr \
  -P i2c:scl=SCL:sda=SDA \
  -A i2c=nack

With stacked decoder (e.g., EEPROM):

sigrok-cli -i i2c_capture.sr \
  -P i2c:scl=SCL:sda=SDA,eeprom24xx \
  -A eeprom24xx

Options: address_format = shifted (default) | unshifted

Annotation classes: start, repeat-start, stop, ack, nack, bit, address-read, address-write, data-read, data-write, warnings

SPI

Capture:

sigrok-cli -d <driver> \
  --config samplerate=50m \
  --channels D0=CS,D1=CLK,D2=MOSI,D3=MISO \
  --time 2s \
  -o spi_capture.sr

Decode:

sigrok-cli -i spi_capture.sr \
  -P spi:clk=CLK:mosi=MOSI:miso=MISO:cs=CS \
  -A spi

Options: cs_polarity (active-low | active-high), cpol (0 | 1), cpha (0 | 1), bitorder (msb-first | lsb-first), wordsize (1-64, default 8)

Annotation classes: miso-data, mosi-data, miso-bits, mosi-bits, warnings

UART

Capture (TX only):

sigrok-cli -d <driver> \
  --config samplerate=5m \
  --channels D0=TX \
  --time 5s \
  -o uart_capture.sr

Decode:

sigrok-cli -i uart_capture.sr \
  -P uart:rx=TX:baudrate=115200 \
  -A uart=rx-data

Bidirectional:

sigrok-cli -i uart_capture.sr \
  -P uart:rx=RX:tx=TX:baudrate=115200 \
  -A uart=rx-data:tx-data

Raw binary output:

sigrok-cli -i uart_capture.sr \
  -P uart:rx=TX:baudrate=115200 \
  -B uart=rx

Options: baudrate (default 115200), parity_type (none | odd | even), num_data_bits (5-9), num_stop_bits (0 | 1 | 2), bit_order (lsb-first | msb-first), invert_rx / invert_tx (yes | no), format (ascii | hex | oct | bin)

JTAG

Capture:

sigrok-cli -d <driver> \
  --config samplerate=10m \
  --channels D0=TCK,D1=TMS,D2=TDI,D3=TDO \
  --time 5s \
  -o jtag_capture.sr

Decode:

sigrok-cli -i jtag_capture.sr \
  -P jtag:tck=TCK:tms=TMS:tdi=TDI:tdo=TDO \
  -A jtag

1-Wire

Capture:

sigrok-cli -d <driver> \
  --config samplerate=5m \
  --channels D0=OWR \
  --time 5s \
  -o onewire_capture.sr

Decode:

sigrok-cli -i onewire_capture.sr \
  -P onewire_link:owr=OWR,onewire_network \
  -A onewire_network

Multi-Protocol (parallel decode from single capture)

# Capture all needed channels
sigrok-cli -d <driver> \
  --config samplerate=10m \
  --channels D0=SCL,D1=SDA,D2=TX,D3=CS,D4=SCLK,D5=MOSI \
  --time 5s \
  -o multi_capture.sr

# Decode all protocols in parallel
sigrok-cli -i multi_capture.sr \
  -P i2c:scl=SCL:sda=SDA \
  -P uart:rx=TX:baudrate=115200 \
  -P spi:clk=SCLK:mosi=MOSI:cs=CS

Triggering

sigrok-cli -d <driver> \
  --config samplerate=10m \
  --channels D0=SCL,D1=SDA \
  --triggers D1=f \
  --wait-trigger \
  --time 500 \
  -o triggered_capture.sr

Trigger types: 0 (low), 1 (high), r (rising), f (falling), e (edge).

Check device profile for supported trigger types — not all devices support all types.

Sample Rate Selection Guide

Pick at least 4x the signal frequency (10x is better for clean edges).

Protocol	Signal Freq	Recommended Rate
I2C 100 kHz	100 kHz	5-10 MHz
I2C 400 kHz	400 kHz	5-10 MHz
I2C 1 MHz	1 MHz	10 MHz
SPI ≤5 MHz	5 MHz	20-50 MHz
SPI ≤10 MHz	10 MHz	50-100 MHz
SPI ≤25 MHz	25 MHz	100-200 MHz
UART 115200	~115 kHz	5 MHz
UART 1 Mbaud	1 MHz	5-10 MHz
JTAG ≤10 MHz	10 MHz	50-100 MHz

Validate the chosen rate against the device profile's supported list.

Output Formats

Flag	Format	Use
-o file.sr	Session file	Default. Recommended for all captures.
-O binary	Raw binary	High-speed streaming, piping.
-O csv	CSV	Import to spreadsheets/scripts. Options: dedup, header, time.
-O hex	Hex display	Quick visual check. Option: width=N.
-O bits	Bit display	Quick logic level check. Option: width=N.

CLI Quick Reference

Command	Purpose
sigrok-cli --scan	Find connected devices
sigrok-cli -d <drv> --show	Show device capabilities
sigrok-cli -i file.sr --show	Inspect capture file metadata
sigrok-cli --protocol-decoders <id> --show	Show decoder options/signals
sigrok-cli -L	List all drivers, formats, decoders

Additional Decode Flags

Flag	Purpose
--protocol-decoder-samplenum	Include sample numbers in annotations (for timing)
--protocol-decoder-ann-class	Show annotation class names in output
--protocol-decoder-jsontrace	Output in Google Trace Event JSON format
-M <decoder>=<meta>	Show decoder meta output (e.g., baud rate detection)
-B <decoder>=<class>	Raw binary decoder output to stdout

Available Protocol Decoders (132 total)

Use sigrok-cli --protocol-decoders <id> --show to see options and signals for any decoder. Use sigrok-cli -L for the full list.

Serial buses: uart, spi, i2c, i2s, onewire_link, onewire_network, microwire, modbus, lin, can, flexray, dali, dsi, dmx512, sbus_futaba, midi, ps2, sdq, spdif, wiegand, swim, swd, jtag, cjtag, jtag_stm32, jtag_ejtag, lpc, parallel, pjon, pjdl, ssi32, tdm_audio, xy2-100

I2C peripherals: eeprom24xx, ds1307, lm75, adxl345, mlx90614, mcp230xx, pca9571, nunchuk, mxc6225xu, rtc8564, edid, ina2xx, tca6408a

SPI peripherals: spiflash, eeprom93xx, sdcard_spi, enc28j60, nrf24l01, mrf24j40, cc1101, nrf905, rfm12, rgb_led_spi, max72xx, ad5626, ad79x0, adf435x, adns5020, ltc242x, ltc26x7, avr_isp, avr_pdi, st25r39xx_spi, st7735, sda2506, tlc5620, ade77xx

USB: usb_signalling, usb_packet, usb_request, usb_power_delivery

Wireless/RF: ir_nec, ir_rc5, ir_rc6, ir_sirc, ir_irmp, em4100, em4305, t55xx, ook, ook_oregon, ook_vis, nrf24l01, rc_encode, rgb_led_ws281x

Automotive/industrial: can, flexray, lin, sae_j1850_vpw, qi

ARM debug: arm_etmv3, arm_itm, arm_tpiu, swd

Timing/utility: counter, timing, jitter, guess_bitrate, pwm, stepper_motor, numbers_and_state, graycode, signature, caliper, seven_segment, morse, miller, dcf77

Memory cards: sdcard_sd, sdcard_spi, sle44xx, x2444m, atsha204a

Audio/video: ac97, cec, hdcp, i2s, spdif, tdm_audio

Display/optics: cfp, xfp, lfast, sipi

Filters/demux: i2cdemux, i2cfilter, z80, mcs48, aud, pan1321

Troubleshooting

Device not found:

1. On WSL: USB device must be forwarded via usbipd-win (see "Detect device" step above)
2. Use USB 3.0 port (not a hub)
3. Check udev rules on Linux (vendor-specific — see device profile)
4. Try sudo sigrok-cli --scan

Empty or no data:

1. Verify physical wiring matches channel assignments
2. Check voltage threshold vs signal voltage (see device profile)
3. Ensure sample rate is high enough
4. If using triggers, test without --wait-trigger first

Garbled decode:

1. Increase sample rate (at least 4x signal frequency)
2. Verify protocol settings (baud, CPOL, CPHA, etc.)
3. Check channel-to-signal mapping in -P
4. For UART, try invert_rx=yes if signal is inverted

Capture terminates early:

1. Use capture-first pattern (no -P during live capture)
2. Reduce sample rate or channel count
3. Use binary output for high-speed streaming