示波器

从一个 cargo test 里驱动示波器：设置它的通道、时基和触发，控制采集，并读取测量值。它适用于 Rigol MSO5000 和 PicoScope Net，需要 Box 软件 0.55.0 或更高版本。

句柄

use lager::LagerBox;

let lager = LagerBox::from_env()?;
let ch1 = lager.scope("scope1-ch1");

示波器在 Box 上保存为两种 Net：

一个代表仪器本身的 scope Net
每个输入各一个 scope-channel Net

lager.scope(name) 接受这两种中的任意一种。通道设置和测量需要通道 Net。其余一切都属于仪器本身，通过任意一种 Net 都可以使用。

方法

方法	Net	说明
`name()`	任意	该句柄所指向的 Net 名称
`enable()`, `disable()`, `is_enabled()`	通道	打开或关闭该通道，或者读回其状态
`set_scale()`, `scale()`	通道	垂直刻度（V/div）
`set_coupling()`, `coupling()`	通道	输入耦合（`"dc"`、`"ac"`；Rigol 还接受 `"gnd"`）
`set_probe()`, `probe()`	通道	探头衰减（1 表示 1x，10 表示 10x）
`set_offset()`, `offset()`	通道	垂直偏移（V）
`measure()`	通道	一项测量
`measure_all()`	通道	来自同一次采集的全部测量
`set_timebase()`, `timebase()`	任意	时基（s/div）
`set_time_offset()`, `time_offset()`	任意	采集窗口相对于触发点的位置（s）
`trigger_edge()`	任意	配置边沿触发
`trigger()`	任意	读回触发设置
`run()`, `single()`, `stop()`	任意	连续采集、单次采集或停止
`force_trigger()`	任意	立即触发
`autoscale()`	任意	由仪器自行选择刻度、时基和触发
`capabilities()`	任意	仪器的通道、限值和可选功能
`state()`	任意	在一个请求中读取全部控制设置
`capture_mode()`、`trigger_source()`、`trigger_slope()`、`trigger_level()`	任意	读取某一项触发设置
`set_trigger_holdoff()`、`trigger_holdoff()`	任意	触发释抑时间（秒）
`set_acquisition()`、`acquisition()`	任意	普通、平均或峰值采集
`set_roll()`、`roll()`	任意	滚动模式
`set_display()`、`display()`	任意	余辉、XY、缩放、数学波形和 FFT 窗格
`fft()`	任意	某个通道最强的频谱峰值
`set_cursors()`、`cursors()`、`clear_cursors()`	任意	设置、读取或清除光标
`measure_cursors()`	任意	读取光标的位置及它们之间的差值
`capture()`、`capture_timeout()`	任意	最新一次采集的样本（feature `scope-trace`）
`stream()`	任意	从现在起的每一次采集（feature `scope-trace`）
`command()`	任意	任何其他示波器操作，参数为原始 JSON

类型

`Measurement`

pub enum Measurement {
    Vpp, Vmax, Vmin, Vrms, Vavg,
    Period, Frequency,
    DutyCyclePositive, DutyCycleNegative,
    PulseWidthPositive, PulseWidthNegative,
    RiseTime, FallTime, Overshoot,
}

电压以伏特为单位，时间以秒为单位，频率以赫兹为单位，占空比和过冲以百分比表示。

`EdgeTrigger`

pub struct EdgeTrigger {
    pub source: Option<String>,   // as the instrument names it: "CHAN1", "A"
    pub slope: Option<String>,    // "rising", "falling", ...
    pub coupling: Option<String>, // the trigger path's filter, not the input coupling
    pub level: Option<f64>,       // volts
    pub mode: Option<TriggerMode>,
}

pub enum TriggerMode { Auto, Normal, Single }

`TriggerSettings` 和 `Measurements`

trigger() 返回一个 TriggerSettings，其中包含 mode、source、slope、level，以及示波器报告时的 holdoff。每个字段都是 Option，采用仪器自己的写法。 measure_all() 返回一个 Measurements，每个量各有一个 Option<f64> 字段。Measurements::get(Measurement) 读取其中一个。

`ScopeCapture`

capture() 和 ScopeStream::next_capture() 返回一次采集：

项	说明
`seq`	采集的序列号
`sample_interval_ns`	样本之间的时间间隔（纳秒）
`pre_trigger_samples`、`post_trigger_samples`	触发之前和之后的样本数
`samples_per_channel`	每个通道的样本数
`channels`	每个通道一个 `TraceChannel`：`label`、`coupling`、`scale_v_per_count`、`offset_v`
`volts('A')`	某个通道以伏特为单位的样本
`counts('A')`	某个通道的原始样本
`time_axis()`	每个样本的时间，以距触发点的秒数表示
`triggered()`	这次采集是否来自触发
`overflowed('A')`	该通道是否超量程
`sample_rate_hz()`、`duration_s()`	这次采集的采样率和时长
`streaming()`	这次采集是否来自滚动串流，而不是一个数据块
`is_envelope()`	采样点是否为（最小值，最大值）对，即滚动模式发送的格式
`channel_index('A')`	某个通道在 `channels` 中的位置，或 `None`
`ScopeCapture::decode(&[u8])`	解码一个原始 LSCP/1 帧。帧有误时以 `Error::Decode` 失败。不需要任何 feature

对于不在这次采集中的通道，volts() 和 counts() 返回 None。

控制设置与结果

带类型的控制方法接受并返回以下类型。输入结构体 DisplaySettings、FftOptions 和 CursorSettings 实现了 Default：设置所需字段，其余用 ..Default::default() 补齐。

类型	内容
`AcquisitionMode`	`Normal`、`Average`、`Peak`
`Acquisition`	`mode`、`average_count`
`RollMode`	`Auto`、`On`、`Off`
`Roll`	`roll`（设置值）、`rolling`（示波器当前是否在滚动）
`DisplaySettings`	`persistence`（`Persistence::Off`、`Seconds(f64)`、`Infinite`）、`xy`、`zoom`（`Zoom::Off`、`Around { factor, center }`）、`math`（`MathTrace::Off`、`Expr("a-b")`）、`fft`（`FftPane::Off`、`On { channel, window }`）。只有设置了的字段会改变
`FftOptions`	`channel`、`window`（`FftWindow::Hann`、`Hamming`、`Blackman`、`Flattop`、`Rectangular`）、`peaks`
`Spectrum`	`channel`、`window`、`sample_rate_hz`、`resolution_hz`、`samples`、`peaks`（每项为 `SpectralPeak`：`frequency_hz`、`vrms`、`dbv`）
`CursorSettings`	`time: Option<(f64, f64)>`、`volts: Option<(f64, f64)>`、`channel`
`Cursors`	放置在 Box 上的 `time`、`volts`、`channel`
`CursorMeasurement`	`cursors`，以及 `readings`（`CursorReadings`：`delta_t`、`frequency`、`window_start`、`window_end`、`trace_delta_v`、`delta_v` 等）
`ScopeCapabilities`	`family`、`model`、`serial`、`analog_channels`、`channel_labels`、`max_sample_rate_hz`、`max_memory_samples`、`bandwidth_hz`、`roll_mode`、`peak_detect`、`advanced_triggers`、`extra`
`ScopeState`	`version`、`acquiring`、`rolling`、`capture_mode`、`trigger`、`timebase`、`acquisition`、`channels`、`display`、`live_view_problem`

方法参考

`measure(m: Measurement) -> Result<Option<f64>>`

从该通道读取一个量。

use lager::Measurement;

match ch1.measure(Measurement::Frequency)? {
    Some(hz) => println!("{hz} Hz"),
    None => println!("no frequency in this capture"),
}

返回： 当采集中不包含该量时返回 None。例如，直流电平没有周期。这是一个答案，而不是错误。

`measure_all() -> Result<Measurements>`

读取该次采集支持的每一个量。每次 measure() 调用都会进行自己的采集，因此对于实时信号，分开调用得到的值可能来自不同的时刻。measure_all() 从同一次采集中读取全部值，因此它们彼此一致。

`trigger_edge(trigger: &EdgeTrigger) -> Result<()>`

配置边沿触发。Box 只应用已设置的字段。因此只设置 level 时只会移动触发电平，触发源和斜率保持不变。

use lager::{EdgeTrigger, TriggerMode};

ch1.trigger_edge(&EdgeTrigger {
    source: Some("CHAN1".into()),
    level: Some(1.2),
    mode: Some(TriggerMode::Normal),
    ..Default::default()
})?;

TriggerMode::Single 让示波器为一次采集做好准备，与台式示波器上的行为相同。没有设置任何字段的调用会被 Box 拒绝。

`capture() -> Result<ScopeCapture>`

获取示波器最新一次采集。如果还没有，它会立即采集一次，因此请先用 run() 或 single() 启动示波器。需要 scope-trace feature：

[dev-dependencies]
lager = { package = "lager-net", version = "0.13", features = ["scope-trace"] }

ch1.single()?;
let capture = ch1.capture()?;

let volts = capture.volts('A').expect("channel A is on");
let times = capture.time_axis();
println!("{} samples at {} Hz", volts.len(), capture.sample_rate_hz());
assert!(volts.iter().all(|v| v.abs() < 3.6), "over range at {:?}", times.first());

capture_timeout(timeout) 按您给定的时间等待。到时仍没有采集时，以 Error::Timeout 失败。

`stream() -> Result<ScopeStream>`

订阅从现在起的每一次采集。读取较慢的一方得到的是最新的采集而不是积压的数据，因此看到的只是较低的帧率。用 next_capture(timeout: Duration) 读取，用 close() 结束。把流 drop 掉同样会关闭它。

use std::time::Duration;

let mut stream = ch1.stream()?;
for _ in 0..10 {
    let capture = stream.next_capture(Duration::from_secs(5))?;
    assert!(capture.triggered());
}
stream.close();

带类型的控制方法

count 是在 AcquisitionMode::Average 下参与平均的采集次数（设置之前为 16）。时间光标需要一次采集来读取其下方的波形；电压光标不需要。

use lager::nets::scope::{AcquisitionMode, CursorSettings};

scope.set_acquisition(AcquisitionMode::Average, Some(32))?;
scope.set_cursors(&CursorSettings { time: Some((0.0, 1e-3)), ..Default::default() })?;
let readings = scope.measure_cursors()?.readings;

签名
`capabilities() -> Result<ScopeCapabilities>`
`state() -> Result<ScopeState>`
`set_acquisition(mode: AcquisitionMode, count: Option<u32>) -> Result<Acquisition>`
`set_roll(mode: RollMode) -> Result<Roll>`
`set_display(settings: &DisplaySettings) -> Result<serde_json::Value>`
`fft(opts: &FftOptions) -> Result<Spectrum>`
`set_cursors(settings: &CursorSettings) -> Result<Cursors>`
`measure_cursors() -> Result<CursorMeasurement>`

`command(action: &str, params: Value) -> Result<Value>`

运行一个没有类型化方法的示波器操作，并返回它的 value。

use serde_json::json;

ch1.command("get_state", json!({}))?;

示例

测量一个时钟

use lager::{EdgeTrigger, LagerBox, Measurement, TriggerMode};

let lager = LagerBox::from_env()?;
let ch1 = lager.scope("scope1-ch1");

ch1.enable()?;
ch1.set_coupling("dc")?;
ch1.set_scale(0.5)?;
ch1.set_timebase(1e-6)?;
ch1.trigger_edge(&EdgeTrigger {
    level: Some(1.65),
    mode: Some(TriggerMode::Normal),
    ..Default::default()
})?;
ch1.run()?;

let all = ch1.measure_all()?;
let hz = all.get(Measurement::Frequency).expect("a clock has a frequency");
assert!((hz - 32_768.0).abs() < 50.0, "clock at {hz} Hz");

受支持的硬件

仪器	备注
Rigol MSO5000 系列	`set_coupling` 还接受 `"gnd"`
PicoScope 2000、2000A、3000A、4000A 和 5000A 系列	没有接地耦合

说明

在仪器 Net 上执行通道操作会失败。 把 set_scale() 或 measure() 发给 scope Net 时，Box 会以 Error::Box 和 HTTP 400 应答。错误信息会列出应改用的通道 Net。
早于 0.55.0 的 Box 对示波器 Net 应答 HTTP 501，crate 将其返回为 Error::UnsupportedByBox。
每次调用允许 45 秒。Box 把单条示波器命令限制在 30 秒，因此 Box 自己的超时错误会在 crate 停止等待之前到达。
波形采集需要能够流式传输的示波器。 capture() 和 stream() 使用 Box 的 /scope 页面背后的 WebSocket。它们适用于 PicoScope Net，以及已配对 HDMI 采集卡的 Rigol MSO5000 Net（Box 软件 0.57.0 或更高版本）。在没有采集卡的 Rigol 上，Box 会拒绝该请求，返回 Error::Box。
capture() 和 stream() 只在阻塞客户端上提供，并且需要普通的 http:// Box URL。
逻辑分析仪 Net 没有 Rust 句柄，因为 Box 在 /net/command 上没有 logic 角色。待办清单在 MISSING_ENDPOINTS.md 中。
来自 AsyncLagerBox::scope 的 AsyncScope 提供同样的方法，以 .await 调用。

入门

开发

电源与仿真

测量

I/O 与通信

实用工具

安全

Box 设置

指南

句柄

方法

类型

`Measurement`

`EdgeTrigger`

`TriggerSettings` 和 `Measurements`

`ScopeCapture`

控制设置与结果

方法参考

`measure(m: Measurement) -> Result<Option<f64>>`

`measure_all() -> Result<Measurements>`

`trigger_edge(trigger: &EdgeTrigger) -> Result<()>`

`capture() -> Result<ScopeCapture>`

`stream() -> Result<ScopeStream>`

带类型的控制方法

`command(action: &str, params: Value) -> Result<Value>`

示例

测量一个时钟

受支持的硬件

说明

句柄

方法

类型

Measurement

EdgeTrigger

TriggerSettings 和 Measurements

ScopeCapture

控制设置与结果

方法参考

measure(m: Measurement) -> Result<Option<f64>>

measure_all() -> Result<Measurements>

trigger_edge(trigger: &EdgeTrigger) -> Result<()>

capture() -> Result<ScopeCapture>

stream() -> Result<ScopeStream>

带类型的控制方法

command(action: &str, params: Value) -> Result<Value>

示例

测量一个时钟

受支持的硬件

说明

`Measurement`

`EdgeTrigger`

`TriggerSettings` 和 `Measurements`

`ScopeCapture`

`measure(m: Measurement) -> Result<Option<f64>>`

`measure_all() -> Result<Measurements>`

`trigger_edge(trigger: &EdgeTrigger) -> Result<()>`

`capture() -> Result<ScopeCapture>`

`stream() -> Result<ScopeStream>`

`command(action: &str, params: Value) -> Result<Value>`