Skip to content
ISISNeutronMuonPublic

About

pvAccess Protocol implementation in Rust

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Spvirit

crates.io (spvirit-types) crates.io (spvirit-codec) crates.io (spvirit-client) crates.io (spvirit-server) crates.io (spvirit-tools) License

/ˈspɪrɪt/ of the Machine

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. It is not yet production ready, but it is available for anyone to use and contribute to.

Read the documentation: fundamentals, progressive examples in Rust and Python, and a page per CLI tool.

Key areas of development in the near future include:

  • Expanding spvirit-server with more complete softIOC behaviours and record processing.
  • TLS support and structured put payloads in the client.
  • Segmentation emission in the encoder, so large values (NTNDArray images) can be sent as segmented messages rather than one oversized frame.

Why Rust?

Because why not, admittedly I just wanted to learn Rust and this seemed like a fun project with a moderately useful outcome.

The crates

Crate What it is
spvirit-types Shared data model for PVAccess Normative Types (NT).
spvirit-codec PVAccess protocol encode/decode (PVA message layer + pvData) and segment reassembly.
spvirit-client Client library: search, connect, get, put, monitor.
spvirit-server Server library: .db parsing, Source trait, PVAccess server runtime.
spvirit-tools The sp* command-line tools.
spvirit-py Python bindings via PyO3: client and server APIs from Python.
spvirit-ioc Synchronous EPICS record-processing engine (scan lists, links, lock sets).
spvirit-gateway p4p-compatible PVAccess gateway library.
spvirit-calc CALC expression evaluator.

spvirit-client and spvirit-server do not depend on each other. The full layering, versions and feature flags are in the crate map.

Hello, PV

Three records, served over PVAccess.

use spvirit_server::PvaServer;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = PvaServer::builder()
        .ai("SIM:TEMPERATURE", 22.5)   // input  — read-only to clients
        .ao("SIM:SETPOINT", 25.0)      // output — clients may write
        .bo("SIM:ENABLE", false)
        .build();
    server.run().await?;
    Ok(())
}
import spvirit

temp = spvirit.ai("SIM:TEMPERATURE", 22.5)
setpoint = spvirit.ao("SIM:SETPOINT", 25.0)
enable = spvirit.bo("SIM:ENABLE", False)

spvirit.Server(pvs=[temp, setpoint, enable]).run()

Then, from another terminal, spget SIM:TEMPERATURE.

Walked through step by step in Your first PV.

Install

pip install spvirit             # the Python module, plus the sp* tools
pip install spvirit-tools       # just the sp* command-line tools
cargo install spvirit-tools     # same tools, via a Rust toolchain

spvirit depends on spvirit-tools, so the first line gets you both: the importable module and the sp* binaries on your PATH, no compiler needed. The wheel includes the packet-capture tools spvirit-scry and spvirit-scry_influx_collector; on Windows they need the Npcap runtime and print a warning if it is missing. cargo install spvirit-tools builds the thirteen default tools.

To use the libraries from your own Rust project, add the layer you need:

[dependencies]
spvirit-client = "0.4"
spvirit-server = "0.4"

Building from source, and the feature flags that gate the binaries, are covered in Installation.

Tools

spvirit tool EPICS Base equivalent Description
spget pvget Fetch the current value of a PV
spput pvput Write a value to a PV
spmonitor pvmonitor Subscribe to a PV and print value changes
spinfo pvinfo Display field/metadata information for a PV
splist pvlist List all available PVs on discovered servers
spserver softIoc Not fully one-to-one: a demo, but it parses some .db vocabulary
spgateway pvagw PVAccess gateway: proxy PVs between networks from a p4p-schema config
sptable Interactive TUI IOC: build and drive records live
spexplore Interactive TUI to browse servers, select PVs, and monitor values
spsearch TUI showing PV search network traffic for diagnostics
spsine Continuously write a sine wave to a PV (demo/testing)
spget_compare Compare a captured GET exchange against spvirit's own encoders (offline)
spdodeca Server publishing a rotating 3D dodecahedron as an NTNDArray PV

spload, an internal load driver for the loadtest/ harness, is not a user-facing tool: it is not in the default build or the wheel, and builds only with --features load.

A page per tool, with real captured output, is at Command-line tools.

Examples

The repository carries runnable examples covering the main features: nearly thirty Rust examples under spvirit-{codec,client,server}/examples/ and over thirty Python scripts under spvirit-py/examples/. Each is walked through in Progressive examples, Rust and Python side by side.

cargo run -p spvirit-server --example simple_server   # terminal 1
spget SIM:TEMPERATURE                                  # terminal 2

Integration test matrix

I have tested the tools in this repo against the following EPICS PVAccess servers:

  • EPICS
  • p4p (pvxs under the hood)
  • PvAccessJava

Contributing

Internals (the codec, the record model, the server runtime, the bindings) are documented with file-and-line citations in the developer guide. Known divergences from EPICS Base behaviour are collected in Known gaps.

Related Projects

  • spvirit-scry: packet capture and analysis for PVAccess, now built into spvirit-tools: in the Python wheel (pip install spvirit-tools; Windows needs the Npcap runtime), or from source with cargo install spvirit-tools --features scry (needs libpcap on Linux or the Npcap SDK on Windows).

References

I used the following libraries and repos as reference materials for PVAccess protocol:

GenAI Usage Log

Section / Area What Was Done With AI Plans Ahead
spvirit-types Hand coded, few types completed with AI, then prettified with AI keep the same, fairly complete
spvirit-codec Most was hand-coded, some restructuring and prettifying was done with AI. keep the same, bring in any common helpers, maybe write a simplified API for users
spvirit-tools Mostly AI generated, manually coded parts of Put and Get then let the Agents build on top. Client and server logic has been split out into spvirit-client and spvirit-server crates. The APIs are now split idiomatically. Continued refinement of high-level convenience functions for put and monitor.
PvaClient / PvaServer High-level builder-pattern APIs (PvaClient::builder(), PvaServer::builder()) designed with AI assistance. Wraps protocol-level operations into single-call methods for get, put, monitor, info, and typed server records. Extend with more record types, structured put payloads, and TLS support.
Testing I wrote some basic tests, then used GenAI agents to generate more tests and test cases, which I then manually curated and edited. Suite is fairly comprehensive so I will keep it as is.
Documentation The documentation site was drafted with AI, with every code sample included verbatim from a compiled example and every claim checked against the source. Keep it verified by CI: cargo test -p spvirit-tools --test docs_verify.

Licence

Licensed under the terms in LICENSE.

About

pvAccess Protocol implementation in Rust

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages