/logicmso

name: logicmso
description: Analyze digital and analog captures from Saleae Logic MSO devices. Decode protocols like UART, SPI, I2C from exported binary files. Use when analyzing logic analyzer captures for CTF challenges, hardware reverse engineering, or protocol decoding.

Saleae Logic MSO Analysis

This skill enables analysis of captured signals from Saleae Logic MSO devices using the `saleae-mso-api` Python library. It supports loading binary exports, analyzing signal transitions, and decoding common protocols.

Prerequisites

• `saleae-mso-api` Python package — **Do NOT blindly pip install.** First check if it's already installed:

  python3 -c "from saleae.mso_api.binary_files import read_file; print('saleae-mso-api is available')"

Only if that fails, install it: `pip install saleae-mso-api`

• Binary export files from Saleae Logic software (`.bin` format)

Quick Reference

Loading Binary Files

from saleae.mso_api.binary_files import read_file
from pathlib import Path

file_path = Path("capture.bin")
saleae_file = read_file(file_path)

# Access metadata
print(f"Version: {saleae_file.version}")
print(f"Type: {saleae_file.type}")

# Access data
contents = saleae_file.contents

Digital Capture Structure

Digital exports contain `DigitalExport_V1` with chunks:

chunk = saleae_file.contents.chunks[0]

# Key attributes:
chunk.initial_state      # Starting logic level (0 or 1)
chunk.transition_times   # numpy array of transition timestamps (seconds)
chunk.sample_rate        # Capture rate in Hz
chunk.begin_time         # Capture start time
chunk.end_time           # Capture end time

Calculating Pulse Durations

import numpy as np

times = np.array(chunk.transition_times)
durations_ms = np.diff(times) * 1000  # Convert to milliseconds

# If initial_state is 0 (LOW):
#   - Even indices (0, 2, 4...) = HIGH pulse durations
#   - Odd indices (1, 3, 5...) = LOW gap durations
# If initial_state is 1 (HIGH):
#   - Even indices = LOW gap durations
#   - Odd indices = HIGH pulse durations

Helper Scripts

This skill includes helper scripts for common analysis tasks:

Protocol Analyzer

# Analyze signal characteristics
python3 skills/logicmso/analyze_protocol.py capture.bin

# Show detailed timing histogram
python3 skills/logicmso/analyze_protocol.py capture.bin --histogram

# Show detected timing clusters
python3 skills/logicmso/analyze_protocol.py capture.bin --clusters

# Export transitions to CSV
python3 skills/logicmso/analyze_protocol.py capture.bin --export transitions.csv

# Show raw transition values
python3 skills/logicmso/analyze_protocol.py capture.bin --raw -n 50

See [examples.md](examples.md) for full worked end-to-end captures: unknown-protocol triage, and UART, SPI, I2C, and 1-Wire decoding with runnable Python.

Common Protocol Patterns

UART (Asynchronous Serial)

• **Idle state**: HIGH
• **Start bit**: LOW (1 bit period)
• **Data bits**: 8 bits, LSB first
• **Stop bit**: HIGH (1-2 bit periods)
• **Common baud rates**: 9600, 19200, 38400, 57600, 115200
• **Bit period calculation**: `1/baud_rate` seconds
• **Identifying features**: Consistent bit periods, durations are multiples of base period

SPI (Serial Peripheral Interface)

• **4 signals**: SCLK (clock), MOSI (master out), MISO (master in), CS (chip select)
• **Clock polarity (CPOL)**: Idle clock state (0=LOW, 1=HIGH)
• **Clock phase (CPHA)**: Sample edge (0=leading, 1=trailing)
• **Data**: Sampled on clock edges, typically 8 bits per transaction
• **Identifying features**: Regular clock signal, CS goes LOW during transaction

I2C (Inter-Integrated Circuit)

• **2 signals**: SDA (data), SCL (clock)
• **Idle state**: Both HIGH (pulled up)
• **Start condition**: SDA falls while SCL is HIGH
• **Stop condition**: SDA rises while SCL is HIGH
• **Data**: 8 bits + ACK/NACK, MSB first
• **Address**: 7-bit (first byte after START)
• **Identifying features**: START/STOP conditions, 9 clock pulses per byte (8 data + ACK)

1-Wire

• **Single signal**: DQ (data/power)
• **Idle state**: HIGH (pulled up)
• **Reset pulse**: Master pulls LOW for 480us minimum
• **Presence pulse**: Slave responds LOW for 60-240us
• **Write 0**: LOW for 60-120us
• **Write 1**: LOW for 1-15us, then release
• **Read**: Master samples 15us after pulling LOW

Analysis Workflow

Step 1: Initial Exploration

from saleae.mso_api.binary_files import read_file
import numpy as np

f = read_file("capture.bin")
chunk = f.contents.chunks[0]

print(f"Sample rate: {chunk.sample_rate/1e6:.1f} MHz")
print(f"Duration: {chunk.end_time - chunk.begin_time:.3f}s")
print(f"Initial state: {'HIGH' if chunk.initial_state else 'LOW'}")
print(f"Transitions: {len(chunk.transition_times)}")

Step 2: Analyze Timing Patterns

times = np.array(chunk.transition_times)
durations_us = np.diff(times) * 1e6  # microseconds

# Separate HIGH and LOW durations
high_idx = 0 if chunk.initial_state == 0 else 1
high_durations = durations_us[high_idx::2]
low_durations = durations_us[(1-high_idx)::2]

print(f"HIGH pulses: min={min(high_durations):.1f}us, max={max(high_durations):.1f}us")
print(f"LOW gaps: min={min(low_durations):.1f}us, max={max(low_durations):.1f}us")

# Find unique timing values (cluster detection)
unique_high = sorted(set(round(d, -1) for d in high_durations))  # Round to 10us
unique_low = sorted(set(round(d, -1) for d in low_durations))
print(f"HIGH clusters: {unique_high}")
print(f"LOW clusters: {unique_low}")

Step 3: Identify Protocol

Based on timing patterns:

• **UART**: Consistent bit periods, durations are multiples of base period, idles HIGH
• **SPI/I2C**: us-scale timing, needs clock signal analysis, look for regular patterns
• **1-Wire**: Reset pulses ~480us, data pulses 1-120us

Step 4: Decode

Once protocol is identified, decode based on protocol rules. For unknown/custom protocols, analyze the timing clusters and