benchControlPlatform
Guide

Add an instrument

How a bench instrument gets into the app as the code is in version 0.7.0. A power supply is the easy case: copy the simulated supply. The four example instruments show the transports: the HM310T for Modbus RTU, the IPS3608 for a binary protocol over USB CDC serial, the Rigol DHO924S for SCPI over TCP and the FNB58 for USB HID.

The state today

A power supply needs no central file but the device list. Another kind of instrument needs a page of its own and changes in central files, and a second oscilloscope or USB meter needs such changes too, because the app wires those two kinds itself for now. Moving them behind the device list is on the roadmap, and until 1.0 the structure changes with each step. This page describes the code as it is now.

What kind of instrument

A power supply
is copied from the simulated supply sim-psu and implements the supply contract. It gets the shared worker, the supply page, its tab, demo mode and the tests of every supply, and touches no central file but the device list: Add a power supply.
An oscilloscope or a USB meter
has a page of its own. The app wires the Rigol and the FNB58 itself for now, so a second one means changes in central files: Another kind.
Another kind
needs a page of its own and changes in central files, as the FNB58 shows: Another kind.

Add a power supply

The supply to copy is src/devices/sim_psu/, the simulated supply sim-psu. It runs in memory, without an instrument or a port, through the same worker and page as a real supply. Its four files:

mod.rs
its ENTRY in the device list, a DeviceEntry of Kind::Supply: id, name, maker, transport and status; and a test that runs the supply end to end through the worker
model.rs
the supply in memory, SimSupply; in yours, the state of your device
driver.rs
its INFO, a SupplyInfo with the fields, rows, memory slots and connection settings the page shows; its connect; and its implementation of the supply contract SupplyDriver from src/kinds/supply/mod.rs
demo.rs
its demo data, a SupplyDemo

The HM310T and the IPS3608 keep that contract code in supply.rs, next to a driver.rs that speaks their protocol.

The steps

  1. Copy src/devices/sim_psu/ to a folder of your own. Its protocol goes into that folder, or its driver uses ModbusClient or ScpiClient.
  2. Implement SupplyDriver for your device and describe it in its INFO. It starts as experimental (Status::Experimental).
  3. Add two lines to src/devices/mod.rs: pub mod <folder>; and <folder>::ENTRY, in the device list, which is kept in the order of the ids.
  4. Write its page docs/devices/<id>.md: under the README link, a head table of one row with maker, model, kind, status and transport, as docs/devices/sim-psu.md has it. A test compares the table with the entry. It gets no row in the README, which lists only the four starter devices, and the maintainer adds its CHANGELOG.md line when merging.
  5. Look at it in demo mode:
BCP_DEMO=1 BCP_DEVICES=<id> cargo run

The steps with every name and path: AGENTS.md, "You want to add a supply".

What a supply gets

  • A worker thread of the shared supply worker (src/kinds/supply/worker.rs): it keeps the connection, polls after 500 ms without a command, reads back every write, and drops the driver after a failed poll.
  • The supply page, drawn from its INFO and its data: readouts, setpoints, protection, the memory tiles and the trend. "All outputs off" switches its output off too.
  • A tab when BCP_DEVICES or active_devices in the settings names it, and its connection settings in a table of its own in settings.toml, [devices.<id>].
  • A place in demo mode, from its demo.rs, and in the test bench.
  • The tests that run for every supply of the list: the page fit at every size and scale, the regions of the page, the scans for device names and imports, the contract checks and the output-safety test.

Another kind of instrument

For now the app's shell wires the oscilloscope and the USB meter itself, each with a page of its own. So a second scope or meter, or a new kind of instrument, means changes in central files, and a new kind also needs a Kind and a page of its own. Moving the scope and the meter behind the device list is on the roadmap.

The FNB58 shows what it takes. Its own files are src/protocol/fnb58.rs and src/devices/fnb58/: its ENTRY, model.rs, driver.rs, runtime.rs (its worker thread) and recorder.rs (the CSV recording). Outside them:

FileWhat the FNB58 has there
src/app/mod.rsits fields, commands and events
src/app/demo.rs, src/app/capture.rsits demo data and its demo states
src/devices/mod.rsits Kind
src/ui/console/mod.rs, src/ui/console/tab_bar.rs, src/ui/console/testing.rsits page by Kind, its tab, the probe of the test bench
src/ui/console/meter/its page

The layers

Rust 2024 with eframe and egui 0.31, drawn with wgpu. The code lives in seven folders, and the guard rails in one file:

FolderContentsImports from the crate
src/transport/TCP, serial ports and USB HID: TcpConnection, SerialTransport, the Transport trait, open_port, HidPort and the ReportPort traitnothing
src/protocol/SCPI (ScpiClient), Modbus RTU (ModbusClient), the IPS3608 frames, the FNB58 reportstransport
src/devices/mod.rs: the device list (devices(), find(id), STARTER: the four starter devices in tab order). A folder per device with mod.rs (its ENTRY), model.rs and driver.rs; the scope and the meter also runtime.rs (their worker thread), the two real supplies supply.rs (the driver behind the supply contract) and demo.rsprotocol, transport, kinds::supply, core::types::ConnectionState
src/kinds/supply/the supply kind: the contract SupplyDriver, SupplyInfo and SupplyData, the one worker of every supply (SupplyHandle) and SupplyDemocore::types, transport::serial
src/app/the shell BenchControlApp: the active devices, the open page, a SupplyInstrument per active supply, the scope's and the meter's own state and commands, the event draining and the settings save; the demo data of the scope and the meter, DevOptions and the capturecore, devices, kinds, transport::hid, ui
src/ui/console/the pages, the tab bar (a tab per active device), the status bar, the controls, the widgets, the theme and helpersapp, core, devices, kinds, transport::hid
src/core/the settings file, the log, AppTab (Device(id) or Logs) and ConnectionStatedevices::rigol::model
src/guards.rstest builds only: the guard rails of the device list

Threads

  • One worker thread per active instrument. Outside demo mode BenchControlApp::new starts the scope's and the meter's with <Device>RuntimeHandle::spawn, and each supply's through its SupplyInstrument, on the shared supply worker. A handle holds two unbounded crossbeam channels: commands to the worker, events back. Dropping a handle sends Shutdown and joins the thread.
  • The worker does the blocking I/O, sends an event and asks egui for a repaint.
  • Each frame, the app drains every pending event of the workers with try_recv (a supply's in its instrument), draws the pages, and saves the settings if one changed.

How a supply reaches the screen: the IPS3608

Its own files are src/protocol/fnirsi.rs and src/devices/fnirsi/, with its ENTRY, INFO, connect and demo data. BenchControlApp::new gives every active supply a SupplyInstrument (src/app/supply.rs, which names no device); it loads the supply's settings and starts a SupplyHandle with its connect. The worker polls the driver and sends SupplyEvent::DataUpdated; the instrument keeps the data and the history. The supply page asks the contract, never the name: INFO gives the fields, the decimals, the CV and CC lamps, energy and charge, the rows and the connection settings, the data gives the values. A click goes to the instrument's act, which sends a SupplyCommand.

More in docs/architecture.md in the repository.

Reuse before you write

Transports
Transport (src/transport/serial.rs) with FakeTransport and the register map FakeModbusDevice (src/protocol/modbus.rs, test builds); open_port for a raw serial port; ReportPort (src/transport/hid.rs); TcpConnection (src/transport/tcp.rs).
Protocol clients
ScpiClient (src/protocol/scpi.rs), bound to TcpConnection; ModbusClient (src/protocol/modbus.rs) on any Transport.
Supply kind
the contract SupplyDriver, the worker SupplyHandle that runs it, and the supply page supply::show(inst, shell, ctx), which serves every supply of the list from its SupplyInfo and SupplyData.
Controls
src/ui/console/controls.rs: button, switch, toggle, stepper, value_field, dropdown, segmented, tabs, menu and more.
Widgets
src/ui/console/widgets.rs: chip, dot, region, kv_row, connection_box and more.
Values and plots
format.rs: number formats and parse_value for typed values. axis.rs: value axes of trends. plotting.rs: the trend plots.
Arming
arming.rs: the click hold and the two-click arming of an action without undo.
Test harness
src/ui/console/testing.rs: Bench runs the whole app on a page without a window; a test clicks a control by its name and reads what went to a worker. Bench::with_devices(ids, ..) activates exactly ids; Bench::with_extra(&TEST_PSU, ..) adds a made-up supply without a port.

Which example uses what:

ExampleTransport and protocolDriver and its tests
Rigol DHO924SSCPI over TCP: ScpiClient on TcpConnectionDho900; a driver test talks to a fake scope on a local TCP port
Hanmatek HM310TModbus RTU over a serial port: ModbusClient on a TransportHanmatekHm310t<T: Transport>, behind the supply contract in supply.rs; tests with a fake port
FNIRSI IPS3608a binary protocol over USB CDC serial: its frames in src/protocol/fnirsi.rsFnirsiIps3608<P: Read + Write>, behind the supply contract in supply.rs; tests with FakePort
FNIRSI FNB58USB HID reports: src/protocol/fnb58.rs on a ReportPortFnb58<P: ReportPort>; tests with a fake port of its own
Sim PSUnone: the supply lives in memorySimSupply behind the supply contract in driver.rs; a test runs it end to end through the worker

Demo data

Demo mode lets anyone look at a page without the instrument; the captures of the definition of done are made in it. A supply brings its demo data in its own demo.rs.

  • In demo mode BenchControlApp::new gives every instrument an idle handle (RigolRuntimeHandle::idle(), SupplyHandle::idle() and the like): no worker thread, commands go nowhere, no event comes. It neither copies, loads nor saves the settings, and opens no file dialog.
  • demo::apply fills the active devices in tab order: the scope and the meter from src/app/demo.rs, a supply from its SupplyDemo. demo::apply_states then sets the states that BCP_STATE names, a supply state in every supply. The tokens are in DemoState::ALL in src/app/capture.rs.
mkdir -p target/captures
BCP_DEMO=1 BCP_TAB=fnirsi-ips3608 BCP_WINDOW=1440x900 BCP_CAPTURE=target/captures/fnirsi.png cargo run

The capture cannot create its folder, hence the mkdir. It saves the window 1.5 s after the start and quits. The pixel size follows the scale of the display: 1440 x 900 at scale 1, 2880 x 1800 at scale 2. A new supply's page: add BCP_DEVICES=<id> and BCP_TAB=<id>.

Tests

  • Every driver of a real instrument has at least one test built from bytes captured from it. The example is accepts_info_report_captured_from_fnb58 in src/protocol/fnb58.rs.
  • Driver tests run on fakes: FakeTransport and the register map FakeModbusDevice for a Transport, FakePort for the IPS3608, a fake port of its own for the FNB58, a fake scope on a local TCP port for the Rigol.
  • Page tests use Bench from src/ui/console/testing.rs: it runs the whole app on a page without a window, clicks a control by its name and reads what went to a worker.
  • The guard rails fail cargo test when a device does not fit the list: the ids unique, in kebab case and in order; for each id a page docs/devices/<id>.md with the head table the list gives, and no page without a device; a README row for each starter device; no supply's id, name or folder in the shell; the imports between the layers; each supply's slots, connection settings and demo data against its SupplyInfo. For every supply of the list the supply page's tests add the page fit at every size and scale, the regions and the output safety.
  • Tests reach neither the real settings nor the save dialog: test builds keep settings.toml under the temporary directory, and a test answers the dialog with save_file_answer.
  • Hardware tests are #[ignore] (three today) and only read or restore what they change: the IPS3608 test refuses to run with the output on and restores the voltage it nudges; the two FNB58 tests only read from the meter.

Docs

  • Its page docs/devices/<id>.md: under the README link a head table of one row (maker, model, kind, status and transport, as its entry in the list has them), then the protocol, the timing, the limits and what is not supported or not confirmed, as the example pages show.
  • No row in the README's table of supported instruments: it lists only the four starter devices.
  • Protocol knowledge taken from another project is credited on that page, in its section "Sources and licenses". Code is ported only from a source whose license allows its use under this project's license.
  • The manual (docs/manual/) where the change touches a page. The CHANGELOG.md line of a new device is added by the maintainer when merging.

The rules a device keeps

  • The UI thread never talks to an instrument. All instrument I/O runs on the instrument's worker thread: a supply's on the shared supply worker (src/kinds/supply/worker.rs), the scope's and the meter's in their runtime.rs. The app sends commands over a channel and drains the events every frame with try_recv. Add no blocking call to the UI thread.
  • Protocol details stay in src/protocol/ and src/devices/. src/app/, src/ui/ and src/core/ import nothing from crate::protocol; they send typed commands (RigolCommand, SupplyCommand, Fnb58Command).
  • The supply page and the shell name no supply. The page asks the supply's contract, never its name, and a test scans for names.
  • Nothing switches an output without a user action. Write::Output is sent only by a click on a supply's output switch and by "All outputs off"; a memory recall sets voltage and current only.
  • Demo mode never reaches a device. Every instrument gets an idle handle there.
  • Colours, fonts and controls come from the theme. Colours and fonts from theme.rs (palette(), channel_color, font), no colour literal outside it; new controls from controls.rs (fixed size, named: controls::id(name)) and widgets.rs.

Definition of done

  • The four checks pass, among them the guard rails:
cargo fmt --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cargo deny check licenses
  • A capture of every page the change touches, in the demo states it changes, looked at.
  • README.md, docs/manual/, docs/devices/ and CHANGELOG.md are true for the change; a new device's CHANGELOG.md line is the maintainer's.
  • New text is English with ASCII punctuation.

cargo deny is a tool of its own (cargo install cargo-deny --locked). The pipeline runs the same four, and each has to pass.

Send it back, from 1.0 on

Merge requests for instruments make sense from 1.0 on. Before that, the code under an instrument changes with every step of the roadmap, so a merge request written against today's structure would have to be redone. Until 1.0, try the demo, read this guide, and tell the project which instrument you would add with an Instrument-request issue on GitLab.

From 1.0 on: if you integrate an instrument, in a fork or just for yourself, please send it as a merge request, also when it is not finished. An unfinished device is welcome as experimental, and nobody has to integrate the same instrument a second time. The license does not require this; we ask for it.

Today, a device merge request uses the Device template (.gitlab/merge_request_templates/Device.md). It asks for:

Instrument
maker and model, hardware revision, firmware
Operating system
the one the device was tried on
Tried on the hardware
connect, read, each setpoint, output on and off, disconnect, cable pulled while connected; leave out what the instrument does not have
Capture
a capture of the device's page with the real device connected
Protocol knowledge
where it comes from: the manual, documents from the vendor, your own captures, another project (name it and its license)
Test from captured bytes
the test built from bytes captured from the real instrument
Checklist
the four checks pass; docs/devices/<id>.md with its head table; the contribution is under the project's license
verified
the merge request has everything the Device template asks for
experimental
anything less; the status is set in review. A change to the registers or writes of a verified device needs the template's evidence again, or sets it back to experimental
simulated
a device without an instrument, such as sim-psu

An instrument you would like to see supported but cannot add yourself: open an Instrument-request issue on GitLab.

With a coding agent

Contributions made with an AI agent are welcome. The rule is the same for everybody: a new device needs somebody who ran it on the hardware. Point the agent at AGENTS.md in the repository root: the commands, a map of the code, the hard rules, what to reuse, the steps for a supply and the definition of done.

  • An agent starts the app only in demo mode, also with BCP_DEVICES. A normal start loads the user's settings.toml, saves it when a setting changes, and starts the workers of the active devices.
  • It never runs the hardware tests (--ignored) without the instrument and its owner.
  • An agent cannot confirm that a device works. The person with the instrument does, in the merge request, with the Device template: what was tried on the hardware, a capture with the real device, the source of the protocol knowledge and the test from captured bytes. Without all of it the device is experimental.