PVXS Quick Start Guide

This guide will help you get started with PVXS in minutes. We’ll walk through installing PVXS and running simple client and server examples.

Prerequisites

Before starting, ensure you have:

  • EPICS Base >= 3.15.1 installed and built

  • A C++11 compliant compiler (GCC >= 4.8, Clang >= 3.3, or Visual Studio >= 2015)

  • libevent >= 2.0.1 (or build bundled version)

Step 1: Install PVXS

Quick Installation

# Clone EPICS Base (if not already done)
git clone --branch 7.0 https://github.com/epics-base/epics-base.git
cd epics-base
make
cd ..

# Clone PVXS
git clone --recursive https://github.com/epics-base/pvxs.git
cd pvxs

# Configure PVXS
cat <<EOF > configure/RELEASE.local
EPICS_BASE=\$(TOP)/../epics-base
EOF

# Install system libevent (recommended)
# On Debian/Ubuntu:
sudo apt-get install libevent-dev
# On RHEL/CentOS:
sudo yum install libevent-devel
# On macOS:
brew install libevent

# Build PVXS
make

For detailed installation instructions, see :doc:guides/installation.

Step 2: Verify Installation

Check that PVXS built successfully:

# Run unit tests (recommended)
make runtests

# Check that tools were built
ls -la O.*/bin/pvx*

Step 3: Run Your First Server

In one terminal, start a simple server:

cd example
make
./O.linux-x86_64/simplesrv

You should see output indicating the server is running. The server creates a PV named my:pv:name with a double value of 42.0.

What’s happening:

The server code (see simplesrv.cpp <../example/simplesrv.cpp>_) does the following:

  1. Creates an NTScalar structure (a standard EPICS type) with a double value

  2. Sets an initial value of 42.0

  3. Creates a mailbox PV (stores whatever clients send)

  4. Opens the PV with the initial value

  5. Adds the PV to a server configured from environment variables

  6. Runs the server (blocks until Ctrl+C)

Step 4: Connect with a Client

In another terminal, run the simple client:

cd example
./O.linux-x86_64/simpleget my:pv:name

You should see the PV value printed to stdout.

What’s happening:

The client code (see simpleget.cpp <../example/simpleget.cpp>_) does the following:

  1. Creates a client context configured from environment variables

  2. Initiates a GET operation for the PV name

  3. Waits up to 5 seconds for the response

  4. Prints the received value

Step 5: Modify and Experiment

Try Changing the Value

In the client terminal, you can use the command-line tools:

# Get the value
pvxget my:pv:name

# Put a new value
pvxput my:pv:name 99.5

# Get it again to see the change
pvxget my:pv:name

# Monitor for changes (press Ctrl+C to stop)
pvxmonitor my:pv:name

Try the Mailbox Example

The mailbox server (see mailbox.cpp <../example/mailbox.cpp>_) includes a PUT handler with validation:

# Terminal 1: Start mailbox server
cd example
./O.linux-x86_64/mailbox test:pv:1

# Terminal 2: Use the client example to interact
./O.linux-x86_64/client test:pv:1

The mailbox server:

  • Validates PUT values (clips to range [-100.0, 100.0])

  • Adds timestamps automatically

  • Notifies subscribers when values change

Understanding the Code

Client Example Breakdown

#include <pvxs/client.h>
#include <pvxs/log.h>

int main() {
    using namespace pvxs;
    
    // Configure client from environment ($EPICS_PVA_*)
    auto ctxt = client::Context::fromEnv();
    
    // Get a PV value (blocking)
    Value result = ctxt.get("some:pv:name")
                   .exec()      // Start the operation
                   ->wait(5.0); // Wait up to 5 seconds
    
    std::cout << result << std::endl;
    return 0;
}

Key concepts:

  • Context::fromEnv() - Creates client configured from $EPICS_PVA_* environment variables

  • .get("pv:name") - Creates a GetBuilder for the named PV

  • .exec() - Starts the network operation, returns an Operation handle

  • .wait(5.0) - Blocks until operation completes or timeout

See :doc:api/client for detailed documentation.

Server Example Breakdown

#include <pvxs/server.h>
#include <pvxs/sharedpv.h>
#include <pvxs/nt.h>

int main() {
    using namespace pvxs;
    
    // Create an NTScalar structure with double value
    Value initial = nt::NTScalar{TypeCode::Float64}.create();
    initial["value"] = 42.0;
    
    // Create a mailbox PV (stores client PUTs)
    server::SharedPV pv(server::SharedPV::buildMailbox());
    pv.open(initial);  // Set the data type and initial value
    
    // Create server and add PV
    server::Server::fromEnv()    // Configure from environment
        .addPV("my:pv:name", pv) // Register the PV
        .run();                  // Run until SIGINT
    
    return 0;
}

Key concepts:

  • nt::NTScalar{TypeCode::Float64} - Creates a standard EPICS scalar type

  • SharedPV::buildMailbox() - Creates a PV that stores PUT values

  • .open(initial) - Sets the data type and initial value

  • Server::fromEnv() - Creates server configured from environment variables

  • .run() - Starts server and blocks until interrupted

See :doc:api/server for detailed documentation.

Next Steps

Now that you have PVXS working, explore further:

  1. Read the Full Documentation:

    • README.md <../README.md>_ - Overview and features (external reference)

    • :doc:guides/architecture - System design

    • :doc:api/overview - Complete API reference overview

  2. Explore Examples:

    • client.cpp <../example/client.cpp>_ - Comprehensive client demo

    • mailbox.cpp <../example/mailbox.cpp>_ - Server with PUT validation

    • rpc_client.cpp <../example/rpc_client.cpp>_ and rpc_server.cpp <../example/rpc_server.cpp>_ - RPC examples

    • ticker.cpp <../example/ticker.cpp>_ - Periodic updates

  3. Learn About:

    • :doc:reference/netconfig - Configuring network settings

    • :doc:api/value - Working with data structures

    • :doc:api/ioc - Integrating with EPICS IOCs

  4. Build Your Application:

    • See :doc:guides/installation for including PVXS in your project

    • Check :doc:guides/troubleshooting if you encounter issues

Common Issues

Server not found:

  • Check that server is running

  • Verify $EPICS_PVA_ADDR_LIST environment variable (if needed)

  • Check firewall settings (ports 5075 TCP, 5076 UDP)

Connection timeout:

  • Verify network connectivity

  • Check server logs for errors

  • Ensure client and server are on same network (or configure addresses explicitly)

Build errors:

  • See :doc:guides/installation for troubleshooting

  • Check that EPICS Base is built and accessible

  • Verify libevent is installed

For more troubleshooting help, see :doc:guides/troubleshooting.

Additional Resources

Acknowledgments

This quick start guide was created and organized by K. Gofron, Oak Ridge National Laboratory, December 28, 2025.