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:
Easily installed into a Python environment
Ability to add command-line hooks
Better structure - relatve imports
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:
Decoupling PVGroup source code from per-IOC settings.
A git submodule of the IOC source to specify a released (or unreleased) versino of the IOC source code.
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....