Package: pvapy
PvaPy - PvAccess for PythonThe PvaPy package is a Python API for EPICS7. It supports both PVA and CA
providers, all standard EPICS7 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 EPICS7 C++ libraries and APIs,
and is currently supported on Linux, OSX and Windows.InstallationAt 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.CondaSupported platforms: Linux (64-bit), OSXSupported Python versions: Python2, Python3Make surecondacommand is in your path, and execute the following command:$condainstall-cepicspvapyThis should result in installation of pvapy, pvapy-boost and epics-base
Conda packages.PyPISupported platforms: Linux (64-bit), Windows (64-bit), OSX (64-bit), ARM (64-bit)Supported Python versions: Python2, Python3Make surepipcommand is in your path, and execute the following command:$pipinstallpvapyPvaPy pip packages contain all needed epics base and boost libraries.BuildThis section is intended for those users that would like to build PvaPy from
the source code.PrerequisitesBuilding PvaPy from source requires recent versions of the following software:Standard development tools (gcc, make, autoconf, etc.)Python development header files/libraries (>=v2.6.6)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 BuildAutomated 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/pathmakelocalThis 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 thetools/localsubdirectory of the PvaPy distribution.Custom BuildIn addition to the Python-related prerequsites, the custom build requires
the following software already built:EPICS Base (>=v3.14.12.3)EPICS4 CPP release (>=v4.4.0); note that EPICS7 release includes
all needed v4 modulesBoost (>=v1.41.0); must have the boost_python library builtBoost.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 PvaPyThis can be done manually (all platforms), or using autoconf (on Linux
and OSX).For manual configuration: Read the comments in both theconfigure/RELEASEandconfigure/CONFIG_SITEfiles and follow the instructions given there.For automatic configuration: In the top level directory run$makeconfigureEPICS_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/pathwith the full
path to your EPICS Base directory, and/epics/v4/pathwith 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 optionalBOOST_NUMPY_DIRargument enables NumPy array support for older
Boost versions, as v1.63.0 and later releases already include NumPy libraries.
The optionalBOOST_ROOTargument 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 abovemake configurecommand.
Also, note that building with python 3.x requires PYTHON_VERSION=3 argument.Themake configurecommand will check for your Boost/Python libraries, and
create suitableconfigure/RELEASE.localandconfigure/CONFIG_SITE.localfiles that are used by the build process. They should look roughly like the
examples below:$catRELEASE.localPVACLIENT=/home/epics/v4/pvaClientCPPPVDATABASE=/home/epics/v4/pvDatabaseCPPNORMATIVETYPES=/home/epics/v4/normativeTypesCPPPVACCESS=/home/epics/v4/pvAccessCPPPVDATA=/home/epics/v4/pvDataCPPEPICS_BASE=/home/epics/base-3.15.5$catCONFIG_SITE.localPVAPY_CPPFLAGS=-I/usr/include-I/usr/include/python2.7PVAPY_LDFLAGS=-L/usr/lib64-lpython2.7PVAPY_SYS_LIBS=boost_pythonPVA_API_VERSION=480PVA_RPC_API_VERSION=480HAVE_BOOST_NUMPY=0HAVE_BOOST_PYTHON_NUMPY=0PYTHON_VERSION=2.7PVAPY_PYTHON=/bin/pythonPVAPY_PYTHONPATH=/home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64PVAPY_LD_LIBRARY_PATH=/usr/lib64PVAPY_EPICS_BASE=/home/epics/base-3.15.5PVAPY_EPICS4_DIR=/home/epics/v4PVAPY_HOST_ARCH=linux-x86_64PVAPY_SETUP_SH=/home/epics/pvaPy/bin/linux-x86_64/pvapy_setup_full.2.7.shThe above files were created automatically on a 64-bit RHEL 7.4 machine, with
the following boost/python packages installed:$rpm-qboost-pythonpython-develboost-python-1.53.0-27.el7.x86_64python-devel-2.7.5-58.el7.x86_64Note that the automatic configuration process also createspvapy_setup_full.$PYTHON_VERSION.(c)shandpvapy_setup_pythonpath.$PYTHON_VERSION.(c)shfiles in thebin/$EPICS_HOST_ARCHdirectory. The full setup files modify PATH,
LD_LIBRARY_PATH and PYTHONPATH environment variables, while the pythonpath
setup files modify only PYTHONPATH variable. For example,$catpvapy_setup_pythonpath.2.7.sh#!/bin/sh## modifies PYTHONPATH environment variable#iftest-z"$PYTHONPATH";thenexportPYTHONPATH=/home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64elseexportPYTHONPATH=/home/epics/v4/pvaPy/lib/python/2.7/linux-x86_64:$PYTHONPATHfiAfter 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_64or 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_642. Compile PvaPy SourceIn the top level package directory run:$makeThe above command will create and install a loadable librarypvaccess.sounder thelib/pythondirectory which can be imported directly by Python.3. Generate DocumentationThis step is optional and requires Sphinx to be installed:$makedocIf asphinx-buildscript is present on the system, html pages will be
generated in thedocumentation/sphinx/_build/htmldirectory.Basic Usage: PV put/getFor simple testing, do the following:In a separate terminal, start the testDbPv IOC:$cd$EPICS4_DIR/pvaSrv/testTop/iocBoot/testDbPv$../../bin/$EPICS_HOST_ARCH/testDbPvst.cmdSource the appropriate setup file from pvaPy'sbin/$EPICS_HOST_ARCHdirectory 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 5In 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 monitorIn a separate terminal, start the testDbPv IOC:$cd$EPICS4_DIR/pvaSrv/testTop/iocBoot/testDbPv$../../bin/$EPICS_HOST_ARCH/testDbPvst.cmdPV values can be changed using the IOC shell commanddbpf, 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.1Monitor a channel in Python, passing in a subscriber object (function
that processes PvObject instance):>>>c=pvaccess.Channel('float01')>>>defecho(x):...print'New PV value:',x...>>>c.subscribe('echo',echo)>>>c.startMonitor()>>>NewPVvalue:epics:nt/NTScalar:1.0floatvalue11.1NewPVvalue:epics:nt/NTScalar:1.0floatvalue11.2NewPVvalue:epics:nt/NTScalar:1.0floatvalue11.3>>>c.stopMonitor()Advanced Usage: PVA Server ClassIn terminal 1, create a simple 'pair' channel:$ python 
  >>> pv = PvObject({'x': INT, 'y' : INT})
  >>> pvaServer = PvaServer('pair', pv)In terminal 2, start monitoring this channel:$ pvget -m pairIn terminal 1, update one of the object's fields:>>> pv['x'] = 1This change should appear in terminal 2.Advanced Usage: RPC Client ClassIn a separate terminal, start the v4 test RPC service:$cd$EPICS4_DIR/pvAccessCPP/bin/$EPICS_HOST_ARCH$./rpcServiceExample# in terminal 2RPC test channel is 'sum':>>>rpc=pvaccess.RpcClient('sum')>>>request=pvaccess.PvObject({'a':pvaccess.STRING,'b':pvaccess.STRING})>>>request.set({'a':'11','b':'22'})>>>printrequeststructurestringa11stringb22>>>response=rpc.invoke(request)>>>printresponsestructuredoublec33Advanced Usage: RPC Server ClassExample 1In 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()In terminal 1, reuse previous request object>>>rpc=pvaccess.RpcClient('echo')>>>response=rpc.invoke(request)>>>printresponsestructurestringa11stringb22Example 2In 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()In terminal 1:>>>rpc=pvaccess.RpcClient('sum')>>>request=pvaccess.PvObject({'a':pvaccess.INT,'b':pvaccess.INT})>>>request.set({'a':11,'b':22})>>>printrequeststructureinta11intb22>>>response=rpc.invoke(request)>>>printresponsestructureintvalue33Example 3In terminal 2:>>>importpvaccess>>>srv=pvaccess.RpcServer()>>>defhash(x):...importhashlib...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)...returnresponse>>>srv.registerService('hash',hash)>>>srv.listen()In terminal 1:>>>rpc=pvaccess.RpcClient('hash')>>>request=pvaccess.PvString('abcd')>>>printrpc.invoke(request)structurestringhash0a380e7375d8c3f68d1bbe068141d6cestringvalue