IOC Template Cookiecutters

Caproto IOCs are easy to get started with and only require a single source code file as shown in the many examples provided here.

For larger projecs, making a single caproto IOC into its own Python package brings along some benefits:

  1. Easily installed into a Python environment

  2. Ability to add command-line hooks

  3. Better structure - relatve imports

  4. Add tests, documentation

To ease this process, caproto offers two “cookiecutter” templates, one for generating your IOC package and one for creating a startup script that can be used by procServ, systemd, init.d, and so on.

IOC Cookiecutter

The cookiecutter is available in the caproto organization on GitHub.

The steps outlining an IOC creation are tersely shown here for a quick example.

Install cookiecutter

$ pip install cookiecutter

Use the cookiecutter

$ cookiecutter https://github.com/caproto/cookiecutter-caproto-ioc
project_name [project_name]:
github_repo_group [pcdshub]:
repo_name [project_name]:
default_prefix [SIM:]:
author_name [SLAC National Accelerator Laboratory]:
email []:
folder_name [project_name]:
import_name [project_name]:
description [project_name]:
Select license:
1 - SLAC
2 - BNL
3 - MIT
4 - BSD-3
Choose from 1, 2, 3, 4 [1]:
Select auto_git_setup:
1 - no
2 - yes
Choose from 1, 2 [1]:
git_remote_name [origin]:
Select auto_doctr_setup:
1 - no
2 - yes
Choose from 1, 2 [1]:
Select use_x11_on_travis:
1 - no
2 - yes
Choose from 1, 2 [1]:
year [2020]:

Create a test environment

$ conda create -n my_test_env python=3.7
$ conda activate my_test_env

Install the project in that environment

$ cd project_name
$ pip install .

Run the IOC

$ project_name --list-pvs
[I 17:33:28.970       server:  133] Asyncio server starting up...
[I 17:33:28.971       server:  146] Listening on 0.0.0.0:5064
[I 17:33:28.972       server:  205] Server startup complete.
[I 17:33:28.973       server:  207] PVs available:
    SIM:SampleValue
    SIM:SampleScanned
This happens at IOC boot!
Initial value was: 0.0
Now it is: 0.1

^C
[I 17:33:30.442       server:  212] Server task cancelled. Will shut down.
[I 17:33:30.442       server:  222] Server exiting....

Alternatively:

$ python -m project_name --list-pvs

Build the docs:

$ cd docs
$ make html

Open them in your browser:

# (macOS)
$ open build/html/index.html
# (Linux)
$ xdg-open build/html/index.html

Startup Script Cookiecutter

The startup_cookiecutter is available in the caproto organization on GitHub.

Before using this cookiecutter, you should already have a caproto-based IOC you wish to create startup scripts for. Please consider starting with the cookiecutter from the previous section.

With standard EPICS IOCs, the IOC supporting code tends to be reused many times, with only a per-IOC startup script configuring which records get created with what PV prefixes, device IP addresses, and so on.

This cookiecutter aims to do something similar - take your existing IOC source code and easily template multiple instances of that IOC. Several key points (and benefits in the author’s opinion) of this method are:

  1. Decoupling PVGroup source code from per-IOC settings.

  2. A git submodule of the IOC source to specify a released (or unreleased) versino of the IOC source code.

  3. An independent conda environment per IOC.

If you want to use your IOC with procServ, this is the cookiecutter for you.

The steps outlining an IOC startup script creation are tersely shown here for a quick example.

Install cookiecutter

$ pip install cookiecutter

Use the cookiecutter

$ cookiecutter https://github.com/pcdshub/cookiecutter-caproto-ioc-startup
$ cd ioc-my-iocname

Customize any settings

$ vim config.sh

Run the IOC

$ ./st.cmd
[I 17:33:28.970       server:  133] Asyncio server starting up...
[I 17:33:28.971       server:  146] Listening on 0.0.0.0:5064
[I 17:33:28.972       server:  205] Server startup complete.
[I 17:33:28.973       server:  207] PVs available:
    SIM:SampleValue
    SIM:SampleScanned
This happens at IOC boot!
Initial value was: 0.0
Now it is: 0.1

^C
[I 17:33:30.442       server:  212] Server task cancelled. Will shut down.
[I 17:33:30.442       server:  222] Server exiting....