Skip to main content

Python library for EPICS PV Access

Project description

PvaPy - PvAccess for Python

The PvaPy package is a Python API for EPICS4. It supports both PVA and CA providers, all standard EPICS4 types (structures, scalars, unions, etc), standard set of channel operations (put/get, monitor), RPC client/server, PVA server, etc. It uses Boost/Python to wrap EPICS4 C++ libraries and APIs, and is currently supported on the Unix-like operating systems (Linux, OSX).

Installation

At the moment prebuilt PvaPy packages exist for the Conda and PyPI package management system. If none of the prebuilt packages work for you, or if you need 32-bit Linux packages, you will have to build PvaPy from sources.

Conda

  • Supported platforms: Linux (64-bit), OSX
  • Supported Python versions: Python2, Python3

Make sure conda command is in your path, and execute the following command:

  $ conda install -c epics pvapy

This should result in installation of pvapy, pvapy-boost and epics-base Conda packages.

PyPI

  • Supported platforms: Linux (64-bit), Windows (64-bit)
  • Supported Python versions: Python2, Python3

Make sure pip command is in your path, and execute the following command:

  $ pip install pvapy

PvaPy pip packages contain all needed epics base and boost libraries.

Build

This section is intended for those users that would like to build PvaPy from the source code.

Prerequisites

Building PvaPy from source requires recent versions of the following software:

  1. Standard development tools (gcc, make, autoconf, etc.)
  2. Python development header files/libraries (>=v2.6.6)
  3. Sphinx/Sphinx RTD Theme (optional, for generating documentation)

There are two ways of building and installing PvaPy from sources: automated and custom. The automated local install will download and build predefined versions of EPICS Base, Boost and PvaPy. Custom local install relies on already existing EPICS Base and Boost libraries, and builds only PvaPy.

Automated Build

Automated build works under Linux and OSX. Make sure the desired version of Python is in your path, and execute the following command from the top of the PvaPy source directory:

  $ PREFIX=/local/install/path make local

This should build and install predefined versions of EPICS Base, Boost Python and PvaPy libraries under the directory specified by the PREFIX variable. If PREFIX is not specified, all software will be installed under the tools/local subdirectory of the PvaPy distribution.

Custom Build

In addition to the Python-related prerequsites, the custom build requires the following software already built:

  1. EPICS Base (>=v3.14.12.3)
  2. EPICS4 CPP release (>=v4.4.0); note that EPICS7 release includes all needed v4 modules
  3. Boost (>=v1.41.0); must have the boost_python library built
  4. Boost.NumPy (optional, for retrieving numeric scalar arrays as numpy arrays; this is not needed for Boost v1.63.0 and later)

The version numbers mentioned above are the earliest that PvaPy was tested with. Any recent version of Python and the Boost libraries (such as those that come with current linux distributions) should work. Similarly, any recent version of EPICS Base that is supported by EPICS4 CPP should be fine.

Nothing special needs to be done when building the EPICS4 CPP modules. Ensure that the EPICS Base installation you use for this module is the same one that was used to build the EPICS4 modules.

This module has not been adapted for use on Microsoft Windows. Only Unix-like operating systems (e.g. Linux, MacOS, Solaris) are currently supported.

1. Configure PvaPy

This can be done manually (all platforms), or using autoconf (on Linux and OSX).

For manual configuration: Read the comments in both the configure/RELEASE and configure/CONFIG_SITE files and follow the instructions given there.

For automatic configuration: In the top level directory run

  $ make configure EPICS_BASE=/epics/base/path [EPICS4_DIR=/epics/v4/path] [BOOST_NUMPY_DIR=/boost.numpy/path] [BOOST_ROOT=/boost/path] [PYTHON_VERSION=3]

Note that you can only use the automatic configuration if the v4 modules have not been renamed. In the above command replace /epics/base/path with the full path to your EPICS Base directory, and /epics/v4/path with the full path to your top level directory containing the v4 modules pvDataCPP, pvAccessCPP, etc. If you are using EPICS7 release, you can omit EPICS4_DIR argument, as configuration scripts will find the required v4 libraries and header files in the EPICS Base directory.

The optional BOOST_NUMPY_DIR argument enables NumPy array support for older Boost versions, as v1.63.0 and later releases already include NumPy libraries. The optional BOOST_ROOT argument is typically used for custom Boost installation directory. In case you are using custom python installation that uses shared object libraries, you may need to set PATH and LD_LIBRARY_PATH environment variables before running the above make configure command. Also, note that building with python 3.x requires PYTHON_VERSION=3 argument.

The make configure command will check for your Boost/Python libraries, and create suitable configure/RELEASE.local and configure/CONFIG_SITE.local files that are used by the build process. They should look roughly like the examples below:

  $ cat RELEASE.local
  PVACLIENT = /home/epics/v4/pvaClientCPP
  PVDATABASE = /home/epics/v4/pvDatabaseCPP
  NORMATIVETYPES = /home/epics/v4/normativeTypesCPP
  PVACCESS = /home/epics/v4/pvAccessCPP
  PVDATA = /home/epics/v4/pvDataCPP
  EPICS_BASE = /home/epics/base-3.15.5

  $ cat CONFIG_SITE.local
  PVAPY_CPPFLAGS = -I/usr/include -I/usr/include/python2.7
  PVAPY_LDFLAGS = -L/usr/lib64 -lpython2.7
  PVAPY_SYS_LIBS = boost_python  
  PVA_API_VERSION = 480
  PVA_RPC_API_VERSION = 480
  HAVE_BOOST_NUMPY = 0
  HAVE_BOOST_PYTHON_NUMPY = 0
  PYTHON_VERSION = 2.7
  PVAPY_PYTHON = /bin/python
  PVAPY_PYTHONPATH = /home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64
  PVAPY_LD_LIBRARY_PATH = /usr/lib64
  PVAPY_EPICS_BASE = /home/epics/base-3.15.5
  PVAPY_EPICS4_DIR = /home/epics/v4
  PVAPY_HOST_ARCH = linux-x86_64
  PVAPY_SETUP_SH = /home/epics/pvaPy/bin/linux-x86_64/pvapy_setup_full.2.7.sh

The above files were created automatically on a 64-bit RHEL 7.4 machine, with the following boost/python packages installed:

  $ rpm -q boost-python python-devel
  boost-python-1.53.0-27.el7.x86_64
  python-devel-2.7.5-58.el7.x86_64

Note that the automatic configuration process also creates pvapy_setup_full.$PYTHON_VERSION.(c)sh and pvapy_setup_pythonpath.$PYTHON_VERSION.(c)sh files in the bin/$EPICS_HOST_ARCH directory. The full setup files modify PATH, LD_LIBRARY_PATH and PYTHONPATH environment variables, while the pythonpath setup files modify only PYTHONPATH variable. For example,

  $ cat pvapy_setup_pythonpath.2.7.sh
  #!/bin/sh
  #
  # modifies PYTHONPATH environment variable
  #
  if test -z "$PYTHONPATH" ; then
      export PYTHONPATH=/home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64
  else
      export PYTHONPATH=/home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64:$PYTHONPATH
  fi

After building pvaPy, the environment setup files can be sourced to use the built python module, e.g.:

  $ . /home/epics/v4/pvaPy/bin/linux-x86_64/pvapy_setup_pythonpath.2.7.sh
  $ echo $PYTHONPATH
  /home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64

or for csh users:

  % source /home/epics/v4/pvaPy/bin/linux-x86_64/pvapy_setup_pythonpath.2.7.csh
  % echo $PYTHONPATH
  /home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64

2. Compile PvaPy Source

In the top level package directory run:

  $ make

The above command will create and install a loadable library pvaccess.so under the lib/python directory which can be imported directly by Python.

3. Generate Documentation

This step is optional and requires Sphinx to be installed:

  $ make doc

If a sphinx-build script is present on the system, html pages will be generated in the documentation/sphinx/_build/html directory.

Basic Usage: PV put/get

For simple testing, do the following:

  1. In a separate terminal, start the testDbPv IOC:
  $ cd $EPICS4_DIR/pvaSrv/testTop/iocBoot/testDbPv
  $ ../../bin/$EPICS_HOST_ARCH/testDbPv st.cmd
  1. Source the appropriate setup file from pvaPy's bin/$EPICS_HOST_ARCH directory and start python (the Python PVA module is called pvaccess):
  $ python
  >>> import pvaccess
  >>> dir (pvaccess)
  ['BOOLEAN', 'BYTE', 'CA', 'Channel', 'DOUBLE', 'FLOAT', 'FieldNotFound',
  'INT', 'InvalidArgument', 'InvalidDataType', 'InvalidRequest', 'LONG',
  'NtTable', 'NtType', 'PVA', 'ProviderType', 'PvAlarm', 'PvBoolean', 'PvByte',
  'PvDouble', 'PvFloat', 'PvInt', 'PvLong', 'PvObject', 'PvScalar',
  'PvScalarArray', 'PvShort', 'PvString', 'PvTimeStamp', 'PvType', 'PvUByte',
  'PvUInt', 'PvULong', 'PvUShort', 'PvUnion', 'PvaException', 'RpcClient',
  'RpcServer', 'SHORT', 'STRING', 'UBYTE', 'UINT', 'ULONG', 'USHORT', '__doc__',
  '__file__', '__name__', '__package__']
  >>> c = pvaccess.Channel('int01')
  >>> print c.get()
  epics:nt/NTScalar:1.0
      int value 0
  >>> c.putInt(7)
  >>> print c.get()
  epics:nt/NTScalar:1.0
      int value 7
  >>> c.put(pvaccess.PvInt(5))
  >>> print c.get()
  epics:nt/NTScalar:1.0
      int value 5

In the above, note that in addition to PV object classes like PvInt, one can also use standard Python types as arguments for channel puts.

Basic Usage: PV monitor

  1. In a separate terminal, start the testDbPv IOC:
  $ cd $EPICS4_DIR/pvaSrv/testTop/iocBoot/testDbPv
  $ ../../bin/$EPICS_HOST_ARCH/testDbPv st.cmd
  1. PV values can be changed using the IOC shell command dbpf, e.g:
  epics> dbpr 'float01'
  ASG:                DESC:               DISA: 0             DISP: 0
  DISV: 1             NAME: float01       SEVR: MAJOR         STAT: LOLO
  TPRO: 0             VAL: 0
  epics> dbpf 'float01' 11.1
  DBR_FLOAT:          11.1
  1. Monitor a channel in Python, passing in a subscriber object (function that processes PvObject instance):
  >>> c = pvaccess.Channel('float01')
  >>> def echo(x):
  ...     print 'New PV value:', x
  ...
  >>> c.subscribe('echo', echo)
  >>> c.startMonitor()
  >>> New PV value: epics:nt/NTScalar:1.0
      float value 11.1

  New PV value: epics:nt/NTScalar:1.0
      float value 11.2

  New PV value: epics:nt/NTScalar:1.0
      float value 11.3

  >>> c.stopMonitor()

Advanced Usage: PVA Server Class

  1. In terminal 1, create a simple 'pair' channel:
  $ python 
  >>> pv = PvObject({'x': INT, 'y' : INT})
  >>> pvaServer = PvaServer('pair', pv)
  1. In terminal 2, start monitoring this channel:
  $ pvget -m pair
  1. In terminal 1, update one of the object's fields:
  >>> pv['x'] = 1

This change should appear in terminal 2.

Advanced Usage: RPC Client Class

  1. In a separate terminal, start the v4 test RPC service:
  $ cd $EPICS4_DIR/pvAccessCPP/bin/$EPICS_HOST_ARCH
  $ ./rpcServiceExample # in terminal 2
  1. RPC test channel is 'sum':
  >>> rpc = pvaccess.RpcClient('sum')
  >>> request = pvaccess.PvObject({'a': pvaccess.STRING, 'b': pvaccess.STRING})
  >>> request.set({'a': '11', 'b': '22' })
  >>> print request
  structure
      string a 11
      string b 22
  >>> response = rpc.invoke(request)
  >>> print response
  structure
      double c 33

Advanced Usage: RPC Server Class

Example 1

  1. In a separate terminal, source the environment file and start python:
  $ python # in terminal 2
  >>> import pvaccess
  >>> srv = pvaccess.RpcServer()
  >>> def echo(x):    # x is an instance of PvObject
  ...     print 'Got object: ', x
  ...     return x    # service must return an instance of PvObject
  >>> srv.registerService('echo', echo)
  >>> srv.listen()
  1. In terminal 1, reuse previous request object
  >>> rpc = pvaccess.RpcClient('echo')
  >>> response = rpc.invoke(request)
  >>> print response
  structure
      string a 11
      string b 22

Example 2

  1. In terminal 2:
  $ python
  >>> import pvaccess
  >>> srv = pvaccess.RpcServer()
  >>> def sum(x):
  ...     a = x.getInt('a')
  ...     b = x.getInt('b')
  ...     return pvaccess.PvInt(a+b)
  >>> srv.registerService('sum', sum)
  >>> srv.listen()
  1. In terminal 1:
  >>> rpc = pvaccess.RpcClient('sum')
  >>> request = pvaccess.PvObject({'a': pvaccess.INT, 'b': pvaccess.INT})
  >>> request.set({'a': 11, 'b': 22})
  >>> print request
  structure
      int a 11
      int b 22
  >>> response = rpc.invoke(request)
  >>> print response
  structure
      int value 33

Example 3

  1. In terminal 2:
  >>> import pvaccess
  >>> srv = pvaccess.RpcServer()
  >>> def hash(x):
  ...     import hashlib
  ...     md5 = hashlib.md5()
  ...     md5.update(str(x))
  ...     h = md5.hexdigest()
  ...     dict = x.getStructureDict()
  ...     dict['hash'] = pvaccess.STRING
  ...     response = pvaccess.PvObject(dict)
  ...     response.setString('hash', h)
  ...     return response
  >>> srv.registerService('hash', hash)
  >>> srv.listen()
  1. In terminal 1:
  >>> rpc = pvaccess.RpcClient('hash')
  >>> request = pvaccess.PvString('abcd')
  >>> print rpc.invoke(request)
  structure
      string hash 0a380e7375d8c3f68d1bbe068141d6ce
      string value

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

pvapy-3.0.0-cp38-cp38-win_amd64.whl (2.3 MB view details)

Uploaded CPython 3.8 Windows x86-64

pvapy-3.0.0-cp38-cp38-manylinux1_x86_64.whl (12.9 MB view details)

Uploaded CPython 3.8

pvapy-3.0.0-cp37-cp37m-manylinux1_x86_64.whl (12.9 MB view details)

Uploaded CPython 3.7m

pvapy-3.0.0-cp36-cp36m-manylinux1_x86_64.whl (12.9 MB view details)

Uploaded CPython 3.6m

pvapy-3.0.0-cp35-cp35m-manylinux1_x86_64.whl (12.9 MB view details)

Uploaded CPython 3.5m

pvapy-3.0.0-cp34-cp34m-manylinux1_x86_64.whl (12.9 MB view details)

Uploaded CPython 3.4m

pvapy-3.0.0-cp27-cp27mu-manylinux1_x86_64.whl (12.9 MB view details)

Uploaded CPython 2.7mu

pvapy-3.0.0-cp27-cp27m-manylinux1_x86_64.whl (12.9 MB view details)

Uploaded CPython 2.7m

File details

Details for the file pvapy-3.0.0-cp38-cp38-win_amd64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp38-cp38-win_amd64.whl
  • Upload date:
  • Size: 2.3 MB
  • Tags: CPython 3.8, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/47.1.0 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5

File hashes

Hashes for pvapy-3.0.0-cp38-cp38-win_amd64.whl
Algorithm Hash digest
SHA256 ac196dafec233b42a50396ea47253b5ff392231c15e9f76d4dcdd078817452f7
MD5 ec9af2d508e2d56df5ec30e62e9bf417
BLAKE2b-256 b25675d4ecafed30ec5d090a737c0e1f0699e6b9d46401fedc420159fbaa0063

See more details on using hashes here.

File details

Details for the file pvapy-3.0.0-cp38-cp38-manylinux1_x86_64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp38-cp38-manylinux1_x86_64.whl
  • Upload date:
  • Size: 12.9 MB
  • Tags: CPython 3.8
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.6

File hashes

Hashes for pvapy-3.0.0-cp38-cp38-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 3989d754232ab6cdf3da40d259844ed076bc1bb51868c3231d8e6c1be2f0ae22
MD5 fc2292611db604e6426571a016b74407
BLAKE2b-256 58555e0704979e22d27362a45fda59aa63ced408eface2aff1fdddb9718a5bfb

See more details on using hashes here.

File details

Details for the file pvapy-3.0.0-cp37-cp37m-manylinux1_x86_64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp37-cp37m-manylinux1_x86_64.whl
  • Upload date:
  • Size: 12.9 MB
  • Tags: CPython 3.7m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.6

File hashes

Hashes for pvapy-3.0.0-cp37-cp37m-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 10c75bf1dbf9eaeca29f7f0cb9c240dd0c649d9058d8f2353ecf23befd3f1556
MD5 7b19e869dff5bb82d63f0fab06e65364
BLAKE2b-256 24ce301e0bd5d1957b2d10744237462f86dd28ba608b50e2ae7fda1ccc7bb305

See more details on using hashes here.

File details

Details for the file pvapy-3.0.0-cp36-cp36m-manylinux1_x86_64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp36-cp36m-manylinux1_x86_64.whl
  • Upload date:
  • Size: 12.9 MB
  • Tags: CPython 3.6m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.6

File hashes

Hashes for pvapy-3.0.0-cp36-cp36m-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 95c79b0c20fd73cc360d9cf21169c92e34164d26a47fb8ebe67795bfd4df0b6c
MD5 88bcb6b0797d5d18f3064dfdb84c43f8
BLAKE2b-256 8188b7062f913da09b56b648b0596e55c61e51f9ac977be50cbca7af1bbcd4aa

See more details on using hashes here.

File details

Details for the file pvapy-3.0.0-cp35-cp35m-manylinux1_x86_64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp35-cp35m-manylinux1_x86_64.whl
  • Upload date:
  • Size: 12.9 MB
  • Tags: CPython 3.5m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.6

File hashes

Hashes for pvapy-3.0.0-cp35-cp35m-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 e8b1d1c59b54f34233f8155ede80bb76a90c821b405d326447dab5f03393a0fd
MD5 53c0a16ce01059bfd811f2675059148c
BLAKE2b-256 2f44e8cf2b5435a7188c8d7e2a94eb97363ae2a18e4d606a858da15f9139ef3e

See more details on using hashes here.

File details

Details for the file pvapy-3.0.0-cp34-cp34m-manylinux1_x86_64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp34-cp34m-manylinux1_x86_64.whl
  • Upload date:
  • Size: 12.9 MB
  • Tags: CPython 3.4m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.6

File hashes

Hashes for pvapy-3.0.0-cp34-cp34m-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 6f628bce45d2c27a58193c1cec128b2395edaf13faf854248ae5a793814c3c9a
MD5 4453d946916c3e3b5e6765af5765b71e
BLAKE2b-256 9fd9f6a36a76e08e8f3984820cb33068f153f6fb84fe042c0568ab44a4017b2b

See more details on using hashes here.

File details

Details for the file pvapy-3.0.0-cp27-cp27mu-manylinux1_x86_64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp27-cp27mu-manylinux1_x86_64.whl
  • Upload date:
  • Size: 12.9 MB
  • Tags: CPython 2.7mu
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.6

File hashes

Hashes for pvapy-3.0.0-cp27-cp27mu-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 265b9a60288736d57692de8c47543b5d68a34eba5648fb2300d9d198ff39f93f
MD5 f8ab6d48e2db9293896016f6aa3ea009
BLAKE2b-256 faf6dfe204b51962f1dc29a60849c2b52eefb244f2eab0d05ceaecddcd748742

See more details on using hashes here.

File details

Details for the file pvapy-3.0.0-cp27-cp27m-manylinux1_x86_64.whl.

File metadata

  • Download URL: pvapy-3.0.0-cp27-cp27m-manylinux1_x86_64.whl
  • Upload date:
  • Size: 12.9 MB
  • Tags: CPython 2.7m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.41.1 CPython/3.7.6

File hashes

Hashes for pvapy-3.0.0-cp27-cp27m-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 553d90df5cbcbe721a1a89efc88b7911c5440691a8bde25582a6d06f076c8adc
MD5 f2bd6a85c3ee55992b15f59ad1395b78
BLAKE2b-256 5469a627fac9bedba0e41ae11d3cff45c1a738029b8e154c02488d03f3ab957a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page