sigrok: improve documentation

Author: mangelajo

packages/jumpstarter-driver-sigrok/README.md

@@ -1,11 +1,10 @@
 # Sigrok Driver
 
-`jumpstarter-driver-sigrok` wraps `sigrok-cli` to provide logic analyzer and oscilloscope capture from Jumpstarter exporters. It supports:
-- **Logic analyzers** (digital channels) - with protocol decoding (SPI, I2C, UART, etc.)
+`jumpstarter-driver-sigrok` wraps [sigrok-cli](https://sigrok.org/wiki/Sigrok-cli) to provide logic analyzer and oscilloscope capture from Jumpstarter exporters. It supports:
+- **Logic analyzers** (digital channels)
 - **Oscilloscopes** (analog channels) - voltage waveform capture
 - One-shot and streaming capture
-- Decoder-friendly channel mappings
-- Real-time protocol decoding
+- Multiple output formats with parsing (VCD, CSV, Bits, ASCII)
 
 ## Installation
 
@@ -19,44 +18,34 @@ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-d
 export:
   sigrok:
     type: jumpstarter_driver_sigrok.driver.Sigrok
-    driver: demo                        # sigrok driver (demo, fx2lafw, etc.)
-    conn: null                          # optional: USB VID.PID or serial path
-    executable: null                    # optional: path to sigrok-cli (auto-detected)
-    channels:                           # channel mappings (device_name: semantic_name)
-      D0: vcc
-      D1: cs
+    driver: fx2lafw                     # sigrok driver (demo, fx2lafw, rigol-ds, etc.)
+    conn: null                          # optional: USB VID.PID, serial path, or null for auto
+    channels:                           # optional: map device channels to friendly names
+      D0: clk
+      D1: mosi
       D2: miso
-      D3: mosi
-      D4: clk
-      D5: sda
-      D6: scl
+      D3: cs
 ```
 
-## CaptureConfig (client-side)
+### Configuration Parameters
 
-```python
-from jumpstarter_driver_sigrok.common import CaptureConfig, DecoderConfig
+| Parameter | Description | Type | Required | Default |
+|-----------|-------------|------|----------|---------|
+| `driver` | Sigrok driver name (e.g., `demo`, `fx2lafw`, `rigol-ds`) | str | yes | - |
+| `conn` | Connection string (USB VID.PID, serial path, or `null` for auto-detect) | str \| None | no | None |
+| `executable` | Path to `sigrok-cli` executable | str | no | Auto-detected from PATH |
+| `channels` | Channel mapping from device names (D0, A0) to semantic names (clk, voltage) | dict[str, str] | no | {} (empty) |
 
-config = CaptureConfig(
-    sample_rate="8MHz",
-    samples=20000,
-    pretrigger=5000,
-    triggers={"cs": "falling"},
-    decoders=[
-        DecoderConfig(
-            name="spi",
-            channels={"clk": "clk", "mosi": "mosi", "miso": "miso", "cs": "cs"},
-            annotations=["mosi-data"],
-        )
-    ],
-)
-```
+## CaptureConfig Parameters (client-side)
 
-This maps to:
-```bash
-sigrok-cli -d fx2lafw -c samplerate=8MHz,samples=20000,pretrigger=5000 --triggers D1=falling \
-  -P spi:clk=D4:mosi=D3:miso=D2:cs=D1 -A spi=mosi-data
-```
+| Parameter | Description | Type | Required | Default |
+|-----------|-------------|------|----------|---------|
+| `sample_rate` | Sampling rate (e.g., `"1M"`, `"8MHz"`, `"24000000"`) | str | no | "1M" |
+| `samples` | Number of samples to capture (`None` for continuous) | int \| None | no | None |
+| `pretrigger` | Number of samples to capture before trigger | int \| None | no | None |
+| `triggers` | Trigger conditions by channel name (e.g., `{"cs": "falling"}`) | dict[str, str] \| None | no | None |
+| `channels` | List of channel names to capture (overrides defaults) | list[str] \| None | no | None |
+| `output_format` | Output format (vcd, csv, bits, ascii, srzip, binary) | str | no | "vcd" |
 
 ## Client API
 
@@ -67,23 +56,107 @@ sigrok-cli -d fx2lafw -c samplerate=8MHz,samples=20000,pretrigger=5000 --trigger
 - `get_channel_map()` — device-to-semantic name mappings
 - `list_output_formats()` — supported formats (csv, srzip, vcd, binary, bits, ascii)
 
+## Output Formats
+
+The driver supports multiple output formats. **VCD (Value Change Dump) is the default** because:
+- ✅ **Efficient**: Only records signal changes (not every sample)
+- ✅ **Precise timing**: Includes exact timestamps in nanoseconds
+- ✅ **Widely supported**: Standard format for signal analysis tools
+- ✅ **Mixed signals**: Handles both digital and analog data
+
+### Available Formats
+
+| Format | Use Case | Decoded By |
+|--------|----------|------------|
+| `vcd` (default) | Change-based signals with timing | `result.decode()` → `list[Sample]` |
+| `csv` | All samples with timing | `result.decode()` → `list[Sample]` |
+| `bits` | Bit sequences by channel | `result.decode()` → `dict[str, list[int]]` |
+| `ascii` | ASCII art visualization | `result.decode()` → `str` |
+| `srzip` | Raw sigrok session (for PulseView) | `result.data` (raw bytes) |
+| `binary` | Raw binary data | `result.data` (raw bytes) |
+
+### Output Format Constants
+
+```python
+from jumpstarter_driver_sigrok.common import OutputFormat
+
+config = CaptureConfig(
+    sample_rate="1MHz",
+    samples=1000,
+    output_format=OutputFormat.VCD,  # or CSV, BITS, ASCII, SRZIP, BINARY
+)
+```
+
 ## Examples
 
-### Logic Analyzer (Digital Channels)
+### Example 1: Simple Capture (VCD format - default)
+
+**Python client code:**
+```python
+from jumpstarter_driver_sigrok.common import CaptureConfig
+
+# Capture with default VCD format (efficient, change-based with timing)
+config = CaptureConfig(
+    sample_rate="1MHz",
+    samples=1000,
+    channels=["D0", "D1", "D2"],  # Use device channel names or mapped names
+)
+result = client.capture(config)
 
-One-shot with trigger:
+# Decode VCD to get samples with timing
+samples = result.decode()  # list[Sample]
+for sample in samples[:5]:
+    print(f"Time: {sample.time_ns}ns, Values: {sample.values}")
+```
+
+**Equivalent sigrok-cli command:**
 ```bash
-sigrok-cli -d fx2lafw -c samplerate=8MHz,samples=20000,pretrigger=5000 --triggers D0=rising -o out.sr
+sigrok-cli -d fx2lafw -C D0,D1,D2 \
+  -c samplerate=1MHz --samples 1000 \
+  -O vcd -o /tmp/capture.vcd
 ```
 
-Real-time decode (SPI):
+---
+
+### Example 2: Triggered Capture with Pretrigger
+
+**Python client code:**
+```python
+from jumpstarter_driver_sigrok.common import CaptureConfig
+
+# Capture with trigger and pretrigger buffer (VCD format - default)
+config = CaptureConfig(
+    sample_rate="8MHz",
+    samples=20000,
+    pretrigger=5000,  # Capture 5000 samples before trigger
+    triggers={"D0": "rising"},  # Trigger on D0 rising edge
+    channels=["D0", "D1", "D2", "D3"],
+    # output_format defaults to VCD (efficient change-based format)
+)
+result = client.capture(config)
+
+# Decode to analyze signal changes with precise timing
+samples = result.decode()  # list[Sample] - only changes recorded
+print(f"Captured {len(samples)} signal changes")
+
+# Access timing and values
+for sample in samples[:3]:
+    print(f"Time: {sample.time_ns}ns, Changed: {sample.values}")
+```
+
+**Equivalent sigrok-cli command:**
 ```bash
-sigrok-cli -d fx2lafw -c samplerate=1M --continuous \
-  -P spi:clk=D4:mosi=D3:miso=D2:cs=D1 -A spi=mosi-data
+sigrok-cli -d fx2lafw -C D0,D1,D2,D3 \
+  -c samplerate=8MHz,samples=20000,pretrigger=5000 \
+  --triggers D0=rising \
+  -O vcd -o /tmp/capture.vcd
 ```
 
-### Oscilloscope (Analog Channels)
+---
 
+### Example 3: Oscilloscope (Analog Channels)
+
+**Exporter configuration:**
 ```yaml
 export:
   oscilloscope:
@@ -95,16 +168,60 @@ export:
       A1: CH2
 ```
 
+**Python client code:**
 ```python
-from jumpstarter_driver_sigrok.common import CaptureConfig
+from jumpstarter_driver_sigrok.common import CaptureConfig, OutputFormat
 
 # Capture analog waveforms
 config = CaptureConfig(
     sample_rate="1MHz",
     samples=10000,
     channels=["CH1", "CH2"],  # Analog channels
-    output_format="csv",  # or "vcd" for waveform viewers
+    output_format=OutputFormat.CSV,  # CSV for voltage values
 )
 result = client.capture(config)
-waveform_data = result.data  # bytes with voltage measurements
+
+# Parse voltage data
+samples = result.decode()  # list[Sample]
+for sample in samples[:5]:
+    print(f"Time: {sample.time_ns}ns")
+    print(f"  CH1: {sample.values.get('A0', 'N/A')}V")
+    print(f"  CH2: {sample.values.get('A1', 'N/A')}V")
+```
+
+**Equivalent sigrok-cli command:**
+```bash
+sigrok-cli -d rigol-ds:conn=usb -C A0=CH1,A1=CH2 \
+  -c samplerate=1MHz --samples 10000 \
+  -O csv -o /tmp/capture.csv
+```
+
+---
+
+### Example 4: Bits Format (Simple Bit Sequences)
+
+**Python client code:**
+```python
+from jumpstarter_driver_sigrok.common import CaptureConfig, OutputFormat
+
+# Capture in bits format (useful for visual inspection)
+config = CaptureConfig(
+    sample_rate="100kHz",
+    samples=100,
+    channels=["D0", "D1", "D2"],
+    output_format=OutputFormat.BITS,
+)
+result = client.capture(config)
+
+# Get bit sequences per channel
+bits_by_channel = result.decode()  # dict[str, list[int]]
+for channel, bits in bits_by_channel.items():
+    print(f"{channel}: {''.join(map(str, bits[:20]))}")  # First 20 bits
+```
+
+**Equivalent sigrok-cli command:**
+```bash
+sigrok-cli -d demo -C D0,D1,D2 \
+  -c samplerate=100kHz --samples 100 \
+  -O bits -o /tmp/capture.bits
 ```

packages/jumpstarter-driver-sigrok/jumpstarter_driver_sigrok/common.py

@@ -43,8 +43,9 @@ class CaptureConfig(BaseModel):
     triggers: dict[str, str] | None = Field(default=None, description="e.g., {'D0': 'rising'}")
     channels: list[str] | None = Field(default=None, description="override default channels by name")
     output_format: str = Field(
-        default="srzip",
-        description="csv, srzip, vcd, binary, bits, ascii",
+        default=OutputFormat.VCD,
+        description="Output format (default: vcd - efficient change-based format with timing). "
+        "Options: vcd, csv, srzip, binary, bits, ascii",
     )
     decoders: list[DecoderConfig] | None = Field(default=None, description="real-time protocol decoding")
 

packages/jumpstarter-driver-sigrok/jumpstarter_driver_sigrok/driver.py

@@ -19,20 +19,14 @@ def find_sigrok_cli() -> str:
     return executable
 
 
-def _default_channel_map() -> dict[str, str]:
-    # Decoder-friendly default names for demo driver
-    # Maps device channel name -> semantic name
-    return {"D0": "vcc", "D1": "cs", "D2": "miso", "D3": "mosi", "D4": "clk", "D5": "sda", "D6": "scl"}
-
-
 @dataclass(kw_only=True)
 class Sigrok(Driver):
     """Sigrok driver wrapping sigrok-cli for logic analyzer and oscilloscope support."""
 
     driver: str = "demo"
     conn: str | None = None
     executable: str = field(default_factory=find_sigrok_cli)
-    channels: dict[str, str] = field(default_factory=_default_channel_map)
+    channels: dict[str, str] = field(default_factory=dict)
 
     def __post_init__(self):
         if hasattr(super(), "__post_init__"):

packages/jumpstarter-driver-sigrok/jumpstarter_driver_sigrok/driver_test.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from .common import CaptureConfig, CaptureResult
+from .common import CaptureConfig, CaptureResult, OutputFormat
 from .driver import Sigrok
 from jumpstarter.common.utils import serve
 
@@ -68,6 +68,43 @@ def test_capture_with_demo_driver(demo_client):
     assert len(result.channel_map) > 0
 
 
+@pytest.mark.skipif(which("sigrok-cli") is None, reason="sigrok-cli not installed")
+def test_capture_default_format(demo_client):
+    """Test capture with default output format (VCD).
+
+    VCD is the default because it's the most efficient format:
+    - Only records changes (not every sample)
+    - Includes precise timing information
+    - Widely supported by signal analysis tools
+    """
+    # Don't specify output_format - should default to VCD
+    cfg = CaptureConfig(
+        sample_rate="100kHz",
+        samples=50,
+        channels=["D0", "D1", "D2"],
+    )
+
+    result = demo_client.capture(cfg)
+
+    # Verify we got VCD format by default
+    assert isinstance(result, CaptureResult)
+    assert result.output_format == OutputFormat.VCD
+    assert isinstance(result.data, bytes)
+    assert len(result.data) > 0
+
+    # Verify VCD data can be decoded
+    samples = result.decode()
+    assert isinstance(samples, list)
+    assert len(samples) > 0
+
+    # Verify samples have timing information (VCD feature)
+    for sample in samples:
+        assert hasattr(sample, "time_ns")
+        assert isinstance(sample.time_ns, int)
+        assert hasattr(sample, "values")
+        assert isinstance(sample.values, dict)
+
+
 @pytest.mark.skipif(which("sigrok-cli") is None, reason="sigrok-cli not installed")
 def test_capture_csv_format(demo_client):
     """Test capture with CSV output format via client."""
@@ -297,6 +334,7 @@ def test_decode_bits_format(demo_client):
     Verifies:
     - Bits format decoding works
     - Returns dict with bit sequences
+    - Channel names are mapped from device names (D0) to user-friendly names (vcc)
     """
     from .common import OutputFormat
 
@@ -314,11 +352,19 @@ def test_decode_bits_format(demo_client):
     assert isinstance(decoded, dict)
     assert len(decoded) > 0
 
+    # Should have user-friendly channel names (vcc, cs, miso) from channel_map
+    # Not generic names like CH0, CH1
+    assert "vcc" in decoded or "D0" in decoded
+    assert "cs" in decoded or "D1" in decoded
+    assert "miso" in decoded or "D2" in decoded
+
     # Each channel should have a list of bits
     for channel, bits in decoded.items():
         assert isinstance(channel, str)
         assert isinstance(bits, list)
         assert all(b in [0, 1] for b in bits)
+        # Should have bits (at least some, exact count may vary with demo driver timing)
+        assert len(bits) > 0
 
 
 @pytest.mark.skipif(which("sigrok-cli") is None, reason="sigrok-cli not installed")