Spvirit

/ˈspɪrɪt/ of the Machine

Spvirit is a Rust library for working with EPICS PVAccess protocol, including encoding/decoding and connection state tracking. It also includes tools for monitoring and testing PVAccess connections. These are not yet production ready , but they are available for anyone to use and contribute to.

Key areas of development in the near future include:

• More complete support for EPICS Normative Types (NT) and their associated metadata.
• softIOC-like server functionality, including parsing of EPICS db files and support for more complex PV types and behaviors, a prototype of which is already available in the spserver tool.

Why Rust?

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

Project Structure

The project is structured as a Cargo workspace with three crates:

• spvirit-types: Contains shared data model types for PVAccess Normative Types (NT).
• spvirit-codec: Contains the PVAccess protocol encoding/decoding logic and connection state tracking.
• spvirit-tools: Contains command-line tools for monitoring and testing PVAccess connections.

In the future I would like to split out the tools to client and server tools and add some more IOC-like functionality to the server tools, but for now they are all in one crate for simplicity.

Getting Started

Install Rust

# Linux

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

clone the repo

git clone https://github.com/ISISNeutronMuon/spvirit

Build the project

cd spvirit

cargo build --release

Run the tools

cargo run --bin spmonitor my:pv:name

# or

./target/release/spmonitor my:pv:name

# or if installed 

cargo install spvirit-tools


spmonitor my:pv:name

Using the library in your own Rust project

Add the crates you need to your Cargo.toml:

[dependencies]

spvirit-tools = "0.1"    # client/server library + CLI tools

spvirit-codec = "0.1"    # low-level PVA protocol encode/decode

spvirit-types = "0.1"    # shared Normative Type data model

Fetching a PV value (client)

use spvirit_tools::{format_output, pvget, PvGetOptions, RenderOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pv_name = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "MY:PV:NAME".into());

    let opts = PvGetOptions::new(pv_name);
    let result = pvget(&opts).await?;

    let render = RenderOptions::default();
    println!("{}", format_output(&result.pv_name, &result.value, &render));
    Ok(())
}

Searching for a PV server

use std::time::Duration;
use spvirit_tools::{build_auto_broadcast_targets, search_pv};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let pv_name = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "MY:PV:NAME".into());

    let targets = build_auto_broadcast_targets();

    let addr = search_pv(&pv_name, 5076, Duration::from_secs(5), &targets, false).await?;
    println!("Found server at {addr}");
    Ok(())
}

Decoding a raw PVA packet (codec)

use spvirit_codec::{PvaPacket, PvaPacketCommand};

fn main() {
    let raw: &[u8] = &[
        0xCA, 0x02, 0x00, 0x01, // header: magic, version, flags (LE), command 1
        0x09, 0x00, 0x00, 0x00, // payload length = 9
        0x00, 0x40, 0x00, 0x00, // buffer_size = 16384
        0xFF, 0x7F,             // introspection_registry_size = 32767
        0x00, 0x00,             // qos = 0
        0x00,                   // authz = "" (empty string)
    ];

    let mut packet = PvaPacket::new(raw);

    println!("command: {}", packet.header.command);
    println!("endian:  {}", if packet.header.flags.is_msb { "big" } else { "little" });

    if let Some(cmd) = packet.decode_payload() {
        match cmd {
            PvaPacketCommand::ConnectionValidation(cv) => {
                println!("buffer_size: {}", cv.buffer_size);
            }
            other => println!("{other:?}"),
        }
    }
}

See the examples/ folders for runnable versions of each snippet:

cargo run --example pvget_example -p spvirit-tools MY:PV:NAME      # requires a running IOC

cargo run --example search_example -p spvirit-tools MY:PV:NAME     # requires a running IOC

cargo run --example decode_packet -p spvirit-codec       # self-contained, no IOC needed

Tools available

Server (softIOC like experiment)

While not a full softIOC implementation, spserver is a simple PVAccess server that can serve some static PVs and parse a limited subset of EPICS db file syntax. It proves that the encoding/decoding and connection handling logic in spvirit-codec is sufficient to implement a server, and it can be used as a starting for a more full featured softIOC in the future. (hint hint PRs welcome :))

Integration test matrix

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

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

Related Projects

• spvirit-scry — A Rust tool for capturing and analyzing pvAccess EPICS packets.

References

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

• pvxs
• pvAccess Protocol Specification
• EPICS Base
• PVAshark

GenAI Usage Log