Skip to content

Commit df03cdf

Browse files
gilesknapgilesknap
authored
Merge pull request #137 from epics-containers/august-update
Add second devcontainers page and update ioc_changes1
2 parents 8fd8809 + 27a33b2 commit df03cdf

File tree

5 files changed

+165
-94
lines changed

5 files changed

+165
-94
lines changed

‎docs/images/custom_bob.png

396 KB
Loading

‎docs/tutorials.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ tutorials/create_beamline
1313
tutorials/deploy_example
1414
tutorials/create_ioc
1515
tutorials/dev_container
16+
tutorials/dev_container2
1617
tutorials/ioc_changes1
1718
tutorials/ioc_changes2
1819
tutorials/generic_ioc

‎docs/tutorials/create_ioc.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -389,7 +389,7 @@ ec restart bl01t-ea-cam-01
389389

390390
Once it is back up you can click on the bl01t-ea-cam-01 button in the 'Autogenerated Engineering Screens' pane and you will see a new 'NDProcess' entity. If you know about wiring up AreaDetector you can now wire this plugin into your pipeline and make modifications to the image data as it passes through.
391391

392-
392+
(raw-startup-assets)=
393393
## Raw Startup Script and Database
394394

395395
This section demonstrates how to use your own startup assets. This involves
@@ -420,8 +420,8 @@ your IOC Instance config folder like this (replace docker with
420420
docker if that is what you are using):
421421

422422
```bash
423-
docker cp t01-services-bl01t-ea-cam-01-1:/epics/runtime/st.cmd services/bl01t-ea-cam-01/config
424-
docker cp t01-services-bl01t-ea-cam-01-1:/epics/runtime/ioc.subst services/bl01t-ea-cam-01/config/ioc.subst
423+
docker cp bl01t-ea-cam-01-1:/epics/runtime/st.cmd services/bl01t-ea-cam-01/config
424+
docker cp bl01t-ea-cam-01-1:/epics/runtime/ioc.subst services/bl01t-ea-cam-01/config/ioc.subst
425425
# no longer need an ibek ioc yaml file
426426
rm services/bl01t-ea-test-02/config/ioc.yaml
427427
```
@@ -434,3 +434,13 @@ Restart the IOC to see it operating as before (except that engineering screen ge
434434
```bash
435435
ec restart bl01t-ea-cam-01
436436
```
437+
438+
:::{note}
439+
This same IOC instance will be used in later tutorials. Therefore we should move these changes to a branch and restore the original **ioc.yaml** based version:
440+
```bash
441+
git checkout -b raw-startup
442+
git add .
443+
git commit -m "use raw startup script and database"
444+
git checkout main
445+
```
446+
:::

‎docs/tutorials/dev_container2.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Developer Containers Part 2
2+
3+
In this tutorial we will take a look at some of the extra features that came with the ioc-adsimdetector developer container we built in the previous tutorial. The compose folder in the ioc-adsimdetector repository contains a docker-compose file that can be used to launch a gateway and a phoebus container to view the PVs from the IOC. This works in the same way as the test compose profile that we used in the `t01-services` repository from earlier tutorials.
4+
5+
## Channel Access
6+
7+
If you want to inspect or change PV values for your developer container you can do so using the command line tools inside of the container.
8+
9+
If you still have your previous session open then you can use that. If you need to relaunch your developer container, then you can do so with the following commands:
10+
11+
```bash
12+
cd ioc-adsimdetector
13+
code .
14+
# ctrl-shift-p and choose 'reopen in container'
15+
# open a terminal in vscode
16+
17+
ibek dev instance /workspaces/t01-services/services/bl01t-ea-cam-01
18+
cd /epics/ioc
19+
make
20+
./start.sh
21+
```
22+
23+
Now you can open a new terminal in vscode and interact with the IOC using the EPICS CLI tools:
24+
25+
```bash
26+
caget BL01T-EA-CAM-01:DET:Acquire
27+
caput BL01T-EA-CAM-01:DET:Acquire 1
28+
caput BL01T-EA-CAM-01:ARR:EnableCallbacks 1
29+
# now see the (changing) value of the image array
30+
caget -#100 BL01T-EA-CAM-01:ARR:ArrayData
31+
caget -#100 BL01T-EA-CAM-01:ARR:ArrayData
32+
...
33+
```
34+
35+
This just shows that you have all the EPICS tools available to you inside the container.
36+
37+
Note that you have the ability to install any other tools you might need inside the container using `sudo apt update; sudo apt install package-name`, the container is based on **ubuntu 24.04** so all packages available for that distro are available to you. podman users should drop the `sudo` from the start of the commands.
38+
39+
If you want to use a GUI tool or any other tools you have installed on your host machine we will need a couple of extra steps.
40+
41+
## Phoebus and Gateway
42+
43+
Generic IOCs can use PVI to auto generate engineering screens for your IOC instance in the form of phoebus bob files. ioc-adsimdetector uses this to make screens for the simdetector driver and for all of the AreaDetector plugins installed in the IOC instance.
44+
45+
To make use of these screens we can use an install phoebus on the host machine or run it in a separate dedicated container. In either case we need our PVs to be accessible from outside of the container. For this purpose we use a separate gateway container which runs in the same network as the IOC container and binds to the channel access ports on the host machine's loopback adapter.
46+
47+
To launch both phoebus in a container and the ca-gateway container we use compose just like we did in the `t01-services` tutorial. The compose file is in the `compose` folder of the `ioc-adsimdetector` repository.
48+
49+
IMPORTANT: the commands we are about to run must be executed on the host, not in the developer container. We are launching further containers here and we do not want 'containers in containers' because there lies madness! To launch the gateway and phoebus containers, open a new terminal on the host and use the following commands:
50+
51+
```bash
52+
cd /workspaces/ioc-adsimdetector/compose
53+
. ./environment.sh
54+
ec up -d
55+
```
56+
57+
Phoebus will be launched and attempt to load the bob file called **opi/ioc/index.bob**. The **opi** folder is a place where the author of this generic IOC could place some screens. The subfolder **ioc** is not committed to git and is where the IOC instance will place its autogenerated engineering screens. The autogenerated screens always include and index.bob which is the entry point to all other autogenerated screens.
58+
59+
## /workspaces in Phoebus Container
60+
61+
Just like the developer container itself, the Phoebus container mounts the folder above **ioc-adsimdetector** into the container as **/workspaces**. This means you can access bob files from peer projects.
62+
63+
The autogenerated engineering screens currently show the image array as a list of integers. But we already had a nice screen for displaying an overview of the PVs, including an image widget for the image array. That screen was made for the same IOC instance we are currently running inside of the developer container.
64+
65+
To access the screen, chose `File -> Open` in phoebus and navigate to **/workspaces/t01-services/opi/demo-simdet.bob** file. This will open the screen in phoebus and allow you to view the sample image.
66+
67+
:::figure
68+
![Phoebus Screen](../images/custom_bob.png)
69+
Example overview screen for bl01t-ea-cam-01
70+
:::
71+
72+
## Using Host Machine Tools
73+
74+
If you have EPICS tools installed on the host machine then those can now also be used.
75+
76+
You will need to tell channel access that it should search against the loopback adapter to find PVs from your developer container. Do this with:
77+
78+
```bash
79+
export EPICS_CA_ADDR_LIST=127.0.0.1
80+
```
81+
82+
If you are running **phoebus** on the host machine it is configured via a settings file. Launching phoebus on your host with the following command will apply the correct settings and launch the index screen for the IOC instance:
83+
84+
```bash
85+
phoebus.sh -settings compose/phoebus/config/settings.ini -resource /opi/ioc/index.bob
86+
```

‎docs/tutorials/ioc_changes1.md

Lines changed: 65 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,20 @@
11
# Changing the IOC Instance
22

3-
This tutorial will make a very simple change to the example IOC `bl01t-ea-test-02`.
4-
This is a type 1 change from {any}`ioc-change-types`, types 2, 3 will be covered in the
5-
following 2 tutorials.
3+
This tutorial will make a very simple change to the example IOC `bl01t-ea-cam-01`. This is a type 1 change from {any}`ioc-change-types`, types 2, 3 will be covered in the following 2 tutorials.
64

7-
Strictly speaking, Type 1 changes do not require a devcontainer. You created
8-
and deployed the IOC instance in a previous tutorial without one. It is up to
9-
you how you choose to make these types of changes. Types 2,3 do require a
10-
devcontainer because they involve compiling Generic IOC / support module code.
5+
Strictly speaking, Type 1 changes do not require a devcontainer. You created and deployed the IOC instance in a previous tutorial without one. It is up to you how you choose to make these types of changes. Types 2,3 do require a devcontainer because they involve compiling Generic IOC / support module code.
116

127
These instructions are for running inside the devcontainer. If you closed your developer container from the last tutorial, then open it again now. To do so, open your `ioc-adsimdetector` folder in vscode and then press `Ctrl-Shift-P` and type `Remote-Containers: Reopen in Container`.
138

149
We are going to add a hand crafted EPICS DB file to the IOC instance. This will be a simple record that we will be able to query to verify that the change is working. We will use the version of the IOC instance that used `ioc.yaml`. If you changed to using raw startup assets in the previous tutorial then revert to using `ioc.yaml` for this tutorial or see [](raw-startup-assets).
1510

16-
:::{note}
17-
Before doing this tutorial make sure you have not left the IOC bl01t-ea-test-02 running from a previous tutorial. Execute this command *outside* of the devcontainer to stop it:
18-
19-
```bash
20-
ec stop bl01t-ea-test-02
21-
```
22-
:::
23-
2411
Make the following changes in your test IOC config folder
25-
(`bl01t/services/bl01t-ea-test-02/config`):
12+
(`/epics/ioc/config` which is currently the same as `/workspaces/t01-services/services/bl01t-ea-cam-01/config`):
2613

2714
1. Add a file called `extra.db` with the following contents.
2815

2916
```text
30-
record(ai, "bl01t-ea-test-02:TEST") {
17+
record(ai, "BL01T-EA-CAM-01:TEST") {
3118
field(DESC, "Test record")
3219
field(DTYP, "Soft Channel")
3320
field(SCAN, "Passive")
@@ -45,118 +32,107 @@ Make the following changes in your test IOC config folder
4532
4633
## Locally Testing Your changes
4734
48-
You can immediately test your changes by running the IOC locally. The following
49-
command will run the IOC locally using the config files in your test IOC config
50-
folder:
35+
You can immediately test your changes by restarting the IOC instance inside the developer container as follows:
5136
5237
```bash
5338
# stop any existing IOC shell by hitting Ctrl-D or typing exit
5439
cd /epics/ioc
5540
./start.sh
5641
```
5742

58-
If all is well you should see your iocShell prompt and the output should
59-
show `dbLoadRecords(config/extra.db)`.
43+
If all is well you should see your iocShell prompt and the output should show `dbLoadRecords(config/extra.db)`.
6044

61-
Test your change
62-
from another terminal (VSCode menus -> Terminal -> New Terminal) like so:
45+
Test your change from another terminal (VSCode menus -> Terminal -> New Terminal) like so:
6346

6447
```bash
65-
caget bl01t-ea-test-02:TEST
48+
caget BL01T-EA-CAM-01:TEST
6649
```
6750

6851
If you see the value 1 then your change is working.
6952

70-
:::{Note}
71-
If you are using podman, you are likely to see *"Identical process variable names on multiple servers"* warnings. This is because caget can see the PV on the host network and the container network, but as these are the same IOC this is not a problem.
7253

73-
You can change this and make your devcontainer network isolated by removing the line `"--net=host",` from `.devcontainer/devcontainer.json`, but it is convenient to leave it if you want to run OPI tools locally on the
74-
host. You may want to isolate your development network if multiple developers are working on the same subnet. In this case some other solution is required for running OPI tools on the host (TODO add link to solution - likely to be container networks).
75-
:::
76-
77-
Because of the symlink between `/epics/ioc/config` and `/workspaces/bl01t/services/bl01t-ea-test-02/config` the same files you are testing by launching the IOC inside of the devcontainer are also ready to be committed and pushed to the bl01t repo. The following commands show how to do this:
54+
Because of the symlink between `/epics/ioc/config` and `/workspaces/bl01t/services/bl01t-ea-cam-01/config` the same files you are testing by launching the IOC inside of the devcontainer are also ready to be committed and pushed to the `t01-services` repo. The following commands show how to do this:
7855

7956
```bash
80-
# Do this from a host terminal (not a devcontainer terminal)
81-
cd bl01t
57+
cd /workspaces/t01-services
8258
git add .
8359
git commit -m "Added extra.db"
8460
git push
8561
# tag a new version of the beamline repo
86-
git tag 2024.3.2
87-
git push origin 2024.3.2
88-
# deploy the new version of the IOC to the local docker / docker instance
89-
ec deploy bl01t-ea-test-02 2024.3.2
62+
git tag 2024.8.2
63+
git push origin 2024.8.2
9064
```
9165

92-
NOTE: the above assumes you have an active python virtual environment with the `edge-containers-cli` installed and you have sourced the beamline environment file (for a reminder of how to do this see {any}`setup-beamline-t01`).
66+
If you like working entirely from the vscode window you can open a terminal in vscode *outside* of the devcontainer. To do so, press `Ctrl-Shift-P` and choose the commnd `Terminal: Create New Integrated Terminal (Local)`. This will open a terminal to the host. You can then run `ec` from there.
9367

94-
You can now see that the versioned IOC instance is running and loading the extra.db by looking at its log with:
68+
## Launching the Test Beamline
9569

96-
```bash
97-
ec logs bl01t-ea-test-02
98-
```
70+
Because the changes have been made in `t01-services` you can now launch the test beamline from outside of the devcontainer.
71+
However, it is important to remember that we cannot have two ca-gateway's trying to bind to the default CA port on the same host.
9972

73+
Make sure the ca-gateway from the previous tutorial is stopped before launching the test beamline with the following:
10074

101-
The above steps were performed on a host terminal because we are using `ec`. However all of the steps except for the `ec` command could have been done *inside* the devcontainer starting with `cd /workspaces/bl01t` which is where your project is mounted *inside* the devcontainer.
75+
```bash
76+
# IMPORTANT: do this in a terminal outside of the devcontainer
77+
cd ioc-adsimdetector/compose
78+
. ./environment.sh
79+
ec down
80+
```
10281

103-
We choose not to have `ec` installed inside of the devcontainer because that would involve containers in containers which adds too much complexity.
82+
Now you can launch your test beamline and it will have picked up the new extras.db.
10483

105-
If you like working entirely from the vscode window you can open a terminal in vscode *outside* of the devcontainer. To do so, press `Ctrl-Shift-P` and choose the commnd `Terminal: Create New Integrated Terminal (Local)`. This will open a terminal to the host. You can then run `ec` from there.
84+
```bash
85+
# IMPORTANT: do this in a terminal outside of the devcontainer
86+
cd t01-services
87+
. ./environment.sh
88+
ec up -d
89+
caget BL01T-EA-CAM-01:TEST
90+
91+
# Now shut down the beamline again so we can continue with further developer container tutorials
92+
ec down
93+
```
10694

107-
(raw-startup-assets)=
10895
## Raw Startup Assets
10996

110-
If you plan not to use `ibek` runtime asset creation you could use the raw
111-
startup assets from the previous tutorial. If you do this then the process
112-
above is identical except that you will add the `dbLoadRecords` command to
113-
the end of `st.cmd`.
97+
If you plan not to use `ibek` runtime asset creation you could use the raw startup assets from {any}`raw-startup-assets`. If you do this then the process above is identical except that you will add the `dbLoadRecords` command to the end of raw `st.cmd`.
11498

11599
## More about ibek Runtime Asset Creation
116100

117-
The set of `entities` that you may create in your ioc.yaml is defined by the
118-
`ibek` IOC schema that we reference at the top of `ioc.yaml`.
119-
The schema is in turn defined by the set of support modules that were compiled
120-
into the Generic IOC (ioc-adsimdetector). Each support module has an
121-
`ibek` *support YAML* file that contributes to the schema.
101+
The set of `entities` that you may create in your ioc.yaml is defined by the `ibek` IOC schema that we reference at the top of `ioc.yaml`. The schema is in turn defined by the set of support modules that were compiled into the Generic IOC (ioc-adsimdetector). Each support module has an `ibek` *support YAML* file that contributes to the schema.
122102

123-
The *Support yaml* files are in the folder `/epics/ibek-defs` inside of the
124-
container. They were placed there during the compilation of the support
125-
modules at Generic IOC build time.
103+
The *Support yaml* files are in the folder `/epics/ibek-defs` inside of the container. They were placed there during the compilation of the support modules at Generic IOC build time.
126104

127-
It can be instructive to look at these files to see what entities are available
128-
to *IOC instances*. For example the global support yaml file
129-
`/epics/ibek-defs/epics.ibek.support.yaml` contains the following:
105+
It can be instructive to look at these files to see what entities are available to *IOC instances*. For example the global support yaml file `/epics/ibek-defs/epics.ibek.support.yaml` contains the following (snippet):
130106

131107
```yaml
132-
- name: StartupCommand
133-
description: Adds an arbitrary command in the startup script before iocInit
134-
args:
135-
- type: str
136-
name: command
137-
description: command string
138-
default: ""
139-
pre_init:
140-
- type: text
141-
value: "{{ command }}"
142-
143-
- name: PostStartupCommand
144-
description: Adds an arbitrary command in the startup script after iocInit
145-
args:
146-
- type: str
147-
name: command
148-
description: command string
149-
default: ""
150-
post_init:
151-
- type: text
152-
value: "{{ command }}"
108+
---
109+
- name: StartupCommand
110+
description: Adds an arbitrary command in the startup script before iocInit
111+
parameters:
112+
command:
113+
type: str
114+
description: command string
115+
default: ""
116+
pre_init:
117+
- type: text
118+
value: "{{ command }}"
119+
120+
- name: PostStartupCommand
121+
description: Adds an arbitrary command in the startup script after iocInit
122+
parameters:
123+
command:
124+
type: str
125+
description: command string
126+
default: ""
127+
post_init:
128+
- type: text
129+
value: "{{ command }}"
130+
---
153131
```
154132

155-
These two definitions allow you to add arbitrary commands to the startup script
156-
before and after iocInit. This is how we added the `dbLoadRecords` command.
133+
These two definitions allow you to add arbitrary commands to the startup script before and after iocInit. This is how we added the `dbLoadRecords` command.
157134

158-
If you want to specify multiple lines in a command you can use the following
159-
syntax for multi-line strings:
135+
If you want to specify multiple lines in a command you can use the following syntax for multi-line strings:
160136

161137
> ```yaml
162138
> - type: epics.StartupCommand
@@ -167,8 +143,6 @@ syntax for multi-line strings:
167143
> dbLoadRecords(config/extra2.db)
168144
> ```
169145
170-
This would place the 4 lines verbatim into the startup script (except that
171-
they would not be indented - the nesting whitespace is stripped).
146+
This would place the 4 lines verbatim into the startup script (except that they would not be indented - the nesting whitespace is stripped).
172147
173-
In later tutorials we will see where the *Support yaml* files come from and
174-
how to add your own.
148+
In later tutorials we will see where the *Support yaml* files come from and how to add your own.

0 commit comments

Comments
 (0)