Converting a builder XML IOC to ibek ioc.yaml#

This tutorial shows how to use builder2ibek xml2yaml to convert an existing DLS XMLbuilder IOC instance into an ibek ioc.yaml. This is the most common operation and is all you need to do when working with existing generic IOCs.

This is just a quick intro. For a more comprehensive guide see: Convert a builder XML IOC instance to ibek YAML

The input: a builder XML file#

Builder IOC definitions live under a beamline’s BL*-BUILDER repository, in etc/makeIocs/. For example, /dls_sw/work/R3.14.12.7/support/BL19I-BUILDER/etc/makeIocs/BL19I-MO-IOC-14.xml:

<?xml version="1.0" ?>
<components arch="linux-x86_64">
    <utility.pingWait delay="3" ip="10.119.2.14"/>
    <pmac.pmacAsynSSHPort IP="10.119.2.14" PASSWORD="!ls@OX11" name="BRICK14_S"/>
    <pmac.PowerPMAC P="BL19I-MO-STEP-14" Port="BRICK14_S" name="BRICK14"/>
    <pmac.dls_pmac_asyn_motor ADDR="1" DESC="Beamstop X Smaract" M=":X"
        P="BL19I-OP-ABSB-02" PORT="BRICK14" ... name="BS2.X"/>
    <pmac.dls_pmac_asyn_motor ADDR="2" DESC="Beamstop Y Smaract" M=":Y"
        P="BL19I-OP-ABSB-02" PORT="BRICK14" ... name="BS2.Y"/>
    <pmac.dls_pmac_asyn_motor ADDR="3" DESC="Beamstop Z Smaract" M=":Z"
        P="BL19I-OP-ABSB-02" PORT="BRICK14" ... name="BS2.Z"/>
    <pmac.pmacDisableLimitsCheck Axis="1" Controller="BRICK14"/>
    <pmac.pmacDisableLimitsCheck Axis="2" Controller="BRICK14"/>
    <pmac.pmacDisableLimitsCheck Axis="3" Controller="BRICK14"/>
    <pmac.autohome GRP1="ALL" GRP2="X" GRP3="Y" GRP4="Z" P="BL19I-OP-ABSB-02"
        PLC="11" PORT="BRICK14" ... name="BS2.HOME"/>
    <BL19I.writeReadPMACVarNEW P="BL19I-MO-STEP-14" PORT="BRICK14" VAR="M32" .../>
    <BL19I.writeReadPMACVarNEW P="BL19I-MO-STEP-14" PORT="BRICK14" VAR="M33" .../>
    <BL19I.writeReadPMACVarNEW P="BL19I-MO-STEP-14" PORT="BRICK14" VAR="M34" .../>
    <devIocStats.devIocStatsHelper ioc="BL19I-MO-IOC-14" name="MO-IOC-14"/>
    <autosave.Autosave iocName="BL19I-MO-IOC-14" name="MO-IOC14-SR" .../>
    <pvlogging.PvLogging/>
</components>

Run the conversion#

uv run builder2ibek xml2yaml \
    /dls_sw/work/R3.14.12.7/support/BL19I-BUILDER/etc/makeIocs/BL19I-MO-IOC-14.xml \
    --yaml ioc.yaml

The output: ioc.yaml#

The converter produces an ioc.yaml with every entity listed explicitly (bl19i-mo-step-14/config/ioc.yaml, abbreviated):

ioc_name: "{{  _global.get_env('IOC_NAME') }}"

description: auto-generated by https://github.com/epics-containers/builder2ibek

entities:
  - type: epics.EpicsEnvSet
    name: STREAM_PROTOCOL_PATH
    value: /epics/runtime/protocol/

  - type: pmac.pmacAsynSSHPort
    IP: 10.119.2.14
    PASSWORD: "!ls@OX11"
    name: BRICK14_S

  - type: pmac.PowerPMAC
    P: BL19I-MO-STEP-14
    name: BRICK14
    pmacAsynSSHPort: BRICK14_S

  - type: pmac.dls_pmac_asyn_motor
    ADDR: 1
    Controller: BRICK14
    DESC: Beamstop X Smaract
    M: :X
    P: BL19I-OP-ABSB-02
    # ... further motor parameters ...

  # ... further motors and pmacDisableLimitsCheck entries ...

  - type: pmac.autohome
    GRP1: ALL
    GRP2: X
    GRP3: Y
    GRP4: Z
    P: BL19I-OP-ABSB-02
    PLC: 11
    PmacController: BRICK14

  - type: pmac.pmacVariableWrite
    P: BL19I-MO-STEP-14
    PORT: BRICK14
    VAR: M32
    # ...

  - type: autosave.Autosave
    P: "BL19I-MO-STEP-14:"

What to review after conversion#

The output is a good starting point but always needs a human review:

  • Check entity types — confirm each type: matches what you expect from the builder XML.

  • Check parameter values — PV prefixes, IP addresses, and other site-specific values should match the original configuration.

  • Commented-out elements — builder XML elements that the converter could not map are emitted as YAML comments. These need manual attention.

  • Module-specific converters — some modules (e.g. BL19I.writeReadPMACVarNEW above) are handled by a converter that remaps them to a standard ibek type (pmac.pmacVariableWrite / pmac.pmacVariableRead).

Renaming the IOC#

Builder IOC names like BL19I-MO-IOC-14 describe the montion IOC number, not the device. In ibek the convention is to name the IOC after the device it controls. Here the IOC drives a PMAC brick managing the beamstop motors, so it is renamed bl19i-mo-step-14 — reflecting the beamline, domain, device type, and pmac number. Update the directory name and any Helm/services configuration to match.