Working with Sessions

Every capture produces a .sr session file. These files contain the raw digital samples exactly as acquired from hardware — timestamped, lossless, and ready to decode as many times as you want with whatever decoder and options you choose. This page covers the full session lifecycle.

Where sessions live

Session files are stored in ~/.local/share/mcsigrok/sessions/. The directory is created automatically on first capture. Each file is a standard sigrok session (ZIP archive containing metadata and binary sample data), compatible with PulseView and other sigrok tools.

Session naming

By default, sessions are named with the driver and a UTC timestamp:

fx2lafw-20260307-142530.sr

You can assign a custom name during capture with the session_name parameter:

capture(
  sample_rate="1M",
  samples="10k",
  channels="D0,D1",
  session_name="modbus-field-test"
)

This produces modbus-field-test.sr. Descriptive names help when you accumulate dozens of captures across different debugging sessions.

Listing sessions

list_sessions returns all .sr files sorted by modification time, newest first:

list_sessions()

{
  "sessions": [
    {
      "name": "modbus-field-test",
      "path": "/home/user/.local/share/mcsigrok/sessions/modbus-field-test.sr",
      "size_bytes": 24576,
      "modified": "2026-03-07T14:25:30+00:00"
    },
    {
      "name": "fx2lafw-20260306-091200",
      "path": "/home/user/.local/share/mcsigrok/sessions/fx2lafw-20260306-091200.sr",
      "size_bytes": 12288,
      "modified": "2026-03-06T09:12:00+00:00"
    }
  ],
  "count": 2
}

Inspecting a session

session_info runs sigrok-cli --show on the session file to extract capture metadata:

session_info(session="modbus-field-test")

The output includes the sample rate, number of samples, channel names, and capture duration. This is useful for verifying what you captured before decoding, or when you come back to a session days later and need to remember the setup.

You can pass either the session name (with or without .sr) or the full path.

Re-decoding sessions

The core value of session files: decode them again with different parameters without re-acquiring from hardware. The target device does not even need to be connected.

Suppose you captured a UART signal and decoded it at 9600 baud, but the output was garbled. Try a different baud rate on the same session:

decode_capture(
  decoder="uart",
  source="modbus-field-test",
  channels={"rx": "D0"},
  options={"baudrate": "115200"}
)

Or try a completely different decoder. Maybe those signals are not UART at all — try I2C:

decode_capture(
  decoder="i2c",
  source="modbus-field-test",
  channels={"scl": "D0", "sda": "D1"}
)

You can also apply decoder stacking to existing sessions:

decode_capture(
  decoder="uart",
  source="modbus-field-test",
  channels={"rx": "D0"},
  options={"baudrate": "9600"},
  stack=["modbus"]
)

The decode_saved_session prompt provides a guided walkthrough for re-analyzing any session file. Give it the session name and it steps through inspection, decoder selection, and export.

Exporting sessions

export_session converts the raw session data into a text format. Five output formats are available:

Format	Description	Use case
csv	Comma-separated values with timestamps	Spreadsheet analysis, custom scripts
vcd	Value Change Dump	Waveform viewers (GTKWave, PulseView)
hex	Hexadecimal dump	Quick visual inspection of bit patterns
bits	Binary (0/1) representation	Bit-level debugging
ascii	ASCII art waveform	Inline visualization without external tools

CSV export

export_session(session="modbus-field-test", format="csv")

CSV output includes a header row with channel names and a timestamp column. Each subsequent row is one sample across all channels.

VCD for waveform viewers

VCD (Value Change Dump) is the standard format for waveform visualization tools. Export to VCD and open in GTKWave or PulseView for graphical signal analysis:

export_session(session="modbus-field-test", format="vcd")

GTKWave reads .vcd files directly. This is particularly useful when you need to correlate timing between channels or zoom into specific signal transitions that the protocol decoder flagged as errors.

Filtering channels on export

If a session captured 8 channels but you only care about two, pass the channels parameter:

export_session(
  session="modbus-field-test",
  format="csv",
  channels="D0,D1"
)

This reduces the output to just the channels you need.

Deleting sessions

delete_session removes a session file permanently. It asks for confirmation before proceeding:

delete_session(session="fx2lafw-20260306-091200")

The tool reports the file name and size of the deleted session. There is no undo — once deleted, the raw sample data is gone. If a capture took significant effort to reproduce (intermittent bus fault, specific environmental condition), consider keeping the session file.

Programmatic access via resource

The sigrok://sessions resource provides a live list of all session files, accessible programmatically without calling a tool. This is useful for MCP clients that want to enumerate available sessions before prompting the user to select one.

The resource returns the same data structure as list_sessions — session names, paths, sizes, and modification timestamps — sorted newest first.

Tips

Name sessions during field work. When you are at a bench probing a live system, the auto-generated timestamps all blur together. A name like motor-controller-startup or sensor-bus-idle saves time later.

Keep sessions small when iterating. For protocol debugging, 10k-50k samples is usually enough to capture several complete transactions. Large captures (millions of samples) are useful for statistical analysis or catching rare glitches, but they slow down every decode pass.

Re-decode before re-capturing. If the decode output looks wrong, the problem is more often a decoder option (wrong baud rate, wrong SPI mode) than a bad capture. Try different settings on the existing session before going back to hardware.