IOC Deployment and Troubleshooting

This repo contains instructions for Session 2 of the Practical Beamline Controls Training.

Assumptions

• The instructions assume the user is logged into an APS-maintained Red Hat Enterprise Linux (RHEL) computer.
• The APS-maintained Red Hat Enterprise Linux (RHEL) computer has access to /APSshare

Outline

1. Setup
2. Deploy a new IOC
3. Add simulated motors to the IOC
4. Deploy the motorVMC (Virtual Motor Controller) module
5. Add virtual motors to the IOC
6. asyn troubleshooting

Quickstart

The external quickstart script is much less useful on non-APS machines.

To use the script, do the following:

$ curl -O https://git.aps.anl.gov/practical_beamline_controls_training/session_2/instructions/-/raw/external/scripts/quickstart.sh
$ chmod a+x quickstart.sh
$ ./quickstart.sh

Then copy and paste the output from the script into the terminal and proceed to the "Deploy a new IOC" section.

FAQ

Why isn't mkioc used to create the training IOC?

mkioc renames files and directories (references to xxx are replaced with the desired IOC name). This makes it impossible to have a solution branch in the git repo that works for everyone.

How does the training IOC differ from one created with mkioc?

There will be fewer build errors when building an IOC created by mkioc.

The training IOC required some customization to allow the IOC's prefix to be overridden:

• st.cmd.Linux sources override.iocsh, which overrides the default IOC prefix, xxx:, without requiring settings.iocsh to be edited.
• the caQtDM (and MEDM) start scripts open my-xxx.ui (and my-xxx.adl) instead of xxx.ui (and xxx.adl)
• A newPrefix.sh script was added to simplify the creation of override.iocsh, my-xxx.ui and my-xxx.adl

Should I deploy beamline IOCs based on the training IOC?

No. Just use mkioc.

Can I complete this exercise on a computer other than an APS-maintained RHEL computer?

Yes, in theory, but it requires building a local copy of EPICS base and a subset of synApps. It is likely other problems will be encountered.

Why does the solution branch use ~ instead of /home/beams/USERNAME in the solution branch?

The solution branch uses ~ instead of /home/beams/USERNAME in paths because it was the only way to make the solution branch build for everyone without requiring files to be edited.

The use of ~ is highly discouraged; only absolute paths should be used in RELEASE files. A negative side effect of using ~ in the path to MOTOR_VMC in the IOC's RELEASE file, is that MOTOR_VMC doesn't appear in the IOC's envPaths file. This wasn't a problem during the training becase the IOC doesn't load anything from the motorVMC module at runtime.

The solution branch

Both the xxx and motorVMC repos have a solution branch with tags for each step that:

• allows you to run all the commands in this training without editing a file in a text editor.
• enables jumping to a specific section

Note: the motorVMC module is only modified in section 4, so the only tags it has for later sections are 5.1 and 6.1.

How to avoid manually editing files

Example: You've been following the instructions in the training until step 5.7.2, which asks to you make a lot of change to vmc.cmd, but you'd rather not make those changes yourself.

Do the following to see if there are any files you've modified/created manually:

$ git status

If git reports any "Changes not staged for commit" or "Untracked files", do the following to save your work to a working branch:

$ git stash
$ git checkout -b working
$ git stash apply
$ git add ${IOC_DIR}/xxx
$ git commit -m "Backup of my work before switching to a tag on the solution branch"

At this point you can safely proceed to step 5.7.3

$ git checkout 5.7.3

Note: switching to '5.7.3'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

HEAD is now at 8a0470c Modified iocsh/vmc.cmd

Git can also show you the changes that were made:

$ git show 5.7.3

Note: git show <step_number> is only useful if the previous step involved creating or modifying a file.

How to jump to a specific section

Example: You already know how to deploy IOCs and EPICS modules. You'd really like to skip to section 6 to learn more about asyn troubleshooting.

Do the following:

• Follow the quickstart instructions.
• Complete step 2.1 to clone xxx.
• Complete step 2.2 to cd into the IOC's directory
• Complete step 2.3 override the default prefix
• Complete step 4.1 to clone motorVMC
• Complete step 4.2 to cd into the motorVMC directory
• Run git checkout 6.1 to update motorVMC for step 6.1.
• Run make to build motorVMC. The build should succeed.
• Run cd ${IOC_DIR}/xxx to go back to the IOC's directory.
• Run git checkout 6.1 to update the IOC for step 6.1.
• Run make to build the IOC. The build should succeed.
• Complete step 5.10.2 to start the virtual motor controller
• Proceed to step 6.1

Note: You won't have a motor screen open because you skipped step 3.4 and there will be autosave errors when the IOC first runs saying .sav and .savB files are not found.