tracekit 0.2.0

Digital waveform and protocol reverse engineering toolkit with IEEE-compliant measurements

TraceKit

Digital waveform and protocol reverse engineering toolkit

TraceKit provides IEEE-compliant signal analysis, multi-protocol decoding, and protocol reverse engineering in a unified Python framework. Designed for engineers who need scriptable, automatable signal analysis with industry-standard accuracy.

---

Why TraceKit?

Challenge	TraceKit Solution
Unknown protocol on captured waveform	Protocol inference with automatic parameter detection
Analyzing proprietary bus protocols	State machine learning from captured traffic
Validating signal integrity	IEEE-compliant measurements (181, 1241, 2414)
Debugging embedded systems	16+ protocol decoders (UART, SPI, I2C, CAN, JTAG...)
EMC pre-compliance testing	CISPR/FCC limit mask testing with reports
Processing large captures	Streaming analysis and lazy loading

---

Key Capabilities

• Waveform Measurements - Rise/fall time, frequency, duty cycle, overshoot (IEEE 181-2011)
• Protocol Decoders - UART, SPI, I2C, CAN, CAN-FD, 1-Wire, LIN, JTAG, SWD, I2S, USB, HDLC, Manchester, FlexRay
• Spectral Analysis - FFT, PSD, THD, SNR, SINAD, ENOB, spectrograms, wavelets (IEEE 1241-2010)
• Signal Integrity - Jitter decomposition, eye diagrams, S-parameter analysis, TDR (IEEE 2414-2020)
• File Format Support - Tektronix WFM, Rigol, Sigrok, VCD, PCAP, TDMS, WAV, CSV, HDF5, Touchstone
• Power Analysis - AC/DC power, efficiency, ripple, SOA testing, power factor
• EMC Compliance - CISPR/FCC/CE limit mask testing with automated reporting

---

Quick Start

Installation

# Using uv (recommended)
uv pip install tracekit

# From source
git clone https://github.com/lair-click-bats/tracekit.git
cd tracekit
uv pip install -e ".[dev]"

Basic Usage

import tracekit as tk

# Load and measure
trace = tk.load("capture.wfm")
print(f"Rise time: {tk.rise_time(trace):.2e} s")
print(f"Frequency: {tk.frequency(trace):.2f} Hz")

# Spectral analysis
freq, mag = tk.fft(trace)
print(f"THD: {tk.thd(trace):.1f} dB")
print(f"SNR: {tk.snr(trace):.1f} dB")

# Protocol decoding
uart_packets = tk.decode_uart(trace, baudrate=115200)
spi_frames = tk.decode_spi(trace, clock_pin=0, mosi_pin=1)

# Filtering and math
filtered = tk.low_pass(trace, cutoff=1e6)
derivative = tk.differentiate(trace)

---

Core Features

Signal Measurements

IEEE-compliant measurements for characterization and validation:

# Amplitude measurements
vpp = tk.amplitude(trace)       # Peak-to-peak voltage
rms = tk.rms(trace)             # RMS value
mean = tk.mean(trace)           # DC offset

# Timing measurements (IEEE 181-2011)
rise = tk.rise_time(trace)      # 10-90% rise time
fall = tk.fall_time(trace)      # 90-10% fall time
freq = tk.frequency(trace)      # Signal frequency
duty = tk.duty_cycle(trace)     # Duty cycle percentage

# Signal quality
overshoot = tk.overshoot(trace)
undershoot = tk.undershoot(trace)

Protocol Decoding

Decode embedded protocols directly from captured waveforms:

# Serial protocols
uart = tk.decode_uart(trace, baudrate=115200)
spi = tk.decode_spi(trace, clock_pin=0, mosi_pin=1, miso_pin=2)
i2c = tk.decode_i2c(trace, scl_pin=0, sda_pin=1)

# Automotive protocols
can = tk.decode_can(trace, bitrate=500000)
can_fd = tk.decode_can_fd(trace, bitrate=500000, data_bitrate=2000000)
lin = tk.decode_lin(trace)

# Debug protocols
jtag = tk.decode_jtag(trace)
swd = tk.decode_swd(trace)

Spectral Analysis

Comprehensive frequency-domain analysis with IEEE 1241-2010 compliance:

# FFT and power spectral density
freq, magnitude = tk.fft(trace, window="hann")
freq, psd = tk.psd(trace, method="welch")

# ADC quality metrics
snr = tk.snr(trace)          # Signal-to-noise ratio
thd = tk.thd(trace)          # Total harmonic distortion
sinad = tk.sinad(trace)      # Signal-to-noise and distortion
enob = tk.enob(trace)        # Effective number of bits
sfdr = tk.sfdr(trace)        # Spurious-free dynamic range

# Time-frequency analysis
spectrogram = tk.spectrogram(trace)

Signal Filtering

Complete filter library with design tools:

# Convenience filters
filtered = tk.low_pass(trace, cutoff=1e6)
filtered = tk.high_pass(trace, cutoff=100)
filtered = tk.band_pass(trace, low=1e3, high=1e6)
filtered = tk.notch_filter(trace, center=60, q=30)  # Remove 60 Hz

# Filter design
filter_obj = tk.design_filter("butterworth", order=4, cutoff=1e6)

Power Analysis

Characterize power electronics and supplies:

# Power measurements
power = tk.instantaneous_power(v_trace, i_trace)
avg_power = tk.average_power(v_trace, i_trace)
energy = tk.energy(v_trace, i_trace, duration=1e-3)

# AC power
pf = tk.power_factor(v_trace, i_trace)
apparent = tk.apparent_power(v_trace, i_trace)
reactive = tk.reactive_power(v_trace, i_trace)

# Power supply analysis
ripple_pp, ripple_rms = tk.ripple(trace)
eff = tk.efficiency(v_in, i_in, v_out, i_out)

Signal Integrity

High-speed digital validation and characterization:

# Jitter measurements (IEEE 2414-2020)
from tracekit.analyzers import jitter
tie = jitter.calculate_tie(trace)
period_jitter = jitter.period_jitter(trace)
rj, dj = jitter.decompose_jitter(trace)

# Eye diagram
from tracekit.analyzers.eye import generate_eye_diagram
eye = generate_eye_diagram(trace, bit_rate=1e9)

# Component analysis
impedance = tk.extract_impedance(tdr_trace)
z0 = tk.characteristic_impedance(trace)
delay = tk.propagation_delay(trace)

---

Advanced Features

Exploratory Analysis

Analyze unknown or undocumented signals:

from tracekit.exploratory import unknown, fuzzy

# Detect binary field boundaries in data
fields = unknown.detect_binary_fields(data)

# Fuzzy pattern matching with bit errors
from tracekit.exploratory.sync import fuzzy_sync_search
matches = fuzzy_sync_search(data, pattern=0xAA55, max_errors=2)

Auto-Inference

Automatic signal classification and protocol detection:

# Classify signal type
signal_type = tk.classify_signal(trace)

# Detect protocol automatically
protocol = tk.detect_protocol(trace)
print(f"Detected: {protocol.name} (confidence: {protocol.confidence:.0%})")

# Get analysis recommendations
recommendations = tk.recommend_analyses(trace)

Streaming and Lazy Loading

Handle large files efficiently:

# Lazy loading for huge files
trace = tk.load("huge_capture.wfm", lazy=True)
print(f"Length: {len(trace)} samples")  # Metadata only, no data loaded

# Streaming analysis
for chunk in tk.load_trace_chunks("huge.wfm", chunk_size=1_000_000):
    process(chunk)

Pipelines

Compose analysis workflows functionally:

from tracekit import Pipeline, pipe

# Build reusable pipelines
analysis = Pipeline([
    tk.low_pass(cutoff=1e6),
    tk.rise_time,
    tk.frequency,
])

results = analysis(trace)

Session Management

Annotate and save analysis state:

session = tk.Session()
session.load_trace("capture.wfm")
session.annotate(time=1.5e-6, text="Glitch detected")
session.save("debug_session.tks")

---

File Format Support

Format	Extension	Description
Tektronix WFM	.wfm	Tektronix oscilloscopes
Rigol WFM	.wfm	Rigol oscilloscopes
Sigrok	.sr	Sigrok/PulseView captures
VCD	.vcd	Value Change Dump (digital)
PCAP	.pcap, .pcapng	Network packet captures
TDMS	.tdms	NI LabVIEW
WAV	.wav	Audio waveforms
Touchstone	.s1p, .s2p, etc.	S-parameter data
CSV	.csv	Generic time-series
HDF5	.h5, .hdf5	Scientific data format
NumPy	.npz	NumPy arrays

---

Reporting

Generate professional reports in multiple formats:

report = tk.generate_report(
    trace,
    measurements=["rise_time", "frequency", "thd"],
    format="html",  # or "pdf", "json"
)
report.save("analysis_report.html")

Built-in Templates: default, compliance, characterization, debug, production, comparison

---

EMC Compliance Testing

Test against regulatory limit masks:

# Check CISPR compliance
result = tk.check_compliance(
    spectrum,
    mask="CISPR22_ClassB",
    detector="quasi_peak"
)

# Generate compliance report
report = tk.generate_compliance_report(result, format="pdf")

Supported Standards: CISPR 22/32, FCC Part 15, MIL-STD-461

---

IEEE Standards Compliance

TraceKit implements measurements according to IEEE standards:

Standard	Domain	Measurements
IEEE 181-2011	Pulse measurements	Rise/fall time, slew rate
IEEE 1057-2017	Digitizer characterization	Timing analysis
IEEE 1241-2010	ADC testing	SNR, SINAD, ENOB, THD, SFDR
IEEE 2414-2020	Jitter measurements	TIE, period jitter, RJ/DJ
IEEE 1459	Power measurements	Power quality analysis
IEC 61000-4-7	Power quality	Harmonics analysis

---

Development

# Install with dev dependencies
uv sync

# Run tests
uv run pytest tests/unit -v

# Lint and format
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Type check
uv run mypy src/

See CONTRIBUTING.md for development guidelines.

---

Documentation

• API Reference - Complete API documentation
• Loading Waveforms - File format guide
• Testing Guide - Testing guidelines
• Examples - Working code examples

---

License

MIT License - See LICENSE for details.

---

Links

• Repository: github.com/lair-click-bats/tracekit
• Issues: github.com/lair-click-bats/tracekit/issues
• Changelog: CHANGELOG.md