Metadata-Version: 2.4
Name: tracekit
Version: 0.1.1
Summary: Digital waveform and protocol reverse engineering toolkit with IEEE-compliant measurements
Project-URL: Homepage, https://github.com/lair-click-bats/tracekit
Project-URL: Documentation, https://github.com/lair-click-bats/tracekit/tree/main/docs
Project-URL: Repository, https://github.com/lair-click-bats/tracekit
Project-URL: Changelog, https://github.com/lair-click-bats/tracekit/blob/main/CHANGELOG.md
Project-URL: Issue Tracker, https://github.com/lair-click-bats/tracekit/issues
Project-URL: Discussions, https://github.com/lair-click-bats/tracekit/discussions
License-Expression: MIT
License-File: LICENSE
Keywords: automotive,can,cispr,embedded-systems,emc-testing,eye-diagram,flexray,hardware-debugging,i2c,ieee-1241,ieee-181,ieee-2414,jitter-analysis,jtag,lin,logic-analyzer,oscilloscope,protocol-decoder,protocol-inference,reverse-engineering,signal-analysis,signal-integrity,spectral-analysis,spi,state-machine-learning,swd,uart,waveform-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: System :: Hardware
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: bokeh>=3.8.1
Requires-Dist: click>=8.1.0
Requires-Dist: jinja2>=3.1
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: plotly>=6.5.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.4.7
Requires-Dist: scapy>=2.6.1
Requires-Dist: scipy>=1.10.0
Requires-Dist: tm-data-types>=0.3.0
Provides-Extra: all
Requires-Dist: check-jsonschema>=0.29.0; extra == 'all'
Requires-Dist: h5py>=3.0.0; extra == 'all'
Requires-Dist: interrogate>=1.7.0; extra == 'all'
Requires-Dist: ipython>=8.0.0; extra == 'all'
Requires-Dist: jupyter>=1.0.0; extra == 'all'
Requires-Dist: pytest-cov>=6.0; extra == 'all'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: python-pptx>=0.6.21; extra == 'all'
Requires-Dist: reportlab>=4.0.0; extra == 'all'
Requires-Dist: types-pyyaml>=6.0; extra == 'all'
Requires-Dist: yamllint>=1.35; extra == 'all'
Provides-Extra: dev
Requires-Dist: check-jsonschema>=0.29.0; extra == 'dev'
Requires-Dist: interrogate>=1.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: yamllint>=1.35; extra == 'dev'
Provides-Extra: hdf5
Requires-Dist: h5py>=3.0.0; extra == 'hdf5'
Provides-Extra: jupyter
Requires-Dist: ipython>=8.0.0; extra == 'jupyter'
Requires-Dist: jupyter>=1.0.0; extra == 'jupyter'
Provides-Extra: reporting
Requires-Dist: python-pptx>=0.6.21; extra == 'reporting'
Requires-Dist: reportlab>=4.0.0; extra == 'reporting'
Description-Content-Type: text/markdown

# TraceKit

[![Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Flair-click-bats%2Ftracekit%2Fmain%2Fpyproject.toml&query=%24.project.version&label=version&color=blue)](https://github.com/lair-click-bats/tracekit/releases)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![IEEE](https://img.shields.io/badge/IEEE-compliant-informational.svg)](docs/)

**Python signal analysis toolkit for oscilloscope and logic analyzer data**

TraceKit provides IEEE-compliant waveform analysis, protocol decoding, and spectral measurements in a single unified framework. Designed for engineers who need scriptable, automatable signal analysis with industry-standard accuracy.

---

## 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

```bash
# 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

```python
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:

```python
# 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:

```python
# 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:

```python
# 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:

```python
# 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:

```python
# 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:

```python
# 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:

```python
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:

```python
# 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:

```python
# 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:

```python
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:

```python
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:

```python
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:

```python
# 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

```bash
# 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](CONTRIBUTING.md) for development guidelines.

---

## Documentation

- **[API Reference](docs/api/index.md)** - Complete API documentation
- **[Loading Waveforms](docs/guides/loading-waveforms.md)** - File format guide
- **[Testing Guide](docs/testing/index.md)** - Testing guidelines
- **[Examples](examples/)** - Working code examples

---

## License

MIT License - See [LICENSE](LICENSE) for details.

---

## Links

- **Repository**: [github.com/lair-click-bats/tracekit](https://github.com/lair-click-bats/tracekit)
- **Issues**: [github.com/lair-click-bats/tracekit/issues](https://github.com/lair-click-bats/tracekit/issues)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
