Oscilloscope

Set up channels, timebase and trigger, and read measurements from a scope net

Drive an oscilloscope from a cargo test: set up its channels, timebase and trigger, control acquisition, and read measurements. It works with Rigol MSO5000 and PicoScope nets, and requires box software 0.55.0 or later.

Handle

use lager::LagerBox;

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

A scope is saved on the box as two kinds of net:

• one scope net for the instrument
• one scope-channel net for each input

lager.scope(name) takes either kind. Channel settings and measurements need a channel net. Everything else belongs to the instrument, and works through either kind.

Methods

Method	Net	Description
name()	either	The net name this handle addresses
enable(), disable(), is_enabled()	channel	Turn the channel on or off, or read it back
set_scale(), scale()	channel	Vertical scale (V/div)
set_coupling(), coupling()	channel	Input coupling ("dc", "ac"; a Rigol also takes "gnd")
set_probe(), probe()	channel	Probe attenuation (1 for 1x, 10 for 10x)
set_offset(), offset()	channel	Vertical offset (V)
measure()	channel	One measurement
measure_all()	channel	Every measurement, from one capture
set_timebase(), timebase()	either	Timebase (s/div)
set_time_offset(), time_offset()	either	Capture window position relative to the trigger (s)
trigger_edge()	either	Configure the edge trigger
trigger()	either	Read the trigger back
run(), single(), stop()	either	Continuous acquisition, one acquisition, or stop
force_trigger()	either	Trigger now
autoscale()	either	Let the instrument pick scale, timebase and trigger
capabilities()	either	The instrument’s channels, limits and optional features
state()	either	Every control setting in one request
capture_mode(), trigger_source(), trigger_slope(), trigger_level()	either	Read one trigger setting
set_trigger_holdoff(), trigger_holdoff()	either	Trigger holdoff (s)
set_acquisition(), acquisition()	either	Normal, average or peak acquisition
set_roll(), roll()	either	Roll mode
set_display(), display()	either	Persistence, XY, zoom, math trace and FFT pane
fft()	either	The strongest spectral peaks of a channel
set_cursors(), cursors(), clear_cursors()	either	Set, read or clear the cursors
measure_cursors()	either	Read the cursors’ positions and the differences between them
capture(), capture_timeout()	either	The latest capture’s samples (feature scope-trace)
stream()	either	Every capture from now on (feature scope-trace)
command()	either	Any other scope action, with raw JSON params

Types

Measurement

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

Voltages are in volts, times in seconds, frequency in hertz, and duty cycle and overshoot in percent.

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 and Measurements

trigger() returns a TriggerSettings with mode, source, slope, level, and holdoff when the scope reports one. Each field is an Option, in the instrument’s own spelling.

measure_all() returns a Measurements with one Option<f64> field for each quantity. Measurements::get(Measurement) reads one of them.

ScopeCapture

capture() and ScopeStream::next_capture() return one capture:

Item	Description
seq	The capture’s sequence number
sample_interval_ns	Time between samples (ns)
pre_trigger_samples, post_trigger_samples	Samples before and after the trigger
samples_per_channel	Samples in each channel
channels	One TraceChannel for each channel: label, coupling, scale_v_per_count, offset_v
volts('A')	One channel’s samples in volts
counts('A')	One channel’s raw samples
time_axis()	Each sample’s time, in seconds from the trigger
triggered()	Whether this capture came from a trigger
overflowed('A')	Whether the channel went over range
sample_rate_hz(), duration_s()	The capture’s rate and length

volts() and counts() return None for a channel that is not in the capture.

Method Reference

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

Read one quantity from the channel.

use lager::Measurement;

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

Returns: None when the capture does not contain the quantity. For example, a DC level has no period. This is an answer, not an error.

measure_all() -> Result<Measurements>

Read every quantity the capture supports. Each measure() call takes its own capture, so values from separate calls can come from different moments of a live signal. measure_all() reads them all from one capture, so they agree with each other.

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

Configure the edge trigger. The box applies only the fields that are set. So level alone moves the level, and leaves the source and slope as they are.

use lager::{EdgeTrigger, TriggerMode};

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

TriggerMode::Single arms the scope for one acquisition, as on a bench scope. The box refuses a call with no field set.

capture() -> Result<ScopeCapture>

Fetch the scope’s latest capture. If it has none, it takes one now, so start the scope first with run() or single(). Needs the scope-trace feature:

[dev-dependencies]
lager = { package = "lager-net", version = "0.9", 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) waits for the time you give it. Without a capture by then, it fails with Error::Timeout.

stream() -> Result<ScopeStream>

Subscribe to every capture from now on. A slow reader gets the newest capture rather than a backlog, so it sees a lower frame rate. Read with next_capture(timeout: Duration), and end with close(). Dropping the stream also closes it.

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();

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

Run a scope action that has no typed method, and return its value.

use serde_json::json;

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

Examples

Measure a clock

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");

Supported Hardware

Instrument	Notes
Rigol MSO5000 series	set_coupling also takes "gnd"
PicoScope 2000, 2000A, 3000A, 4000A and 5000A series	No ground coupling

Notes

• A channel action on the instrument net fails. Send set_scale() or measure() to the scope net, and the box answers Error::Box with HTTP 400. The message names the channel nets to use instead.
• A box older than 0.55.0 answers HTTP 501 for scope nets, which the crate returns as Error::UnsupportedByBox.
• Each call allows 45 s. The box limits one scope command to 30 s, so the box’s own timeout error arrives before the crate stops waiting.
• Trace capture needs a scope that streams. capture() and stream() use the WebSocket behind the box’s /scope page. They work on PicoScope nets, and on Rigol MSO5000 nets with an HDMI capture card paired (box software 0.57.0 or later). On a Rigol with no capture card, the box refuses the request, which gives Error::Box.
• capture() and stream() are on the blocking client only, and need a plain http:// box URL.
• Logic-analyzer nets have no Rust handle, because the box has no logic role on /net/command. The work list is in MISSING_ENDPOINTS.md.
• AsyncScope from AsyncLagerBox::scope provides the same methods, .awaited.