Skip to content

Commit 0b67051

Browse files
gilesknapgilesknap
authored
Merge pull request #138 from epics-containers/august-update
update Changing a Generic IOC
2 parents df03cdf + b16b18b commit 0b67051

File tree

2 files changed

+62
-70
lines changed

2 files changed

+62
-70
lines changed

‎docs/images/phoebus2.png

130 KB
Loading

‎docs/tutorials/ioc_changes2.md

Lines changed: 62 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -14,111 +14,99 @@ Some of the reasons for doing this are:
1414
in the support YAML file.
1515

1616
:::{note}
17-
If you are considering making a change to a Generic IOC because you
18-
want to add support for a second device, this is allowed but you should
19-
consider the alternative of creating a new Generic IOC.
20-
If you keep your Generic IOCs simple and focused on a single device, they
21-
will be smaller and there will be less of them. IOCs' records can still be
22-
linked via CA links and this is preferable to recompiling a Generic IOC
23-
for every possible combination of devices. Using Kubernetes to
24-
manage multiple small services is cleaner than having a handful of
25-
monolithic services.
17+
If you are considering making a change to a Generic IOC because you want to add support for a second device, this is allowed but you should consider the alternative of creating a new Generic IOC for the second device. If you keep your Generic IOCs simple and focused on a single device, they will be smaller and there will be less of them. IOCs' records can still be linked via CA links and this is preferable to recompiling a Generic IOC for every possible combination of devices. Using Kubernetes to manage multiple small services is cleaner than having a handful of monolithic services.
18+
19+
Having said this. If there is a common collection of devices that are frequently deployed together and usually restarted together then there is merit in making a Generic IOC for that collection. For example, at DLS we have a Single generic IOC for the set of vacuum equipment that we deploy on every beamline.
2620
:::
2721

28-
This tutorial will make some changes to the generic IOC `ioc-adsimdetector`
29-
that you already used in earlier tutorials.
22+
This tutorial will make some changes to the generic IOC `ioc-adsimdetector` that you already used in earlier tutorials.
3023

31-
For this exercise we will work locally inside the `ioc-adsimdetector`
32-
developer container. Following tutorials will show how to fork repositories
33-
and push changes back to GitHub
24+
For this exercise we will work locally inside the `ioc-adsimdetector` developer container and will not commit our changes back. Following tutorials will show how to fork repositories and push changes back to GitHub
3425

35-
For this exercise we will be using an example IOC Instance to test our changes. Instead of working with a beamline repository, we will use the example ioc instance inside `ioc-adsimdetector`. It is a good idea for Generic IOC authors to include an example IOC Instance in their repository for testing changes in isolation. Obviously, this is easy for a simulation IOC, for IOCs that normally connect to real hardware this would require an additional simulator of some kind.
26+
For this exercise we will be using an example IOC Instance to test our changes. Instead of working with a beamline repository, we will use the example ioc instance that is already inside `ioc-adsimdetector`. It is a good idea for Generic IOC authors to include an example IOC Instance in their repository for testing changes in isolation. Obviously, this is easy for a simulation IOC, for IOCs that normally connect to real hardware this would require a simulator of some kind.
3627

3728
## Preparation
3829

39-
First, clone the `ioc-adsimdetector` repository and make sure the container
40-
build is working:
30+
First, clone the `ioc-adsimdetector` repository and make sure the container build is working. You may also use the existing clone you have from previous tutorials.
4131

42-
```console
43-
git clone [email protected]:epics-containers/ioc-adsimdetector.git
32+
```bash
33+
git clone --recursive [email protected]:epics-containers/ioc-adsimdetector.git
4434
cd ioc-adsimdetector
45-
./build
4635
code .
47-
# Choose "Reopen in Container"
48-
# Or ctrl+shift+p and choose "Remote-Containers: Reopen in Container"
36+
# ctrl+shift+p and choose "Remote-Containers: Reopen in Container"
4937
```
5038

51-
Note that if you do not see the prompt to reopen in the container, you can open
52-
the `Remote` menu with `Ctrl+Alt+O` and select `Reopen in Container`.
53-
54-
The `build` script does two things.
55-
56-
- it fetches the git submodule called `ibek-support`. This submodule is shared between all the Generic IOC container images and contains the support YAML files that tell `ibek` how to build support modules inside the container environment and how to use them at runtime.
57-
- it builds the Generic IOC container image developer target locally using docker or podman.
58-
5939
## Verify the Example IOC Instance is working
6040

61-
When a new Generic IOC developer container is opened, there are two things
62-
that need to be done before you can run an IOC instance inside of it.
41+
When a new Generic IOC developer container is opened, there are two things that need to be done before you can run an IOC instance inside of it.
6342

6443
- Build the IOC binary
6544
- Select an IOC instance definition to run
6645

67-
The folder `ioc` inside of the `ioc-adsimdetector` is where the IOC source code resided. However our containers always make a symlink to this folder at `/epics/ioc`. This is so that it is always in the same place and can easily be found by ibek (and the developer!). Therefore you can build the IOC binary with the
68-
following command:
46+
The folder `ioc` inside of the `ioc-adsimdetector` is where the IOC source code resides. However our containers always make a symlink to this folder at `/epics/ioc`. This is so that it is always in the same place and can easily be found by ibek (and the developer!). Therefore you can build the IOC binary with the following command:
6947

70-
```console
48+
```bash
7149
cd /epics/ioc
7250
make
7351
```
7452

75-
The IOC instance definition is a YAML file that tells `ibek` what the runtime assets (ie. EPICS DB and startup script) should look like. Previous tutorials selected the IOC instance definition from a beamline repository. In this case we will use the example IOC instance that comes with `ioc-adsimdetector`. The following command will select the example IOC instance:
53+
The IOC instance definition is a YAML file that tells `ibek` what the runtime assets (ie. EPICS DB and startup script) should look like. Previous tutorials selected the IOC instance definition from a beamline repository. In this case we will use the example IOC instance that comes with `ioc-adsimdetector`. It can be found in `services/bl01t-ea-ioc-02`. The following command will select the example IOC instance:
7654

77-
```console
78-
ibek dev instance /workspaces/ioc-adsimdetector/services/bl01t-ea-test-02
55+
```bash
56+
ibek dev instance /workspaces/ioc-adsimdetector/services/bl01t-ea-ioc-02
7957
```
8058

81-
The above command removes the existing config folder `/epics/ioc/config` and
82-
symlinks in the chosen IOC instance definition's `config` folder.
59+
The above command removes the existing config folder `/epics/ioc/config` and symlinks in the chosen IOC instance definition's `config` folder to `/epics/ioc/config`.
8360

8461
Now run the IOC:
8562

86-
```console
87-
cd /epics/ioc
63+
```bash
8864
./start.sh
8965
```
9066

9167
You should see an iocShell prompt and no error messages above.
9268

93-
Let us also make sure we can see the simulation images that the IOC is
94-
producing. For this we need the `c2dv` tool that we used earlier. You
95-
can use the same virtual environment that you created earlier, or create
96-
a new one and install again. Note that these commands are to be run
97-
in a terminal outside of the developer container.
69+
Let us also make sure we can see the simulation images that the IOC is producing. For this we will use phoebus and we will create a screen to display the image. Previously we had a pre-defined screen from the template project for this - but this example IOC uses a different PV prefix so we need to create a new screen.
9870

99-
```console
100-
python3 -m venv c2dv
101-
source ~/c2dv/bin/activate
102-
pip install c2dataviewer
71+
From *outside of the developer container* start up phoebus and the ca-gateway as we did in earlier tutorials:
72+
73+
```bash
74+
cd ioc-adsimdetector/compose
75+
. ./environment.sh
76+
ec up -d
10377
```
10478

105-
Run the `c2dv` tool and connect it to our IOCs PVA output:
79+
Phoebus should now be up and running and showing the auto generated **index.bob**, In phoebus do the following steps:
10680

107-
```console
108-
c2dv --pv BL01T-EA-TST-02:PVA:OUTPUT &
109-
```
81+
- right click in the index.bob screen and choose "Open in editor"
82+
- from the plots section of the widget pallet select "Image" and drag a rectangle for you image widget in the index.bob screen.
83+
- in the properties pane
84+
- deselect X and Y axis Visible checkboxes
85+
- set PV Name to 'BL01T-EA-TST-02:ARR:ArrayData'
86+
- set Title to 'SimDetector Image'
87+
- set Data width and height to 1024
88+
- choose File -> Save As and save as `/opi/demo.bob`
89+
- click the 'Execute Display' green arrow button on the right of the top toolbar
11090

111-
Back inside the developer container, you can now start the detector and
112-
the PVA plugin, by opening a new terminal and running the following:
91+
IMPORTANT: you must save in `/opi` not `/opi/ioc` because the second folder has its contents cleared and filled with auto generated screens every time the IOC is started.
11392

114-
```console
115-
caput BL01T-EA-TST-02:PVA:EnableCallbacks 1
93+
Back inside the developer container, you can now start the detector and the Std Arrays plugin, by opening a new terminal and running the following:
94+
95+
```bash
96+
caput BL01T-EA-TST-02:ARR:EnableCallbacks 1
11697
caput BL01T-EA-TST-02:DET:Acquire 1
11798
```
11899

119-
You should see the moving image in the `c2dv` window. We now have a working
100+
You should see the moving image in the Phoebus window. We now have a working
120101
IOC instance that we can use to test our changes.
121102

103+
104+
:::{figure} ../images/phoebus2.png
105+
Phoebus with image widget
106+
:::
107+
108+
Note: the buttons to launch the engineering screens won't work right away because your new screen is in a different folder. To fix this, go back into the screen editor and add `ioc/` to the beginning of the `Display Path` in the `Open Display` action for each button.
109+
122110
## Making a change to the Generic IOC
123111

124112
One interesting way of changing a Generic IOC is to modify the support YAML
@@ -132,10 +120,10 @@ simulation detector is automatically started when the IOC starts.
132120

133121
To make this change we just need to have the startup script set the values
134122
of the records `BL01T-EA-TST-02:DET:Acquire` and
135-
`BL01T-EA-TST-02:PVA:EnableCallbacks` to 1.
123+
`BL01T-EA-TST-02:ARR:EnableCallbacks` to 1.
136124

137125
To make this change, open the file
138-
`ibek-support/ADSimDetector/ADSimDetector.ibek.support.yaml`
126+
`/workspaces/ioc-adsimdetector/ibek-support/ADSimDetector/ADSimDetector.ibek.support.yaml`
139127
and add a `post_init` section just after the `pre_init` section:
140128

141129
```yaml
@@ -145,8 +133,8 @@ post_init:
145133
dbpf {{P}}{{R}}Acquire 1
146134
```
147135
148-
Next make a change to the file `ibek-support/ADCore/ADCore.ibek.support.yaml`.
149-
Find the NDPvaPlugin section and also add a `post_init` section:
136+
Next make a change to the file `/workspaces/ioc-adsimdetector/ibek-support/ADCore/ADCore.ibek.support.yaml`.
137+
Find the NDStdArrays section and also add a `post_init` section:
150138

151139
```yaml
152140
post_init:
@@ -155,19 +143,21 @@ post_init:
155143
dbpf {{P}}{{R}}EnableCallbacks 1
156144
```
157145

146+
The values that you add into entities like the above are rendered at runtime to make the startup script. The `{{P}}` and `{{R}}` are placeholders that are replaced with the PV prefix and record name of the IOC instance. They are rendered using Jinja 2 with a context that includes all of the values of the parameters in the entity. You can go and look at your rendered startup script in `/epics/runtime/st.cmd`.
147+
158148
If you now go to the terminal where you ran your IOC, you can stop it with
159149
`Ctrl+C` and then start it again with `./start.sh`. You should see the
160150
following output at the end of the startup log:
161151

162152
```console
163153
dbpf BL01T-EA-TST-02:DET:Acquire 1
164154
DBF_STRING: "Acquire"
165-
dbpf BL01T-EA-TST-02:PVA:EnableCallbacks 1
155+
dbpf BL01T-EA-TST-02:ARR:EnableCallbacks 1
166156
DBF_STRING: "Enable"
167157
epics>
168158
```
169159

170-
You should also see the `c2dv` window update with the moving image again.
160+
You should also see the demo window update with the moving image again.
171161

172162
If you wanted to publish these changes you would have to commit both the
173163
`ibek-support` submodule and the `ioc-adsimdetector` repository and push
@@ -177,29 +167,31 @@ tutorials we will cover making forks and doing pull requests for when you have
177167
changes to share back with the community.
178168

179169
Note: this is a slightly artificial example, as it would change the behaviour
180-
for all instances of a PVA plugin and a simDetector. In a real IOC you would
170+
for all instances of a StdArray plugin and a simDetector. In a real IOC you would
181171
do this on a per instance basis.
182172

183173
Let us quickly do the instance YAML change to demonstrate the correct approach
184174
to this auto-starting detector.
185175

186176
Undo the support yaml changes:
187177

188-
```console
178+
```bash
189179
cd /workspaces/ioc-adsimdetector/ibek-support
190180
git reset --hard
191181
```
192182

183+
If you restart the IOC now you will see that the detector does not start.
184+
193185
Add the following to
194-
`/workspaces/ioc-adsimdetector/services/bl01t-ea-test-02/config/ioc.yaml`:
186+
`/epics/ioc/config/ioc.yaml`:
195187

196188
```yaml
197189
- type: epics.dbpf
198190
pv: BL01T-EA-TST-02:DET:Acquire
199191
value: "1"
200192
201193
- type: epics.dbpf
202-
pv: BL01T-EA-TST-02:PVA:EnableCallbacks
194+
pv: BL01T-EA-TST-02:ARR:EnableCallbacks
203195
value: "1"
204196
```
205197

0 commit comments

Comments
 (0)