# pylecroy

**Repository Path**: osr-tech/pylecroy

## Basic Information

- **Project Name**: pylecroy
- **Description**: lecroy示波器python控制包
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-02-13
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pylecroy

`pylecroy` 是用于控制 LeCroy 示波器的 Python 包，底层通过 `pyvisa-py`、`pyvicp` 和 VICP 协议连接网络示波器。它适合远程配置通道、触发、采样率、水平时基，并拉取触发后的波形数据。

与 PicoScope 项目不同，LeCroy 仪器通常通过 IP 地址连接，因此没有本机 USB 枚举命令。使用前请确认示波器网络可达，并知道仪器 IP。

## 安装

```sh
pip install .
```

开发调试时可使用：

```sh
pip install -e .
```

安装后会提供 `pylecroy` 命令行工具：

```sh
pylecroy --help
```

## CLI

常用命令：

- `pylecroy info`：查看 CLI 支持的通道、耦合、带宽、采样率、水平时基和数据精度。
- `pylecroy plan`：根据预期电压、采集窗口、信号频率等目标建议垂直刻度、采样率和水平时基。
- `pylecroy idn --ip <address>`：通过 VICP 查询示波器 `*IDN?`。
- `pylecroy capture --ip <address>`：配置示波器并执行一次触发采集，默认输出 PNG 波形图，也可输出 NPZ/CSV 原始数据。

查看支持的设置：

```sh
pylecroy info --json
```

查询仪器身份：

```sh
pylecroy idn --ip 192.168.1.100
```

规划一次测量，例如 1.2 V 最大幅值、10 us 采集窗口、1 GSa/s：

```sh
pylecroy plan --max-abs-mv 1200 --duration-us 10 --sample-rate-hz 1e9 --json
```

采集 C1 并保存 PNG：

```sh
pylecroy capture --ip 192.168.1.100 --channel C1 --c1-vscale-mv 500 --sample-rate 1G --hscale 1us --trigger-source C1 --trigger-threshold-mv 500 --output capture.png
```

采集 C1/C2 并保存原始数据：

```sh
pylecroy capture --ip 192.168.1.100 --channel C1 --channel C2 --c1-vscale-mv 500 --c2-vscale-mv 200 --sample-rate 1G --hscale 1us --output capture.npz
```

在没有真实仪器或需要先确认配置时，使用 `--dry-run`。该模式只打印解析后的配置，不会连接示波器：

```sh
pylecroy capture --ip 192.168.1.100 --channel C1 --c1-vscale-mv 500 --sample-rate 1G --hscale 1us --dry-run
```

`capture` 常用参数：

- `--ip`：示波器 IP 地址。
- `--channel`：采集通道，可重复指定 `C1`、`C2`、`C3`、`C4`；默认 C1。
- `--c1-vscale-mv` 等：垂直刻度，单位 mV/div。
- `--c1-voffset-mv` 等：垂直偏置，单位 mV。
- `--c1-coupling` 等：耦合方式，支持 `DC50`、`DC1M`、`AC1M`。
- `--c1-bandwidth` 等：带宽限制，支持 `full`、`20MHz`、`200MHz`。
- `--trigger-source`：触发源，支持 `C1`、`C2`、`C3`、`C4`、`EXT`。
- `--trigger-threshold-mv`：触发电平，单位 mV。
- `--trigger-direction`：触发方向，支持 `positive`、`negative`，也接受 `rising`、`falling`。
- `--sample-rate`：采样率档位，例如 `1G`、`500M`、`SR_1G`。
- `--hscale`：水平时基，例如 `1us`、`1ms`、`HOR_1US`。
- `--hoffset-s`：水平偏移，单位秒。
- `--sequence`：Sequence 分段采集次数。
- `--precision`：波形传输精度，支持 `int8`、`int16`。
- `--format`：主输出格式，支持 `auto`、`png`、`npz`、`csv`。

当前 CLI 保存的是原始 ADC count。因为驱动没有读取 LeCroy 波形 preamble 缩放信息，PNG 主要用于判断波形形状、触发位置、削顶和采样窗口是否合适；如需精确电压换算，需要额外从仪器读取缩放参数。

## Python API

```python
from pylecroy import (
    LeCroyScope,
    CHANNEL,
    COUPLING,
    BANDWIDTH,
    SAMPLE_RATE,
    HOR_SCALE,
    TRIGGER_DIR,
)

scope = LeCroyScope("192.168.1.100")

scope.set_channel(
    channel=CHANNEL.C1,
    coupling=COUPLING.DC1M,
    vscale=500,
    voffset=0,
    bandwidth=BANDWIDTH.BW_FULL,
    view=True,
)

scope.set_trigger(
    source=CHANNEL.C1,
    threshold=500,
    direction=TRIGGER_DIR.POSSITIVE,
)

scope.set_acquire(
    sample_rate=SAMPLE_RATE.SR_1G,
    hscale=HOR_SCALE.HOR_1US,
    sequence=1,
)

scope.arm()

# 如果触发动作由程序完成，建议 arm 后等待约 0.3 s 再触发。
# time.sleep(0.3)
# perform_trigger_action()

data = scope.acquire(CHANNEL.C1)
scope.close()
```

## AI Agent Skill

项目内置 `skills/pylecroy-oscilloscope` skill，可用于指导 Codex/agent 选择垂直刻度、规划采样率和水平时基、执行 CLI 或 Python API 采集，并根据输出 PNG 判断采集质量。

## 许可

本项目仅供学习和科研使用。如需将本项目代码用于商业产品，请联系项目维护者获取商业许可。