updated ioc_changes1

gilesknap · gilesknap · commit 27a33b2b337a · 2024-08-13T10:24:15.000+01:00
diff --git a/docs/tutorials/create_ioc.md b/docs/tutorials/create_ioc.md
@@ -389,7 +389,7 @@ ec restart bl01t-ea-cam-01
 
 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.
 
-
+(raw-startup-assets)=
 ## Raw Startup Script and Database
 
 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
 docker if that is what you are using):
 
 ```bash
-docker cp t01-services-bl01t-ea-cam-01-1:/epics/runtime/st.cmd services/bl01t-ea-cam-01/config
-docker cp t01-services-bl01t-ea-cam-01-1:/epics/runtime/ioc.subst services/bl01t-ea-cam-01/config/ioc.subst
+docker cp bl01t-ea-cam-01-1:/epics/runtime/st.cmd services/bl01t-ea-cam-01/config
+docker cp bl01t-ea-cam-01-1:/epics/runtime/ioc.subst services/bl01t-ea-cam-01/config/ioc.subst
 # no longer need an ibek ioc yaml file
 rm services/bl01t-ea-test-02/config/ioc.yaml
 ```
@@ -434,3 +434,13 @@ Restart the IOC to see it operating as before (except that engineering screen ge
 ```bash
 ec restart bl01t-ea-cam-01
 ```
+
+:::{note}
+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:
+```bash
+git checkout -b raw-startup
+git add .
+git commit -m "use raw startup script and database"
+git checkout main
+```
+:::
diff --git a/docs/tutorials/dev_container2.md b/docs/tutorials/dev_container2.md
@@ -46,7 +46,7 @@ To make use of these screens we can use an install phoebus on the host machine o
 
 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.
 
-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 use the following commands:
+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:
 
 ```bash
 cd /workspaces/ioc-adsimdetector/compose
diff --git a/docs/tutorials/ioc_changes1.md b/docs/tutorials/ioc_changes1.md
@@ -1,33 +1,20 @@
 # Changing the IOC Instance
 
-This tutorial will make a very simple change to the example IOC `bl01t-ea-test-02`.
-This is a type 1 change from {any}`ioc-change-types`, types 2, 3 will be covered in the
-following 2 tutorials.
+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.
 
-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.
+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.
 
 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`.
 
 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).
 
-:::{note}
-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:
-
-```bash
-ec stop bl01t-ea-test-02
-```
-:::
-
 Make the following changes in your test IOC config folder
-(`bl01t/services/bl01t-ea-test-02/config`):
+(`/epics/ioc/config` which is currently the same as `/workspaces/t01-services/services/bl01t-ea-cam-01/config`):
 
 1. Add a file called `extra.db` with the following contents.
 
    ```text
-   record(ai, "bl01t-ea-test-02:TEST") {
+   record(ai, "BL01T-EA-CAM-01:TEST") {
       field(DESC, "Test record")
       field(DTYP, "Soft Channel")
       field(SCAN, "Passive")
@@ -45,118 +32,107 @@ Make the following changes in your test IOC config folder
 
 ## Locally Testing Your changes
 
-You can immediately test your changes by running the IOC locally. The following
-command will run the IOC locally using the config files in your test IOC config
-folder:
+You can immediately test your changes by restarting the IOC instance inside the developer container as follows:
 
 ```bash
 # stop any existing IOC shell by hitting Ctrl-D or typing exit
 cd /epics/ioc
 ./start.sh
 ```
 
-If all is well you should see your iocShell prompt and the output should
-show `dbLoadRecords(config/extra.db)`.
+If all is well you should see your iocShell prompt and the output should show `dbLoadRecords(config/extra.db)`.
 
-Test your change
-from another terminal (VSCode menus -> Terminal -> New Terminal) like so:
+Test your change from another terminal (VSCode menus -> Terminal -> New Terminal) like so:
 
 ```bash
-caget bl01t-ea-test-02:TEST
+caget BL01T-EA-CAM-01:TEST
 ```
 
 If you see the value 1 then your change is working.
 
-:::{Note}
-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.
 
-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
-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).
-:::
-
-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:
+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:
 
 ```bash
-# Do this from a host terminal (not a devcontainer terminal)
-cd bl01t
+cd /workspaces/t01-services
 git add .
 git commit -m "Added extra.db"
 git push
 # tag a new version of the beamline repo
-git tag 2024.3.2
-git push origin 2024.3.2
-# deploy the new version of the IOC to the local docker / docker instance
-ec deploy bl01t-ea-test-02 2024.3.2
+git tag 2024.8.2
+git push origin 2024.8.2
 ```
 
-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`).
+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.
 
-You can now see that the versioned IOC instance is running and loading the extra.db by looking at its log with:
+## Launching the Test Beamline
 
-```bash
-ec logs bl01t-ea-test-02
-```
+Because the changes have been made in `t01-services` you can now launch the test beamline from outside of the devcontainer.
+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.
 
+Make sure the ca-gateway from the previous tutorial is stopped before launching the test beamline with the following:
 
-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.
+```bash
+# IMPORTANT: do this in a terminal outside of the devcontainer
+cd ioc-adsimdetector/compose
+. ./environment.sh
+ec down
+```
 
-We choose not to have `ec` installed inside of the devcontainer because that would involve containers in containers which adds too much complexity.
+Now you can launch your test beamline and it will have picked up the new extras.db.
 
-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.
+```bash
+# IMPORTANT: do this in a terminal outside of the devcontainer
+cd t01-services
+. ./environment.sh
+ec up -d
+caget BL01T-EA-CAM-01:TEST
+
+# Now shut down the beamline again so we can continue with further developer container tutorials
+ec down
+```
 
-(raw-startup-assets)=
 ## Raw Startup Assets
 
-If you plan not to use `ibek` runtime asset creation you could use the raw
-startup assets from the previous tutorial. If you do this then the process
-above is identical except that you will add the `dbLoadRecords` command to
-the end of `st.cmd`.
+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`.
 
 ## More about ibek Runtime Asset Creation
 
-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.
+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.
 
-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.
+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.
 
-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:
+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):
 
 ```yaml
-- name: StartupCommand
-  description: Adds an arbitrary command in the startup script before iocInit
-  args:
-    - type: str
-      name: command
-      description: command string
-      default: ""
-  pre_init:
-    - type: text
-      value: "{{ command }}"
-
-- name: PostStartupCommand
-  description: Adds an arbitrary command in the startup script after iocInit
-  args:
-    - type: str
-      name: command
-      description: command string
-      default: ""
-  post_init:
-    - type: text
-      value: "{{ command }}"
+  ---
+  - 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 }}"
+
+  - name: PostStartupCommand
+    description: Adds an arbitrary command in the startup script after iocInit
+    parameters:
+      command:
+        type: str
+        description: command string
+        default: ""
+    post_init:
+      - type: text
+        value: "{{ command }}"
+  ---
 ```
 
-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.
+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.
 
-If you want to specify multiple lines in a command you can use the following
-syntax for multi-line strings:
+If you want to specify multiple lines in a command you can use the following syntax for multi-line strings:
 
 > ```yaml
 > - type: epics.StartupCommand
@@ -167,8 +143,6 @@ syntax for multi-line strings:
 >     dbLoadRecords(config/extra2.db)
 > ```
 
-This would place the 4 lines verbatim into the startup script (except that
-they would not be indented - the nesting whitespace is stripped).
+This would place the 4 lines verbatim into the startup script (except that they would not be indented - the nesting whitespace is stripped).
 
-In later tutorials we will see where the *Support yaml* files come from and
-how to add your own.
+In later tutorials we will see where the *Support yaml* files come from and how to add your own.
