tracekit 0.1.0

Signal analysis framework for oscilloscope and logic analyzer data

TraceKit

A comprehensive signal analysis framework for oscilloscope and logic analyzer data.

Features

Waveform Analysis

• Rise/fall time measurements (IEEE 181-2011)
• Period, frequency, duty cycle
• Amplitude measurements (Vpp, Vmax, Vmin, RMS)
• Overshoot/undershoot detection

Digital Analysis

• Threshold-based digital extraction
• Edge detection with sub-sample interpolation
• Clock recovery (FFT and edge-based methods)
• Glitch detection

Spectral Analysis

• FFT with configurable windowing
• Power Spectral Density (Welch method)
• THD, SNR, SINAD, ENOB calculations
• Spectrogram generation
• Wavelet transforms (CWT, DWT)

Protocol Decoding

• UART, SPI, I2C, CAN, CAN-FD
• 1-Wire, LIN, JTAG, SWD
• I2S, USB, HDLC
• Manchester encoding
• FlexRay, DMX512, SENT

Exploratory Analysis

• Unknown signal field detection and entropy analysis
• Legacy multi-family logic level detection
• Fuzzy pattern matching with Hamming distance tolerance
• Error-tolerant DAQ packet parsing and recovery

File Format Support

• Tektronix WFM/ISF
• Rigol WFM
• Sigrok/PulseView
• VCD (Value Change Dump)
• PCAP
• TDMS
• WAV
• CSV, HDF5, NPZ

Production Readiness

Current Version: v0.1.0 (Release Candidate)

TraceKit is a mature, fully-featured signal analysis framework currently in release candidate status. Version 1.0.0 release is pending final validation.

All Domains Production Ready

Domain	Status	Features
Core Analysis	100%	Waveform, timing, digital signal analysis
Spectral	100%	FFT, PSD, THD, harmonics, wavelets
Statistics	100%	Descriptive stats, distributions, correlation
Protocol Decoders	100%	16 protocols with auto-detection
Power Analysis	100%	IEEE 1459, IEC 61000-4-7 compliance
Data Loading	100%	Multi-format support (10+ formats)
Export	100%	CSV, JSON, VCD, WAV, Parquet, Excel, PowerPoint
Memory Management	100%	Chunked processing, streaming, caching, memory map
Logging	100%	Structured, rotation, compression, batch metrics
Reporting	100%	Templates, inheritance, multi-format export
Visualization	100%	Accessibility, interactive, specialized plots
Configuration	100%	Schema validation, migration, hot reload
Plugins	100%	Discovery, registration, sandboxed execution
Expert API	100%	Fluent interface, operators, DSL
Auto-Discovery	100%	Format detection, protocol inference
Exploratory	100%	Unknown signals, legacy analysis, fuzzy matching
Accessibility	100%	Colorblind-safe palettes, alt-text, keyboard nav

v1.0.0 Release Highlights

• 16 Protocol Decoders - UART, SPI, I2C, CAN, CAN-FD, 1-Wire, LIN, JTAG, SWD, I2S, USB, HDLC, Manchester, FlexRay, DMX512, SENT
• Exploratory Analysis - Unknown signal detection, legacy multi-family analysis, fuzzy pattern matching, error-tolerant DAQ
• Accessibility Features - Colorblind-safe visualization, alt-text generation, keyboard navigation
• Report Templates - 6 built-in templates with inheritance and customization
• Batch Metrics - Performance tracking with JSON/CSV export
• Time-based Logging - Rotation with compression and retention policies

Installation

# Using uv (recommended)
uv pip install tracekit

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

Quick Start

import tracekit as tk

# Load waveform data
trace = tk.load("oscilloscope_capture.wfm")

# Basic measurements
print(f"Rise time: {tk.rise_time(trace):.2e} s")
print(f"Frequency: {tk.frequency(trace):.2f} Hz")
print(f"Vpp: {tk.vpp(trace):.3f} V")

# Spectral analysis
spectrum = tk.fft(trace, window="hann")
thd = tk.thd(trace)
snr = tk.snr(trace)

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

# Visualization
tk.plot_waveform(trace)
tk.plot_spectrum(spectrum)
tk.plot_eye_diagram(trace)

Exploratory Analysis

from tracekit.exploratory import unknown, legacy, fuzzy

# Analyze unknown binary signal
result = unknown.detect_binary_fields(data)
print(f"Detected {len(result.fields)} fields")

# Multi-family logic level detection
families = legacy.detect_logic_families_multi_channel(channels)
for family in families:
    print(f"Channel {family.channel}: {family.logic_family}")

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

Time-based Log Rotation

from tracekit.core.logging import configure_logging

# Daily rotation with compression and 30-day retention
configure_logging(handlers={
    "file": {
        "filename": "analysis.log",
        "when": "midnight",
        "backup_count": 30,
        "compress": True,
        "max_age": "30d"
    }
})

Report Templates

from tracekit.reporting.template_system import (
    load_template, extend_template, register_template, TemplateSection
)

# Use built-in template
template = load_template("compliance")

# Create custom template
custom = extend_template(
    "compliance",
    name="FDA Compliance",
    add_sections=[TemplateSection(title="FDA Requirements", order=25)]
)
register_template("fda_compliance", custom)

Batch Job Metrics

from tracekit.batch.metrics import BatchMetrics

metrics = BatchMetrics(batch_id="analysis-001")
metrics.start()

for file in files:
    # ... process file ...
    metrics.record_file(file, duration=0.5, samples=100000)

metrics.finish()
summary = metrics.summary()
metrics.export_json("metrics.json")

Accessibility

from tracekit.visualization.accessibility import (
    get_colorblind_palette,
    generate_alt_text,
    KeyboardHandler
)

# Use colorblind-safe palette
palette = get_colorblind_palette("viridis")

# Generate alt-text for accessibility
alt_text = generate_alt_text(signal, "waveform", title="Clock Signal")

# Enable keyboard navigation
handler = KeyboardHandler(fig, ax)
handler.enable()

Development

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

# Run tests
uv run pytest

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

# Type check
uv run mypy src/

Testing

⚠️ IMPORTANT: If you encountered terminal crashes when running tests, this has been fixed! See docs/TESTING_CRASH_FIX.md for details.

TraceKit includes a comprehensive test suite:

• 16,690+ unit and integration tests
• IEEE/JEDEC compliance tests
• Performance benchmarks
• Full test coverage for all critical functionality

Running Tests

# Run all tests
uv run pytest tests/unit

# Run with coverage
uv run pytest tests/unit --cov=src/tracekit --cov-report=term

# Run in parallel (safe after fix)
uv run pytest tests/unit -n 4

See: docs/TESTING_GUIDELINES.md for comprehensive testing guide.

Standards Compliance

• IEEE 181-2011: Pulse measurements
• IEEE 1057-2017: Digitizer characterization
• IEEE 1241-2010: ADC testing
• IEEE 1149.1: JTAG
• IEEE 1459: Power measurements
• IEEE 2414-2020: Jitter measurements
• IEC 61000-4-7: Power quality
• JEDEC: Setup/hold timing
• RFC 3550: RTP packet timing

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! When contributing:

1. Follow the existing code style (use ruff format)
2. Include tests for all new functionality
3. Ensure all tests pass (pytest)
4. Add type hints and docstrings
5. Submit a pull request with a clear description