1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
.. _pyepics github repository: https://github.com/pyepics/pyepics
.. _PyPi: https://pypi.python.org/pypi/pyepics/
====================================
Downloading and Installation
====================================
Installation
~~~~~~~~~~~~~~~~~~~~~~~
The latest stable version of the pyepics package is |release| which can be
installed with::
pip install pyepics
If you're using Anaconda Python, there are a few conda channels that
provide the latest versions, but the version on `PyPI`_ should be considered
the reference version.
PyEpics |release| works with Python version 3.10 and higher. It may
still work with older versions of Python, but no testing or support is
available for these. At this writing, automated testing is done with
versions 3.10 through 3.14 on 64-bit Linux, though Pyepics is
supported and regularly used on 64-bit Linux, 64-bit Windows, 64-bit
Mac OSX with both Intel and Arm processors. PyEpics should also work
on Linux with ARM processors including raspberry Pi and may still work
on 32-bit Windows and Linux, though these systems are not tested
regularly.
Prerequisites and Dependencies, Supported Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pyepics requires the EPICS Channel Access library from Epics Base
Version 3.14.12 or higher. Using Epics Base 7.0.4 or higher is
strongly recommended. More specifically, pyepics needs only to be
able to find the shared libraries *libca* and *libCom* (*libca.so* and
*libCom.so* on Linux, *libca.dylib* and *libCom.dylib* on Mac OSX, or
*ca.dll* and *Com.dll* on Windows) from *Epics Base*.
For Linux64, Linux32, LinuxArm, Windows64, Windows32, Darwin64 (MacOS)
on x86-64, and Darwin64 (MacOS) on arm64, pre-built versions of
*libca* (and *libCom*) are provided with pyepics. These will be
installed with the python packages directory and will used by
default. This means that you do not need to separately install Epics
base libraries or any other packages to use pyepics. These libraries
have been built with 3.16.2 or 7.0.7 - further details are given in
the `clibs` folder of the source kit. For Epics experts who may want
to use their own versions the *libca* from Epics base, instructions
for how to do this are given below.
The Python `numpy <https://numpy.org/>`_ module is highly
recommended. and will be used to automatically convert between EPICS
waveforms and numpy arrays if available.
The `autosave` module requires the `pyparsing` package, which is widely
available and often installed by default with many Python distributions.
The `wx` module requires the `wxPython` package, and the `qt` module
requires `PyQt` or `PySide`.
Getting Started, Setting up the Epics Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pyepics will find and load the Channel Access dynamic library
(*libca.so*, *libca.dylib*, or *ca.dll* depending on the system) at
runtime to do Channel Access communication. As said above, for the
most commonly used operating systems and architectures, modern version
of these libraries are provided, and will be installed and used with
pyepics by default. We recommend using these.
If these provided versions of *libca* do not work for you, please let
us know. If you need to or wish to use a different version of
*libca*, you can set the environmental variable ``PYEPICS_LIBCA`` to
the full path of the dynamic library to use as *libca*, for example::
> export PYEPICS_LIBCA=/usr/local/epics/base-7.0.4/lib/linux-x86_64/libca.so
Note that *libca* will need to find the library *libCom*, also created
with Epics Base. This is almost always in the same folder as *libca*
and can be found without trouble, but you may need to make sure that
the *libca* you are pointing to can find the required *libCom*.
To find out which CA library will be used by pyepics, use:
>>> import epics
>>> epics.ca.find_libca()
which will print out the full path of the CA dynamic library that will be used.
With the Epics CA library loaded, you will also need to be able to
connect to Epics Process Variables. Generally, these variables are
provided by Epics I/O controllers (IOCs) that are processes running on
some device on the network. If you are connecting to PVs provided by
IOCs on your local subnet, you should have no trouble. If you are
trying to reach IOCs outside of your immediate subnet, you may need to
set the environmental variable ``EPICS_CA_ADDR_LIST`` to specify which
networks to search for PVs. Consult your local Epics expert if you
are having trouble connecting to PVs that you think should be reachable.
Testing
~~~~~~~~~~~~~
Automated testing of PyEpics is done with the Github actions, for
Python 3.10 through 3.14, using an ubuntu-linux environment.
To run these tests yourself, you will need the `pytest` python
module. You will also need to run an Epics softIOC as a separate
process, and a simulator that updates PV values as a separate process.
These can all run on the same machine or different machines on your
network as long as all processes can see all the PVs (all using a
prefix of `PyTest:`). The softIoc cannot be run in a separate
terminal process or using the `procServ` program. To setup the
testing environment, first start the testing softIoc in one shell,
with::
~> cd tests/Setup
~> softIoc ./st.cmd
If you have `procServ` installed, you can do::
~> cd tests/Setup
~> bash ./start_ioc.sh
which will put the IOC properly as a background process. Second, run the
simulator (also in `tests/Setup`) so that Epics channels are changing::
~> python simulator.py
Again, these do not have to be run on the same machine as your tests, but
the PVs here will need to be discoverable by all the processes involved.
Now, you are ready to run the tests in the `tests` folder. In many
scenarios for Python libraries, one would be able to run all the tests, and
measure the testing coverage with a single command. Because the pyepics
test will change underlying threading contexts, a simple ::
~> cd ..
~> pytest test_*.py
will show many failures. Instead you should run each test as a separate
run of `pytest`::
~> for testfile in test_*.py; do pytest $testfile ; done
The automated testing process also uses the `coverage` tool to help
identify which parts of the code is actually run by the tests.
Unfortunately, the code for using GUI are not easily tested by the
automated procedures. In addition, a softIoc would need to support all of
the subclasses of Device, which cannot be guaranteed.
Development Version
~~~~~~~~~~~~~~~~~~~~~~~~
Development of pyepics is done through the `pyepics github
repository`_. To get a copy of the latest version do::
git clone git@github.com/pyepics/pyepics.git
Getting Help
~~~~~~~~~~~~~~~~~~~~~~~~~
For questions, bug reports, feature request, please consider using the
following methods:
1. Send email to the Epics Tech Talk mailing list. You can send
mail directly to the lead author, Matt Newville
<newville@cars.uchicago.ed>. The Epics Tech Talk mailing list
has many Epics experts reading it, so someone else interested or
knowledgeable about the topic might provide an answer. Since the
mailing list is archived and the main mailing list for Epics
work, a question to the mailing list has a better chance of
helping someone else.
2. Create an Issue or Discussion on
https://github.com/pyepics/pyepics. Github Issues are usually
intended for bug tracking, but the traffic for bug reports and
discussions about PyEpics is generally very low, so using either
is fine.
3. If you think you have found a bug in existing code, or have some
code you think would be useful to add to pyepics, consider making
a Pull Request on https://github.com/pyepics/pyepics.
License
~~~~~~~~~~~~~~~~~~~
The pyepics source code, this documentation, and all material
associated with it are distributed under the Epics Open License:
.. include:: ../LICENSE
In plain English, this says that there is no warranty or guarantee that the
code will actually work, but you can do anything you like with this code
except a) claim that you wrote it or b) claim that the people who did write
it endorse your use of the code. Unless you're the US government, in which
case you can probably do whatever you want.
Acknowledgments
~~~~~~~~~~~~~~~~~~~~~~
pyepics was originally written and is maintained by Matt Newville
<newville@cars.uchicago.ed>. Many important contributions to the library
have come from Angus Gratton while at the Australian National University,
and from Daron Chabot and Ken Lauer. Several other people have provided
valuable additions, suggestions, pull requests or bug reports, which has
greatly improved the quality of the library: Robbie Clarken, Daniel Allen,
Michael Abbott, Thomas Caswell, Alain Peteut, Steven Hartmann, Rokvintar,
Georg Brandl, Niklas Claesson, Jon Brinkmann, Marco Cammarata, Craig
Haskins, David Vine, Pete Jemian, Andrew Johnson, Janko Kolar, Irina
Kosheleva, Tim Mooney, Eric Norum, Mark Rivers, Friedrich Schotte, Mark
Vigder, Steve Wasserman, and Glen Wright.
|
