|
| 1 | +# Sigrok Driver |
| 2 | + |
| 3 | +`jumpstarter-driver-sigrok` wraps `sigrok-cli` to provide logic analyzer and oscilloscope capture from Jumpstarter exporters. It supports: |
| 4 | +- **Logic analyzers** (digital channels) - with protocol decoding (SPI, I2C, UART, etc.) |
| 5 | +- **Oscilloscopes** (analog channels) - voltage waveform capture |
| 6 | +- One-shot and streaming capture |
| 7 | +- Decoder-friendly channel mappings |
| 8 | +- Real-time protocol decoding |
| 9 | + |
| 10 | +## Installation |
| 11 | + |
| 12 | +```shell |
| 13 | +pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-driver-sigrok |
| 14 | +``` |
| 15 | + |
| 16 | +## Configuration (exporter) |
| 17 | + |
| 18 | +```yaml |
| 19 | +export: |
| 20 | + sigrok: |
| 21 | + type: jumpstarter_driver_sigrok.driver.Sigrok |
| 22 | + driver: demo # sigrok driver (demo, fx2lafw, etc.) |
| 23 | + conn: null # optional: USB VID.PID or serial path |
| 24 | + executable: null # optional: path to sigrok-cli (auto-detected) |
| 25 | + channels: # channel mappings (device_name: semantic_name) |
| 26 | + D0: vcc |
| 27 | + D1: cs |
| 28 | + D2: miso |
| 29 | + D3: mosi |
| 30 | + D4: clk |
| 31 | + D5: sda |
| 32 | + D6: scl |
| 33 | +``` |
| 34 | +
|
| 35 | +## CaptureConfig (client-side) |
| 36 | +
|
| 37 | +```python |
| 38 | +from jumpstarter_driver_sigrok.common import CaptureConfig, DecoderConfig |
| 39 | + |
| 40 | +config = CaptureConfig( |
| 41 | + sample_rate="8MHz", |
| 42 | + samples=20000, |
| 43 | + pretrigger=5000, |
| 44 | + triggers={"cs": "falling"}, |
| 45 | + decoders=[ |
| 46 | + DecoderConfig( |
| 47 | + name="spi", |
| 48 | + channels={"clk": "clk", "mosi": "mosi", "miso": "miso", "cs": "cs"}, |
| 49 | + annotations=["mosi-data"], |
| 50 | + ) |
| 51 | + ], |
| 52 | +) |
| 53 | +``` |
| 54 | + |
| 55 | +This maps to: |
| 56 | +```bash |
| 57 | +sigrok-cli -d fx2lafw -c samplerate=8MHz,samples=20000,pretrigger=5000 --triggers D1=falling \ |
| 58 | + -P spi:clk=D4:mosi=D3:miso=D2:cs=D1 -A spi=mosi-data |
| 59 | +``` |
| 60 | + |
| 61 | +## Client API |
| 62 | + |
| 63 | +- `scan()` — list devices for the configured driver |
| 64 | +- `capture(config)` — one-shot capture, returns `CaptureResult` with base64 data |
| 65 | +- `capture_stream(config)` — streaming capture via `--continuous` |
| 66 | +- `get_driver_info()` — driver, conn, channel map |
| 67 | +- `get_channel_map()` — device-to-semantic name mappings |
| 68 | +- `list_output_formats()` — supported formats (csv, srzip, vcd, binary, bits, ascii) |
| 69 | + |
| 70 | +## Examples |
| 71 | + |
| 72 | +### Logic Analyzer (Digital Channels) |
| 73 | + |
| 74 | +One-shot with trigger: |
| 75 | +```bash |
| 76 | +sigrok-cli -d fx2lafw -c samplerate=8MHz,samples=20000,pretrigger=5000 --triggers D0=rising -o out.sr |
| 77 | +``` |
| 78 | + |
| 79 | +Real-time decode (SPI): |
| 80 | +```bash |
| 81 | +sigrok-cli -d fx2lafw -c samplerate=1M --continuous \ |
| 82 | + -P spi:clk=D4:mosi=D3:miso=D2:cs=D1 -A spi=mosi-data |
| 83 | +``` |
| 84 | + |
| 85 | +### Oscilloscope (Analog Channels) |
| 86 | + |
| 87 | +```yaml |
| 88 | +export: |
| 89 | + oscilloscope: |
| 90 | + type: jumpstarter_driver_sigrok.driver.Sigrok |
| 91 | + driver: rigol-ds # or demo for testing |
| 92 | + conn: usb # or serial path |
| 93 | + channels: |
| 94 | + A0: CH1 |
| 95 | + A1: CH2 |
| 96 | +``` |
| 97 | +
|
| 98 | +```python |
| 99 | +from jumpstarter_driver_sigrok.common import CaptureConfig |
| 100 | + |
| 101 | +# Capture analog waveforms |
| 102 | +config = CaptureConfig( |
| 103 | + sample_rate="1MHz", |
| 104 | + samples=10000, |
| 105 | + channels=["CH1", "CH2"], # Analog channels |
| 106 | + output_format="csv", # or "vcd" for waveform viewers |
| 107 | +) |
| 108 | +result = client.capture(config) |
| 109 | +waveform_data = result.data # bytes with voltage measurements |
| 110 | +``` |
0 commit comments