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.
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-psuand 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
ENTRYin the device list, aDeviceEntryofKind::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, aSupplyInfowith the fields, rows, memory slots and connection settings the page shows; itsconnect; and its implementation of the supply contractSupplyDriverfromsrc/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
- Copy
src/devices/sim_psu/to a folder of your own. Its protocol goes into that folder, or its driver usesModbusClientorScpiClient. - Implement
SupplyDriverfor your device and describe it in itsINFO. It starts asexperimental(Status::Experimental). - 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. - Write its page
docs/devices/<id>.md: under the README link, a head table of one row with maker, model, kind, status and transport, asdocs/devices/sim-psu.mdhas 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 itsCHANGELOG.mdline when merging. - 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
INFOand its data: readouts, setpoints, protection, the memory tiles and the trend. "All outputs off" switches its output off too. - A tab when
BCP_DEVICESoractive_devicesin the settings names it, and its connection settings in a table of its own insettings.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:
| File | What the FNB58 has there |
|---|---|
src/app/mod.rs | its fields, commands and events |
src/app/demo.rs, src/app/capture.rs | its demo data and its demo states |
src/devices/mod.rs | its Kind |
src/ui/console/mod.rs, src/ui/console/tab_bar.rs, src/ui/console/testing.rs | its 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:
| Folder | Contents | Imports from the crate |
|---|---|---|
src/transport/ | TCP, serial ports and USB HID: TcpConnection, SerialTransport, the Transport trait, open_port, HidPort and the ReportPort trait | nothing |
src/protocol/ | SCPI (ScpiClient), Modbus RTU (ModbusClient), the IPS3608 frames, the FNB58 reports | transport |
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.rs | protocol, 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 SupplyDemo | core::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 capture | core, 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 helpers | app, core, devices, kinds, transport::hid |
src/core/ | the settings file, the log, AppTab (Device(id) or Logs) and ConnectionState | devices::rigol::model |
src/guards.rs | test builds only: the guard rails of the device list |
Threads
- One worker thread per active instrument. Outside demo mode
BenchControlApp::newstarts the scope's and the meter's with<Device>RuntimeHandle::spawn, and each supply's through itsSupplyInstrument, on the shared supply worker. A handle holds two unbounded crossbeam channels: commands to the worker, events back. Dropping a handle sendsShutdownand 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) withFakeTransportand the register mapFakeModbusDevice(src/protocol/modbus.rs, test builds);open_portfor a raw serial port;ReportPort(src/transport/hid.rs);TcpConnection(src/transport/tcp.rs).- Protocol clients
ScpiClient(src/protocol/scpi.rs), bound toTcpConnection;ModbusClient(src/protocol/modbus.rs) on anyTransport.- Supply kind
- the contract
SupplyDriver, the workerSupplyHandlethat runs it, and the supply pagesupply::show(inst, shell, ctx), which serves every supply of the list from itsSupplyInfoandSupplyData. - Controls
src/ui/console/controls.rs:button,switch,toggle,stepper,value_field,dropdown,segmented,tabs,menuand more.- Widgets
src/ui/console/widgets.rs:chip,dot,region,kv_row,connection_boxand more.- Values and plots
format.rs: number formats andparse_valuefor 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:Benchruns 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 exactlyids;Bench::with_extra(&TEST_PSU, ..)adds a made-up supply without a port.
Which example uses what:
| Example | Transport and protocol | Driver and its tests |
|---|---|---|
| Rigol DHO924S | SCPI over TCP: ScpiClient on TcpConnection | Dho900; a driver test talks to a fake scope on a local TCP port |
| Hanmatek HM310T | Modbus RTU over a serial port: ModbusClient on a Transport | HanmatekHm310t<T: Transport>, behind the supply contract in supply.rs; tests with a fake port |
| FNIRSI IPS3608 | a binary protocol over USB CDC serial: its frames in src/protocol/fnirsi.rs | FnirsiIps3608<P: Read + Write>, behind the supply contract in supply.rs; tests with FakePort |
| FNIRSI FNB58 | USB HID reports: src/protocol/fnb58.rs on a ReportPort | Fnb58<P: ReportPort>; tests with a fake port of its own |
| Sim PSU | none: the supply lives in memory | SimSupply 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::newgives 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::applyfills the active devices in tab order: the scope and the meter fromsrc/app/demo.rs, a supply from itsSupplyDemo.demo::apply_statesthen sets the states thatBCP_STATEnames, a supply state in every supply. The tokens are inDemoState::ALLinsrc/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_fnb58insrc/protocol/fnb58.rs. - Driver tests run on fakes:
FakeTransportand the register mapFakeModbusDevicefor aTransport,FakePortfor 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
Benchfromsrc/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 testwhen a device does not fit the list: the ids unique, in kebab case and in order; for each id a pagedocs/devices/<id>.mdwith 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 itsSupplyInfo. 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.tomlunder the temporary directory, and a test answers the dialog withsave_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. TheCHANGELOG.mdline 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 theirruntime.rs. The app sends commands over a channel and drains the events every frame withtry_recv. Add no blocking call to the UI thread. - Protocol details stay in
src/protocol/andsrc/devices/.src/app/,src/ui/andsrc/core/import nothing fromcrate::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::Outputis 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 fromcontrols.rs(fixed size, named:controls::id(name)) andwidgets.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/andCHANGELOG.mdare true for the change; a new device'sCHANGELOG.mdline 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>.mdwith its head table; the contribution is under the project's license
- verified
- the merge request has everything the
Devicetemplate asks for - experimental
- anything less; the status is set in review. A change to the registers or writes of a
verifieddevice needs the template's evidence again, or sets it back toexperimental - 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'ssettings.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
Devicetemplate: 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 isexperimental.