caproto: a pure-Python Channel Access protocol library¶
Caproto is a implementation of the EPICS Channel Access protocol for distributed hardware control in pure Python with a “sans-I/O” architecture.
Caproto is a toolkit for building Python programs that speak Channel Access (“EPICS”). It includes a reusable core that encodes the Channel Access protocol. It also includes several client and server implementations built on that core. This layered design is inspired by the broad effort in the Python community to write sans-I/O implementations of network protocols. The EPICS (Experimental Physics and Industrial Control System) Channel Access protocol is used in laboratories and companies around the world to implement distributed control systems for devices such as large telescopes, particle accelerators, and synchrotrons. Its roots go back to a 1988 meeting funded by the Reagan-era Strategic Defense Initiative (“Star Wars”).
The authors pronounce caproto “kah-proto” (not “C.A. proto”). It’s fun to say.
Caproto is intended as a friendly entry-point to EPICS. It may be useful for scientists who want to understand their hardware better, engineers learning more about the EPICS community, and “makers” interested in using it for hobby projects — EPICS has been used for brewing beer and keeping bees! At the same time, caproto is suitable for use at large experimental facilities.
Try caproto in four lines¶
First verify that you have Python 3.6+.
If necessary, install it by your method of choice (apt, Homebrew, conda, etc.). Now install caproto:
python3 -m pip install -U caproto
In one terminal, start an EPICS Input-Output Controller (IOC), which is a server.
python3 -m caproto.ioc_examples.simple --list-pvs
In another, use the command-line client:
caproto-put simple:A 42
10 Reasons To Use Caproto and 1 Big Reason Not To¶
Most existing EPICS tools are built on well-established C and C++ libraries. Why write something from scratch in Python instead of just wrapping those?
Effortlessly Portable: No required dependencies — even numpy is optional. Caproto just needs Python itself. We use it on Linux, OSX, Windows, and RaspberryPi.
Easy to Install and Use: See “Try caproto in four lines,” above.
Handy for Debugging: Programmatic access to convenient Python objects embodying every CA message sent and received. See the examples of verbose logging with the Command-Line Client.
Efficient: Data is read directly from sockets into contiguous-memory ctypes structures.
- Zero-copy into
- Only pay a performance cost of human-friendly introspection if and when you use it.
For the numbers, see caproto’s benchmarks.
- Zero-copy into
Batteries Included: Includes multiple server and client implementations with different concurrency strategies.
- Command-line tools (largely argument-compatible with standard epics-base ca*)
- A drop-in replacement for pyepics
- Various client and server implementations that are synchronous, threaded, or employing one of Python’s cooperative concurrency frameworks
Accessible: Writing IOCs in pure Python is so easy, a scientist can do it!
Reusable: “Sans-I/O” design separates protocol interpretation from wire transport. See the sans-I/O documentation for more on the rationale for this design pattern and a list of related projects.
Consistent: Server and client implementations share protocol state machine code.
Robust: Over 1500 unit tests verify compatibility with standard epics-base tools (tested against 3.14, 3.15, 3.16, R7).
Succinct: The core of the package is about the same word count as the CA protocol documentation.
All that said, some applications of EPICS — such as running an accelerator — rely on the battle-tested reliability of EPICS’ reference implementation. We would advise those kinds of users to steer well clear of caproto. It is best suited to applications to reward convenience, fast iteration, and accessibility.
- Requirements: Python 3.6+ (no other required dependencies!)
- License: 3-clause BSD
The design of this library was modeled on h11, to which caproto owes its core design principles and many of its clever tricks. h11 is distributed under an MIT license.
And of course many resources from the EPICS developer community were indispensable. See References.
In addition to its core “sans I/O” protocol library, caproto includes some ready-to-use client and server implementations exploring different API choices and networking libraries. They are organized into packages by how they handle concurrency. Some will be maintained long-term; others may be abandoned as learning exercises.
- Command-Line Client
- Synchronous Client
- Threading Client
- Pyepics-Compatible Client
- Asynchronous Clients
- Input-Output Controllers (IOCs)
- Mock Records
- Shark (pcap/tcpdump parsing)
- Performance Benchmarks
- Details of our Protocol Compliance for CA Nerds
- Release History