Zum Inhalt springen
1337skills 1337skills - Referenzen

sigrok Cheat Sheet

Overview

sigrok is a portable, cross-platform, free open-source signal analysis software suite that supports logic analyzers, oscilloscopes, MSOs (mixed-signal oscilloscopes), multimeters, LCR meters, power supplies, and other test and measurement equipment. The project consists of several components: libsigrok (hardware driver library), libsigrokdecode (protocol decoder library), PulseView (GUI frontend), and sigrok-cli (command-line interface). Together, they provide a unified platform for capturing, viewing, and decoding digital and analog signals from dozens of hardware devices.

The protocol decoder library (libsigrokdecode) is one of sigrok’s most powerful features, offering over 100 protocol decoders including SPI, I2C, UART, JTAG, CAN, USB, 1-Wire, SDIO, NAND, and many more. Decoders can be stacked, so a low-level UART decoder can feed into an HDLC or Modbus decoder for multi-layer analysis. sigrok supports hardware from Saleae (via open drivers), DSLogic, fx2lafw-compatible analyzers, Rigol oscilloscopes, and many more devices, making it the swiss army knife of hardware analysis.

Installation

Ubuntu/Debian

sudo apt update
sudo apt install sigrok pulseview sigrok-cli

# Install additional firmware for supported devices
sudo apt install sigrok-firmware-fx2lafw

# Verify
sigrok-cli --version
pulseview --version

Fedora/CentOS

sudo dnf install sigrok-cli pulseview

macOS

brew install sigrok-cli libsigrokdecode
brew install --cask pulseview

From Source

# Install dependencies
sudo apt install git gcc g++ make cmake python3-dev \
  libglib2.0-dev libglibmm-2.4-dev libzip-dev libusb-1.0-0-dev \
  libftdi1-dev libserialport-dev libboost-all-dev \
  qtbase5-dev libqt5svg5-dev

# Build libsigrok
git clone git://sigrok.org/libsigrok
cd libsigrok && ./autogen.sh && ./configure && make && sudo make install

# Build libsigrokdecode
git clone git://sigrok.org/libsigrokdecode
cd libsigrokdecode && ./autogen.sh && ./configure && make && sudo make install

# Build PulseView
git clone git://sigrok.org/pulseview
cd pulseview
cmake -DCMAKE_BUILD_TYPE=Release .
make -j$(nproc)
sudo make install

USB Permissions (Linux)

# Add udev rules for logic analyzers
sudo cp contrib/60-libsigrok.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

# Add user to plugdev group
sudo usermod -aG plugdev $USER
# Log out and back in

sigrok-cli

Device Discovery

# List supported drivers
sigrok-cli --list-drivers

# Scan for connected devices
sigrok-cli --scan

# Scan specific driver
sigrok-cli --driver fx2lafw --scan
sigrok-cli --driver saleae-logic16 --scan
sigrok-cli --driver rigol-ds --scan

Basic Capture

# Capture with default settings
sigrok-cli --driver fx2lafw --output-file capture.sr

# Capture with specific sample rate and sample count
sigrok-cli --driver fx2lafw \
  --config samplerate=1M \
  --samples 1000000 \
  --output-file capture.sr

# Capture for specific duration
sigrok-cli --driver fx2lafw \
  --config samplerate=4M \
  --time 5s \
  --output-file capture.sr

# Capture specific channels only
sigrok-cli --driver fx2lafw \
  --config samplerate=8M \
  --channels 0-3 \
  --samples 500000 \
  --output-file capture.sr

# Capture with trigger
sigrok-cli --driver fx2lafw \
  --config samplerate=1M \
  --triggers 0=r \
  --samples 100000 \
  --output-file capture.sr

Trigger Options

TriggerDescription
0Low level
1High level
rRising edge
fFalling edge
eEither edge (rising/falling)
# Trigger on rising edge of channel 0
sigrok-cli --driver fx2lafw --triggers 0=r --samples 10000

# Trigger on falling edge of channel 2
sigrok-cli --driver fx2lafw --triggers 2=f --samples 10000

# Multiple trigger conditions
sigrok-cli --driver fx2lafw --triggers "0=1,1=0" --samples 10000

Output Formats

# Save as sigrok session (default)
sigrok-cli -d fx2lafw --samples 10000 -o capture.sr

# Save as CSV
sigrok-cli -d fx2lafw --samples 10000 -O csv -o capture.csv

# Save as VCD (Value Change Dump)
sigrok-cli -d fx2lafw --samples 10000 -O vcd -o capture.vcd

# Save as binary
sigrok-cli -d fx2lafw --samples 10000 -O binary -o capture.bin

# Save as WAV (for analog)
sigrok-cli -d rigol-ds --samples 10000 -O wav -o capture.wav

# Output to stdout (pipe to other tools)
sigrok-cli -d fx2lafw --samples 10000 -O csv

Protocol Decoding

List Decoders

# List all available protocol decoders
sigrok-cli --list-decoders

# Show decoder details
sigrok-cli --show --protocol-decoders spi
sigrok-cli --show --protocol-decoders i2c
sigrok-cli --show --protocol-decoders uart

Common Decoders

DecoderDescriptionRequired Channels
uartUART/RS-232 async serialRX and/or TX
spiSPI busCLK, MISO, MOSI, CS
i2cI2C/SMBusSCL, SDA
jtagJTAG debug interfaceTCK, TMS, TDI, TDO
1wireDallas 1-WireOWR
canCAN busCAN_RX
usb_signallingUSB low-levelD+, D-
sdcard_spiSD card SPI modeCLK, MISO, MOSI, CS
nec_irNEC infrared remoteIR
ws2812WS2812 LED stripDIN
dht22DHT22 temp/humidity sensorDATA

Decode from Capture

# Decode UART from captured file
sigrok-cli -i capture.sr \
  -P uart:rx=0:baudrate=115200

# Decode SPI
sigrok-cli -i capture.sr \
  -P spi:clk=0:miso=1:mosi=2:cs=3

# Decode I2C
sigrok-cli -i capture.sr \
  -P i2c:scl=0:sda=1

# Decode JTAG
sigrok-cli -i capture.sr \
  -P jtag:tck=0:tms=1:tdi=2:tdo=3

Live Decode

# Capture and decode UART in real-time
sigrok-cli --driver fx2lafw \
  --config samplerate=1M \
  --samples 100000 \
  -P uart:rx=0:baudrate=9600

# Capture and decode SPI in real-time
sigrok-cli --driver fx2lafw \
  --config samplerate=4M \
  --samples 500000 \
  -P spi:clk=0:miso=1:mosi=2:cs=3

# Capture and decode I2C
sigrok-cli --driver fx2lafw \
  --config samplerate=2M \
  --samples 200000 \
  -P i2c:scl=0:sda=1

Stacked Decoders

# UART -> Modbus RTU (stacked)
sigrok-cli -i capture.sr \
  -P uart:rx=0:baudrate=9600,modbus

# SPI -> SPI Flash (stacked)
sigrok-cli -i capture.sr \
  -P spi:clk=0:miso=1:mosi=2:cs=3,spiflash

# I2C -> EEPROM (stacked)
sigrok-cli -i capture.sr \
  -P i2c:scl=0:sda=1,eeprom24xx

# USB signalling -> USB packet (stacked)
sigrok-cli -i capture.sr \
  -P usb_signalling:dp=0:dm=1,usb_packet

Decoder Output Formatting

# Show only specific annotation class
sigrok-cli -i capture.sr \
  -P uart:rx=0:baudrate=9600 \
  -A uart=rx-data

# Binary output (raw decoded bytes)
sigrok-cli -i capture.sr \
  -P uart:rx=0:baudrate=9600 \
  -B uart=rx-data > decoded.bin

# Python output format
sigrok-cli -i capture.sr \
  -P i2c:scl=0:sda=1 \
  -A i2c=address-read:address-write:data-read:data-write

PulseView (GUI)

Key Features

File > Open       - Open saved session
File > Save       - Save current session
Run/Stop button   - Start/stop capture

# Add protocol decoder:
1. Click "Add protocol decoder" (green +)
2. Select decoder (e.g., UART)
3. Map channels (e.g., RX = D0)
4. Set options (e.g., baudrate = 115200)

# Zoom: Mouse wheel or +/- keys
# Pan: Click and drag
# Measure: Right-click > Add cursor

Keyboard Shortcuts

KeyAction
SpaceStart/stop capture
+/-Zoom in/out
fZoom to fit
1/2Set cursor 1/2
sToggle sampling settings
Ctrl+OOpen file
Ctrl+SSave session

Supported Hardware

Logic Analyzers

DeviceChannelsMax RateDriver
Saleae Logic 8824 MHzfx2lafw
DSLogic Plus16400 MHzdreamsourcelab
Cypress FX2 (generic)8-1624 MHzfx2lafw
Open Bench Logic Sniffer32200 MHzols
Kingst LA series16-32500 MHzkingst-la

Oscilloscopes

# Rigol DS1054Z
sigrok-cli --driver rigol-ds:conn=tcp-raw/192.168.1.100/5555 --scan

# Hantek 6022BE
sigrok-cli --driver hantek-6xxx --scan

# Generic USBTMC
sigrok-cli --driver scpi-pps:conn=usbtmc/1234.5678 --scan

Advanced Usage

Automation Scripts

#!/bin/bash
# capture_uart.sh - Automated UART capture and decode

DEVICE="fx2lafw"
RATE="1M"
SAMPLES="1000000"
BAUD="115200"
OUTPUT="uart_capture_$(date +%Y%m%d_%H%M%S)"

# Capture
sigrok-cli --driver $DEVICE \
  --config samplerate=$RATE \
  --samples $SAMPLES \
  --channels 0 \
  -o "${OUTPUT}.sr"

# Decode
sigrok-cli -i "${OUTPUT}.sr" \
  -P uart:rx=0:baudrate=$BAUD \
  -A uart=rx-data > "${OUTPUT}_decoded.txt"

# Extract binary data
sigrok-cli -i "${OUTPUT}.sr" \
  -P uart:rx=0:baudrate=$BAUD \
  -B uart=rx-data > "${OUTPUT}_binary.bin"

echo "Capture saved to ${OUTPUT}.sr"
echo "Decoded text in ${OUTPUT}_decoded.txt"

Custom Protocol Decoder

# ~/.local/share/libsigrokdecode/decoders/myprotocol/__init__.py
# (empty)

# ~/.local/share/libsigrokdecode/decoders/myprotocol/pd.py
import sigrokdecode as srd

class Decoder(srd.Decoder):
    api_version = 3
    id = 'myprotocol'
    name = 'MyProtocol'
    longname = 'My Custom Protocol'
    desc = 'Custom protocol decoder'
    license = 'gplv3+'
    inputs = ['logic']
    outputs = []
    channels = (
        {'id': 'data', 'name': 'DATA', 'desc': 'Data line'},
    )
    annotations = (
        ('bit', 'Bit'),
        ('byte', 'Byte'),
    )

    def decode(self):
        while True:
            # Wait for edge
            self.wait({0: 'e'})
            # Process data...

Configuration

Sample Rate Selection

# List supported sample rates
sigrok-cli --driver fx2lafw --show

# Rule of thumb: sample at 4-10x the signal frequency
# UART 115200: use 1MHz+
# SPI 1MHz: use 4-8MHz
# I2C 400KHz: use 2-4MHz
# JTAG: use 4-8MHz

Troubleshooting

IssueSolution
Device not detectedCheck USB permissions, install udev rules
Firmware not found (fx2lafw)Install sigrok-firmware-fx2lafw package
Decoder shows errorsIncrease sample rate, check channel mapping
Garbled UART decodeVerify baud rate, check signal polarity
PulseView crashesUpdate to latest version, check GPU drivers
Trigger not workingNot all devices support hardware triggers
Capture too shortIncrease sample count or duration
Protocol decode missing dataSample rate too low for the protocol speed

Verification

# Test device connection
sigrok-cli --driver fx2lafw --scan

# Quick capture test
sigrok-cli --driver fx2lafw --config samplerate=1M --samples 1000

# List device capabilities
sigrok-cli --driver fx2lafw --show