# atk-dl32-mcp

**English** | [ภาษาไทย](README.th.md)

MCP server and Python driver for the **ALIENTEK ATK-DL32** USB logic analyzer. It works without ATK-Logic: it talks to the device directly through a reverse-engineered USB protocol and decodes protocols offline with sigrok. An AI assistant such as Claude can capture, measure and decode signals.

## Features
- Capture all 16 channels (D0-D15) in stream mode at 1-100 MHz (verified)
- Selectable input threshold (1.8 V / 3.3 V / 5 V logic)
- Per-channel activity summary: edge count, high %, min/max pulse width
- Measure frequency, period, duty cycle and pulse-width statistics
- Decode any sigrok protocol (UART, I2C, SPI, CAN, 1-Wire, WS281x and more), including stacked decoders
- Fast built-in UART 8N1 decoder
- Captures are saved as `.sr` files that open in PulseView

## Tools
| Tool | Description |
|---|---|
| `dl32_info` | Connect and return device info (mode, MCU version, name, supported sample rates, threshold presets) |
| `dl32_capture` | Capture all 16 channels (sample rate, duration, threshold), save a `.sr` file and summarise activity per channel |
| `dl32_measure` | Frequency, period, duty cycle, high/low pulse widths and first edge times for one channel |
| `dl32_decode` | Run a sigrok protocol decoder (with optional stacked decoders) and return annotations with timestamps |
| `dl32_uart_text` | Fast built-in UART 8N1 decode of the latest capture, returned as text and hex |
| `dl32_list_decoders` | List available sigrok protocol decoders |
| `dl32_decoder_help` | Show a decoder's channels, options and annotation classes |

## Example prompts
- "Capture 0.5 s at 10 MHz and tell me which channels are active"
- "Decode I2C with SCL on D1 and SDA on D0"
- "Measure the PWM frequency and duty cycle on D3"
- "Read the UART text on D0 at 115200 baud"

## Requirements
- **Windows** only. The driver uses the Cypress `cyusb3` driver (VID `04B4` / PID `6A6A`), which is installed with ATK-Logic.
- Python 3.10+
- [sigrok-cli](https://sigrok.org/wiki/Downloads) for `dl32_decode`, `dl32_list_decoders` and `dl32_decoder_help`
- **Close ATK-Logic** before use: only one program can own the USB device.

## Install
```bash
pip install -r requirements.txt
```

## Run
```bash
python dl32_mcp.py
```

Environment variables:
| Variable | Description |
|---|---|
| `SIGROK_CLI` | Path to `sigrok-cli.exe` (default: `C:\tools\sigrok-cli\sigrok-cli.exe`) |

Captures are saved to `./captures`.

## Claude Code / Claude Desktop config
```json
{
  "mcpServers": {
    "dl32": {
      "command": "python",
      "args": ["C:/path/to/dl32_mcp.py"]
    }
  }
}
```

## Command-line tool
```bash
python dl32cap.py info
```
```bash
python dl32cap.py capture --rate 10M --time 0.2 --uart 0:115200 --save cap.npz
```

## Project layout
| Path | Description |
|---|---|
| `dl32_mcp.py` | MCP server |
| `dl32cap.py` | Command-line capture and analysis tool |
| `dl32/` | Driver: `transport` (cyusb3 bulk IOCTLs), `protocol` (packet framing, CRC), `device` (connect, capture), `decode` (edges, UART), `export` (`.sr` writer), `sigrok` (sigrok-cli wrapper) |
| `DL32_PROTOCOL.md` | USB protocol notes from reverse engineering |
| `cyusb_probe.py`, `test_*.py` | Low-level probe and test scripts used while developing the driver |
| `uart_gen/` | PlatformIO firmware for an ESP32-S3 that outputs a known UART pattern (115200 8N1 on GPIO8) for testing captures |

## Disclaimer
This is an unofficial project and is not affiliated with ALIENTEK. The protocol was worked out for interoperability; use at your own risk.

## License
MIT. See [LICENSE](LICENSE).