# 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:
[](../how-to/convert-ioc-instance.md)

---

## 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`:

```none
<?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

```bash
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):

```yaml
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.