Content
# siglent-sds-mcp
MCP server for controlling a SIGLENT SDS824X HD oscilloscope via SCPI over raw TCP.
**Project status**: SDS824X HD hardware-tested alpha. Core measurement-driven auto setup is functional on real hardware.
## Quick start
```bash
# Install
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
# Test
pytest -q
# Run MCP server (stdio, for AI client config)
python -m siglent_sds_mcp.server
# Quick connectivity probe
python examples/tcp_idn_test.py <scope-ip>
```
## Auto setup — one-command screen setup
The main feature: point at an unknown signal and let the scope measurement engine find usable VDIV / OFST / TDIV settings. The command also saves a screenshot artifact from the final setup path.
```bash
# Backwards-compatible CLI name; internally uses measurement-driven auto setup
python examples/auto_find_waveform_tcp.py <scope-ip> --channels C1 C2 C3 C4
# With signal-type hint for better trigger slope policy
python examples/auto_find_waveform_tcp.py <scope-ip> --signal-hint uart
# Direct TTL wiring / 1X probe
python examples/auto_find_waveform_tcp.py <scope-ip> \
--channels C1 \
--signal-hint clock \
--probe 1
# Weak periodic signal policy
python examples/auto_find_waveform_tcp.py <scope-ip> \
--channels C1 \
--signal-hint clock \
--noise-floor 0.05 \
--min-signal-vpp 0.005
# Restart acquisition after capture only when explicitly requested
python examples/auto_find_waveform_tcp.py <scope-ip> --restart-after-capture
```
Default behavior: `leave_stopped=true`. The tool intentionally leaves the scope stopped on the final visible frame. The return object includes `screen_hold`, `final_panel_state`, `measurements`, `final_settings`, `probe_steps`, `screenshot`, and `compatibility_parameters`.
Compatibility note: `coarse_timebase`, `initial_vdiv`, `max_points`, and `refine_attempts` are accepted by the historical `auto_find_waveform` API so older MCP/CLI callers do not break. The current measurement-driven adapter path owns the actual scanning and refinement logic, so those compatibility fields are reported in JSON but are not directly used by the measurement path.
## Waveform capture modes
`get_waveform_tcp` defaults to `capture_mode="immediate"`.
```text
STOP -> WF? DAT2
```
This intentionally skips `WFSU`. SDS824X HD field debugging showed that sending `WFSU SP,1,NP,0,FP,0` after STOP can refresh/replace the stopped frame before `WF? DAT2`, which loses intermittent UART/RS485 bursts and often returns an IDLE frame instead.
For stable/repetitive signals only, callers may request the legacy configured path:
```text
STOP -> WFSU SP,1,NP,0,FP,0 -> WF? DAT2
```
Use it through MCP by setting:
```json
{
"capture_mode": "configured"
}
```
The metadata records `capture.mode`, `capture.wfsu_sent`, `decode.dt_source`, `parsed.trdl_s`, `parsed.effective_start_s`, `parsed.effective_end_s`, and warnings when fallback timing is used.
## UART decoding
`analyze_uart_csv_file` now performs real UART 8N1 byte decoding instead of only reporting edge timing. It detects falling-edge start bits, samples 8 data bits LSB-first, validates the stop bit, and returns decoded bytes:
```json
{
"decoded_hex": "48 69",
"decoded_ascii": "Hi",
"frames": [
{"byte_hex": "0x48", "stop_ok": true, "framing_ok": true}
]
}
```
Thresholding is histogram-based when two voltage levels are visible, with min/max midpoint fallback. This is more robust for small-amplitude UART such as high=5.2 V and low=4.95 V, where simple min/max Vpp rules are too brittle.
## Architecture
```
MCP client (AI)
│ MCP tool calls (stdio)
▼
server.py — FastMCP tools, auto-reconnect
│
▼
sds_tcp_adapter.py — SDS800X HD command adapter
│ channel / acquisition / trigger / measure / screenshot /
│ waveform capture (WAVEDESC adaptive decode + envelope decimation) /
│ measurement-driven auto_setup
▼
waveform_capture.py — immediate/configured WF? DAT2 capture modes
│ immediate mode preserves stopped frames by skipping WFSU
▼
tcp_transport.py — RawTcpTransport
│ socket-level SCPI, IEEE 488.2 binary block parser,
│ thread-safe (RLock), pre-query socket flush
▼
auto_setup.py — compatibility wrapper for historical auto_find_waveform API
SIGLENT SDS824X HD oscilloscope (LAN port 5025)
```
## Command verification pipeline
```
candidate → official-doc → tested → implemented → safe-tool
```
Tracked in `docs/sds824x-hd-command-matrix.md`. Do NOT expose an untested command as a default MCP tool.
## Key design decisions
### Measurement-driven auto setup
`SDS800XHDTcpAdapter.auto_setup()` uses scope measurements (`PKPK`, `MEAN`, `FREQ`, `PER`, `MAX`, `MIN`) to select display settings. This avoids relying on a separate offline CSV analyzer for first-pass screen setup.
### Weak periodic signal policy
`noise_floor_v` is treated as the strong-signal threshold. A lower-amplitude signal can still be accepted when the scope reports a valid `FREQ` or `PER` and `PKPK >= min_signal_vpp`. This handles real field observations such as a stable 7.89 kHz signal with only about 22.5 mV peak-to-peak.
### WAVEDESC adaptive decode
`WF? DAT2` returns 8-bit signed bytes. Voltage decode queries `WF? DESC` for the WAVEDESC descriptor and uses the descriptor-derived `codes_per_div` with current panel `VDIV? / OFST?` for decoding.
### Timebase and dt policy
DAT2 timing should use WAVEDESC `HORIZ_INTERVAL` whenever available. `SARA?` is recorded as metadata and only used as a fallback. Metadata warnings are emitted when `dt_source` falls back to SARA or TDIV because UART/protocol decoding can be wrong if the fallback does not match the DAT2 memory interval.
### Min/max envelope decimation
When `max_points` < raw sample count, each bucket outputs min + max voltages instead of naive stride-sampling. Preserves glitches/spikes stride would miss.
### ARM/STOP behaviour
`get_waveform_tcp` immediate mode freezes the current frame with STOP and reads DAT2 directly. This is the default for intermittent signals. The older WFSU path is available only through `capture_mode="configured"`.
### Trigger level policy
`C?:TRLV <level>` is a known issue on SDS824X HD firmware `4.8.12.1.1.6.5`. Display-oriented auto setup does not depend on this command by default. `set_trigger_level=true` must be requested explicitly.
## Project structure
```
src/siglent_sds_mcp/
server.py — MCP tools, auto-reconnect, FastMCP
sds_tcp_adapter.py — Command adapter, WAVEDESC decode, envelope, auto_setup
waveform_capture.py — WF? DAT2 capture modes, immediate skips WFSU
tcp_transport.py — Raw TCP socket, lock, binary block parser
auto_setup.py — Compatibility wrapper for auto_find_waveform API
uart_analyzer.py — Offline UART CSV analyzer and 8N1 byte decoder
rs485_analyzer.py — RS485 differential pair analyzer
modbus_timing.py — Modbus RTU timing calculator
report.py — Markdown field report generator
artifacts.py — Timestamped artifact paths, JSON writer
transport.py — PyVISA fallback (legacy, not wired into MCP)
scope_driver.py — SiglentSDSDriver with safety gate (legacy)
docs/
architecture.md — Layered design, UART capture reference
sds824x-hd-command-matrix.md — Per-command verification status
sds824x-hd-knowledge-base.md — Instrument-specific knowledge
verification-workflow.md — Hardware verification procedure
tests/ — pytest, parser tests, TCP transport tests, auto setup helper tests
examples/ — auto_find_waveform_tcp, TCP IDN probe, waveform/RS485 capture
```
## Safety model
| Allowed | Blocked |
|---------|---------|
| `*IDN?`, run/stop/single | `*RST`, factory reset |
| Channel/timebase/trigger setup | Firmware update |
| Measurement query | Network config changes |
| Screenshot/waveform fetch | File deletion/formatting |
| Offline waveform analysis | Arbitrary SCPI writes |
Raw SCPI writes are NOT exposed as MCP tools. `safe_scpi_query_tcp` only accepts `?`-suffixed commands.
## Test coverage
```bash
pytest -q
```
Key test areas:
- `test_unit_parsing.py` — `_parse_voltage`, `_parse_time`, `_parse_sample_rate`
- `test_wavedesc.py` / `test_wavedesc_parser.py` — synthetic WAVEDESC decode, ASCII prefix handling
- `test_tcp_binary_prefix.py` — `query_binary` IEEE 488.2 / BMP prefix skipping
- `test_auto_setup.py` — `_pick_vdiv`, `_pick_tdiv`, measurement parser and SCPI number formatting
- `test_auto_find_compat.py` — weak periodic detection, screen hold, screenshot artifact, compatibility parameters
- `test_waveform_capture_modes.py` — immediate mode skips WFSU; configured mode sends WFSU with warning
- `test_uart_decoder.py` — UART 8N1 byte decoding, hex/ascii output, low-Vpp thresholding
- `test_tcp_transport_parser.py` — socketpair binary block parsing
## Target device
- **SIGLENT SDS824X HD** / SDS800X HD family
- SCPI over raw TCP, port 5025
- Firmware verified: 4.8.12.1.1.6.5
## Reference
- `MagnusJohansson/siglent-sds-mcp` — upstream SIGLENT SDS MCP reference (SDS1104X-E class)
- [`docs/upstream-reference.md`](docs/upstream-reference.md)
