Changing the IOC Instance#

This tutorial makes a small change to the example IOC bl01t-ea-cam-01: you add a hand-crafted EPICS database record and prove the change works. This is a type 1 change from Types of change — you are only editing instance configuration, so nothing is recompiled. Types 2 and 3 follow in the next two tutorials.

Type 1 changes do not strictly need a developer container (you deployed an IOC instance in an earlier tutorial without one), but we will use the ioc-adsimdetector devcontainer here because it lets you test the change instantly. If you closed it after the last tutorial, reopen the ioc-adsimdetector folder in VSCode, press Ctrl-Shift-P and choose “Reopen in Container”, then re-select the instance:

ibek dev instance /workspaces/t01-services/services/bl01t-ea-cam-01

Note

This tutorial assumes the ioc.yaml-based instance. If you switched to raw startup assets in the previous tutorial, either revert to ioc.yaml or apply the same change by appending the dbLoadRecords line to your st.cmd — see Raw Startup Script and Database.

Make the change#

Your instance config folder /epics/ioc/config is symlinked to /workspaces/t01-services/services/bl01t-ea-cam-01/config, so every edit you make here lands directly in the t01-services repo, ready to commit.

  1. Add a file extra.db containing a single soft record:

    record(ai, "BL01T-EA-CAM-01:TEST") {
   field(DESC, "Test record")
   field(DTYP, "Soft Channel")
   field(VAL, "1")
}

  2. Append a StartupCommand entity to ioc.yaml to load it (match the indentation of the existing - type: entries so the - type: lines align):

    - type: epics.StartupCommand
  command: dbLoadRecords(config/extra.db)

Test it#

Restart the IOC inside the devcontainer:

# stop the running IOC shell first with Ctrl-D (or type exit)
cd /epics/ioc
./start.sh

start.sh runs ibek runtime generate2 to regenerate the startup script and database from your edited ioc.yaml, so your dbLoadRecords(config/extra.db) line now appears in the startup log.

From a second terminal (Terminal -> New Terminal) read the new record:

caget BL01T-EA-CAM-01:TEST

A value of 1 confirms the change is live.

Commit the change#

Because the config edits already live in t01-services, commit and push them, then tag a release of the services repo (substitute your own version):

cd /workspaces/t01-services
git add .
git commit -m "Add extra.db to bl01t-ea-cam-01"
git push
git tag 2026.7.1
git push origin 2026.7.1

That tag pins the version you deploy to a real beamline — see Deploy an IOC with ArgoCD for the cluster deployment path.

How it works#

The entities you may use in ioc.yaml are defined by support YAML files baked into the Generic IOC at build time — one per support module, under /epics/ibek-defs. StartupCommand comes from the global /epics/ibek-defs/epics.ibek.support.yaml:

- name: StartupCommand
  description: Adds an arbitrary command in the startup script before iocInit
  parameters:
    command:
      type: str
      description: command string
      default: ""
  pre_init:
    - type: text
      value: "{{ command }}"

Its companion PostStartupCommand does the same after iocInit. For a command spanning several lines, use a YAML block scalar — the lines are emitted verbatim (the nesting whitespace is stripped):

- type: epics.StartupCommand
  command: |
    # load extra records
    dbLoadRecords(config/extra.db)
    dbLoadRecords(config/extra2.db)

Later tutorials show where these support YAML files come from and how to add your own.