Logicmso

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 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 bit patterns to determine encoding scheme.

UART Decoding Example

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

f = read_file("uart_capture.bin")
chunk = f.contents.chunks[0]
times = np.array(chunk.transition_times)

BAUD = 115200
BIT_PERIOD = 1 / BAUD

def decode_uart_byte(start_time, times, bit_period):
    """Decode a single UART byte starting at start_time."""
    byte_val = 0
    for bit_num in range(8):
        # Sample at center of each bit (1.5, 2.5, 3.5... bit periods from start)
        sample_time = start_time + (1.5 + bit_num) * bit_period
        # Find state at sample_time
        idx = np.searchsorted(times, sample_time)
        state = (chunk.initial_state + idx) % 2
        if state:
            byte_val |= (1 << bit_num)  # LSB first
    return byte_val

# Find start bits (falling edges when idle HIGH)
decoded_bytes = []
i = 0
while i < len(times) - 1:
    # Look for falling edge (start bit)
    if chunk.initial_state == 1 or i > 0:
        byte_val = decode_uart_byte(times[i], times, BIT_PERIOD)
        decoded_bytes.append(byte_val)
        # Skip to next potential start bit (after stop bit)
        i += 1
        while i < len(times) and times[i] < times[i-1] + 10 * BIT_PERIOD:
            i += 1
    else:
        i += 1

print("Decoded:", bytes(decoded_bytes))

CTF Tips

1. Unknown protocol: Start with analyze_protocol.py --clusters to see timing distribution 2. Multiple channels: Export each channel separately, identify clock vs data lines 3. Inverted signals: Some captures have inverted logic levels 4. Timing variations: Real hardware has jitter, use threshold-based detection 5. Partial captures: Check if capture starts mid-transmission 6. Custom protocols: Look for repeating patterns, identify sync/framing bytes

Troubleshooting

"No module named 'saleae.mso_api'"

First verify it's truly missing:

python3 -c "from saleae.mso_api.binary_files import read_file"

Only if the import fails, install it:

pip install saleae-mso-api

Empty or corrupt file

Check file size and try re-exporting from Saleae Logic software.

No transitions detected

• Signal may be constant (stuck high/low)
• Check if correct channel was exported
• Verify trigger settings in original capture

Timing seems wrong

• Check sample rate matches original capture settings
• Verify time units (seconds vs milliseconds vs microseconds)

Logic MSO Analysis Examples

Example 1: Unknown Protocol Analysis

Scenario: You captured an unknown digital signal and need to identify the protocol.

Step 1: Get an overview

python3 skills/logicmso/analyze_protocol.py capture.bin

Step 2: Look at timing distribution

python3 skills/logicmso/analyze_protocol.py capture.bin --histogram --clusters

Step 3: Examine raw transitions

python3 skills/logicmso/analyze_protocol.py capture.bin --raw -n 50

Step 4: Export for external analysis

python3 skills/logicmso/analyze_protocol.py capture.bin --export transitions.csv

---

Example 2: UART Signal Analysis

Scenario: You suspect the signal is UART but need to determine the baud rate.

Identifying UART

Look for these characteristics:

• Signal idles HIGH
• Consistent bit periods
• Durations are multiples of the bit period

python3 skills/logicmso/analyze_protocol.py uart_capture.bin --clusters

If the analyzer suggests UART with a specific baud rate:

Protocol Guesses
----------------------------------------
  UART (115200 baud) (85% confidence)
    Bit period ~8.7us

Manual UART Decoding (Python)

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

f = read_file("uart_capture.bin")
chunk = f.contents.chunks[0]
times = np.array(chunk.transition_times)

BAUD = 115200
BIT_PERIOD = 1 / BAUD

def decode_uart_byte(start_time, times, bit_period):
    """Decode a single UART byte starting at start_time."""
    byte_val = 0
    for bit_num in range(8):
        sample_time = start_time + (1.5 + bit_num) * bit_period
        idx = np.searchsorted(times, sample_time)
        state = (chunk.initial_state + idx) % 2
        if state:
            byte_val |= (1 << bit_num)
    return byte_val

# Decode bytes from transitions...

---

Example 3: SPI Analysis

Scenario: Multi-channel SPI capture with clock and data lines.

Identifying SPI signals

• Look for a regular clock signal (SCLK)
• CS (chip select) goes LOW during transaction
• Data sampled on clock edges

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

# Load clock and data channels
clk_file = read_file("spi_clk.bin")
mosi_file = read_file("spi_mosi.bin")

clk_chunk = clk_file.contents.chunks[0]
mosi_chunk = mosi_file.contents.chunks[0]

clk_times = np.array(clk_chunk.transition_times)
mosi_times = np.array(mosi_chunk.transition_times)

# Find rising edges of clock (sample points for CPHA=0)
rising_edges = clk_times[0::2] if clk_chunk.initial_state == 0 else clk_times[1::2]

# Sample MOSI at each rising edge
def get_state_at_time(times, initial_state, t):
    idx = np.searchsorted(times, t)
    return (initial_state + idx) % 2

bits = [get_state_at_time(mosi_times, mosi_chunk.initial_state, t) for t in rising_edges]

# Group into bytes
bytes_out = []
for i in range(0, len(bits) - 7, 8):
    byte_val = sum(bits[i+j] << (7-j) for j in range(8))  # MSB first
    bytes_out.append(byte_val)

print("SPI data:", bytes(bytes_out))

---

Example 4: I2C Analysis

Scenario: Captured I2C SDA and SCL lines.

Identifying I2C

• Both lines idle HIGH
• START: SDA falls while SCL is HIGH
• STOP: SDA rises while SCL is HIGH
• 9 clock pulses per byte (8 data + ACK)

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

sda_file = read_file("i2c_sda.bin")
scl_file = read_file("i2c_scl.bin")

sda_chunk = sda_file.contents.chunks[0]
scl_chunk = scl_file.contents.chunks[0]

sda_times = np.array(sda_chunk.transition_times)
scl_times = np.array(scl_chunk.transition_times)

def get_state_at_time(times, initial_state, t):
    idx = np.searchsorted(times, t)
    return (initial_state + idx) % 2

# Find START conditions (SDA falls while SCL is HIGH)
starts = []
for i, t in enumerate(sda_times):
    if i % 2 == (0 if sda_chunk.initial_state == 1 else 1):  # Falling edge
        if get_state_at_time(scl_times, scl_chunk.initial_state, t) == 1:
            starts.append(t)

print(f"Found {len(starts)} I2C START conditions")

---

Example 5: 1-Wire Analysis

Scenario: Single-wire protocol (e.g., DS18B20 temperature sensor).

Identifying 1-Wire

• Single signal, idles HIGH
• Reset pulse: ~480us LOW
• Presence pulse: ~60-240us LOW response
• Data: short LOW pulses (1-15us = 1, 60-120us = 0)

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

f = read_file("onewire_capture.bin")
chunk = f.contents.chunks[0]
times = np.array(chunk.transition_times)
durations_us = np.diff(times) * 1e6

# Find reset pulses (long LOW periods)
low_idx = 1 if chunk.initial_state == 1 else 0
low_durations = durations_us[low_idx::2]

reset_pulses = [(i, d) for i, d in enumerate(low_durations) if d > 400]
print(f"Found {len(reset_pulses)} reset pulses")

# Decode data bits (after reset)
# Short LOW = 1, Long LOW = 0
data_bits = []
for d in low_durations:
    if 1 < d < 20:
        data_bits.append(1)
    elif 50 < d < 130:
        data_bits.append(0)

---

Python API Quick Reference

Load and inspect a capture

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

# Load file
f = read_file(Path("capture.bin"))
chunk = f.contents.chunks[0]

# Basic info
print(f"Sample rate: {chunk.sample_rate}")
print(f"Initial state: {chunk.initial_state}")
print(f"Transitions: {len(chunk.transition_times)}")

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

# Separate HIGH and LOW durations
if chunk.initial_state == 0:  # Starts LOW
    high_durations = durations_us[0::2]  # Even indices
    low_durations = durations_us[1::2]   # Odd indices
else:  # Starts HIGH
    high_durations = durations_us[1::2]  # Odd indices
    low_durations = durations_us[0::2]   # Even indices

Find unique timing values

# Round to nearest 10us and find unique values
unique_high = sorted(set(round(d, -1) for d in high_durations))
unique_low = sorted(set(round(d, -1) for d in low_durations))

print(f"HIGH pulse values: {unique_high}")
print(f"LOW gap values: {unique_low}")

Get signal state at a specific time

def get_state_at_time(times, initial_state, t):
    """Return signal state (0 or 1) at time t."""
    idx = np.searchsorted(times, t)
    return (initial_state + idx) % 2