Spvirit
Spvirit is a pure-Rust implementation of the EPICS PVAccess protocol (client, server, wire codec, command-line tools, and Python bindings) with no dependency on an EPICS base installation.
Quickstart
Install. This one command brings the Python module and the sp*
command-line tools (fifteen binaries); there is no compiler and no Rust
toolchain involved on Linux, macOS, or Windows x86_64.
pip install spvirit
Save this as first.py. It is a complete soft IOC serving three PVs:
temp = spvirit.ai("SIM:TEMPERATURE", 22.5) # input — read-only to clients
setpoint = spvirit.ao("SIM:SETPOINT", 25.0) # output — clients may write
enable = spvirit.bo("SIM:ENABLE", False) # output — a writable bool
server = spvirit.Server(pvs=[temp, setpoint, enable])
server.run()
Run it, and read a PV from a second terminal:
python first.py # terminal 1 — it blocks, serving
$ spget SIM:TEMPERATURE
SIM:TEMPERATURE 2026-08-06 09:38:00.729 22.5
$ spput SIM:SETPOINT 30
SIM:SETPOINT OK
$ spget SIM:SETPOINT
SIM:SETPOINT 2026-08-06 09:38:00.729 30
$ spput SIM:TEMPERATURE 5
SIM:TEMPERATURE ERROR protocol error: PUT init error: Write access denied
If you see those lines you have a working PVAccess server. The client found
it by broadcasting the PV name, and SIM:TEMPERATURE refused the write
because ai is an input record.
The same thing in Rust is Your first PV; every chapter of this book shows both languages.
Where to go next
- New to EPICS: EPICS in 10 minutes
- Soft IOC quickstart: Your first PV
- Full tour: Serving scalars and the twelve chapters after it
- Function lookup: API reference below
How the site is laid out
- Fundamentals — what EPICS is, what Normative Types are, and the choice to make before you write anything: records vs raw NT.
- Getting started — install, then serve and read a PV in under a page.
- Progressive examples — thirteen chapters, Rust and Python side by side, ending in a complete IOC.
- Command-line tools — a page per
sp*binary, with real captured output. - Reference — the crate map, the record-type matrix, the Python API, troubleshooting, and the known gaps.
- Developer guide — internals, with file-and-line citations, for people changing spvirit itself.
API reference
This book is the tutorial. The exhaustive, generated API documentation lives on docs.rs, one page per crate:
| Crate | API docs |
|---|---|
spvirit-types | docs.rs/spvirit-types |
spvirit-codec | docs.rs/spvirit-codec |
spvirit-client | docs.rs/spvirit-client |
spvirit-server | docs.rs/spvirit-server |
spvirit-tools | docs.rs/spvirit-tools |
spvirit-calc | docs.rs/spvirit-calc |
spvirit-ioc | docs.rs/spvirit-ioc |
spvirit-gateway | docs.rs/spvirit-gateway |
For Python there is no generated site; the
Python API chapter is the reference, and every
object carries a docstring, so help(spvirit.ai) works at the prompt.
Project
- Licence — BSD-3-Clause. See Licence and support.
- Source and issues — github.com/ISISNeutronMuon/spvirit
- Contributing — Licence and support has the short version; the Developer guide has the long one.
Every Rust sample is included verbatim from an example that CI compiles;
Python samples are included from examples that CI syntax-checks. Console
output and small .db fragments are shown inline. The badge at the top of each chapter links
to that source and to the test that checks it, including the quickstart
above:
✅ Verified ·
demo_first_pv.py· checkdocs_verify·The badge reports the whole
docs-verifysuite, not this chapter alone.