Lessons on Channel Access Client Programming

This lessons should qualify a C-programmer to make efficient use of the Channel Access client libraries and to write his/her own EPICS client applications in C. Special attention is directed to network traffic and possible pitfalls.

This tutorial is not yet complete. Whenever I have some time, I will add more lessons.

Contents

• Audience
• References
• Lessons
  • caLesson 1 - simple read access
  • caLesson 2 - getting more infos from EPICS
  • caLesson 3 - channel access data types
  • caLesson 4 - monitors and version differences
  • caLesson 5 - write and wait

Audience

The lessons are directed to all users of EPICS who want to write their own Channel Access client applications in C. They are recommend for all programmers who are new to Channel Access, not only to members of the PSI controls section.

You should be experienced with C. I will not try to explain how the C compiler, preprocessor, or linker works and what Makefiles are. If this is new to you, I recommend to get some programming practice first. For some lesson, experience with multi-threading is recommended.

If you don't have experience with EPICS yet, you should participate in an EPICS trainig, here at PSI or at some other EPICS site. I expect that you know what the terms IOC, record and processing mean in the EPICS world. Experience with medm or other existing Channel Access clients is also helpful.

References

See the EPICS home page www.aps.anl.gov/epics for everything about EPICS. An overwiew what EPICS and Channel Access are is given on the EPICS Overwiew page. Especially read the chaper about Channel Access.

Today, two major releases of Channel Access are in use: R3.12 (which is still used in EPICS release R3.13) and R3.14. On the EPICS home page you can find the (very thin) EPICS R3.12 Channel Access Reference Manual and the much more detailled EPICS R3.14 Channel Access Reference Manual.

APS provides many lectures in their Getting Started with Epics series. You should definitely read the Introduction to Channel Access Clients.

Much valueable information can be found in header files. If you work at a standard SLS Linux PC, have a look at:
/usr/local/epics/base/include/cadef.h
Otherwise find this file in your local EPICS installation.

Lessons

The lessons are provided as tgz archives. Unpack them anywhere in your home directory. Each lesson is in its own directory. The lesson itself is contained in the comments in the C files. Read them carefully. Some lessons contain README files. Read them first.

The provided Makefiles are tailored to the SLS installation of EPICS. It should not be too difficult to modify them for other installations. You may use them as a starting point for your own Channel Access clients.

The environment variable EPICS_HOST_ARCH must be defined. I have tested all programs on Scientific Linux 3, where we have EPICS_HOST_ARCH=SL3-x86 at the SLS. Other installation will most probably use different values.

The used record names exist at the SLS. If you are in the machine network or in a beamline network, you will see real life data. From the SLS office, you will either see simulations or you can connect to the machine network with the cam command. In some lessons, we will write to records. Depending on the relative location of you and the record, you may be allowed to write to real components of the machine! This is not a game!

If you are not at SLS, you should change the record names so something which exists at your site. Probably use a so called softioc to provide some records to play with.

caLesson1

This lesson shows how to write a very simple CA client program. It connects to some channels, reads them, prints them and exits.

Download caLesson1.tgz.

caLesson2

Here you will learn how to read more than a bare number from a channel. This is very useful to format a value correctly or to know the physical units of a value. In fact, it is this additional information that makes the difference between a value and a bare number.

You will also see one way to get your data a bit more structured. There are many ways to achive the same result, of course. You should know how macros work in C to understand this lesson.

Download caLesson2.tgz.

caLesson3

In this lesson, you will learn about different data types in Channel Access. You will also see the difference between "static" and "dynamic" data of a channel and how use this to reduce network traffic when reading data repeatedly.

Download caLesson3.tgz.

caLesson4

This lesson introduces "monitors". When you install a monitor, a user-defined callback function is called by the Channel Access library whenever a channel has new values available. This is much more "network friendly" than high rate polling.

You will also see the differences beween the Channel Access APIs of EPICS R3.13 and R3.14. In R3.14, you can still use the R3.13 API and Channel Access clients written for EPICS R3.13 should work without modifications with EPICS R3.14. Anyway, to be able to understand other people's code, you should know both flavours and only R3.14 is designed for multi-threading.

Download caLesson4.tgz.

caLesson5

In this lesson we will write to a device for the first time. We will use a "put-wait" method, that does not return before the device has understood and executed the written value. This method is best suited for GUI-less programs which can block. (In later lessons, we will learn a different way to write values.)

After the value is written, we will wait unil the device has finished using a monitor on a done flag. This is much more efficient than polling a done flag in a loop.

Download caLesson5.tgz.