Skip to content

Commit 7c31e21

Browse files
gilesknapgilesknap
committed
started ioc_changes2
1 parent 0603120 commit 7c31e21

File tree

8 files changed

+195
-26
lines changed

8 files changed

+195
-26
lines changed

‎.vscode/settings.json

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,10 @@
11
{
2-
"python.linting.pylintEnabled": false,
3-
"python.linting.flake8Enabled": true,
4-
"python.linting.mypyEnabled": true,
5-
"python.linting.enabled": true,
62
"python.testing.pytestArgs": [],
73
"python.testing.unittestEnabled": false,
84
"python.testing.pytestEnabled": true,
9-
"python.formatting.provider": "black",
10-
"python.languageServer": "Pylance",
115
"editor.formatOnSave": true,
126
"editor.codeActionsOnSave": {
13-
"source.organizeImports": true
7+
"source.organizeImports": "explicit"
148
},
159
"cSpell.words": [
1610
"Beamlines",

‎docs/user/explanations/ioc-source.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. _ioc-source:
2+
3+
Dev Container vs Runtime Container
4+
==================================
5+
6+
TODO: explain how and why ioc-xxxx is mounted in dev container and what happens
7+
to the ioc folder.
8+

‎docs/user/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ side-bar.
2222
tutorials/ioc_changes1
2323
tutorials/ioc_changes2
2424
tutorials/ioc_changes3
25+
tutorials/ioc_changes4
2526
tutorials/generic_ioc
2627
tutorials/debug_generic_ioc
2728
tutorials/test_generic_ioc
@@ -61,6 +62,7 @@ side-bar.
6162
explanations/kubernetes_cluster
6263
explanations/docs-structure
6364
explanations/repositories
65+
explanations/ioc-source
6466

6567
+++
6668

‎docs/user/tutorials/ioc_changes1.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,11 @@ However all of the steps except for the ``ec`` command could have been done
110110
We choose not to have ``ec`` installed inside of the devcontainer because
111111
that would involve containers in containers which adds too much complexity.
112112

113+
If you like working entirely from the vscode window you can open a terminal
114+
in vscode *outside* of the devcontainer. To do so, press ``Ctrl-Shift-P`` and
115+
choose the commnd ``Terminal: Create New Integrated Terminal (Local)``.
116+
This will open a terminal to the host. You can then run ``ec`` from there.
117+
113118
Raw Startup Assets
114119
------------------
115120

‎docs/user/tutorials/ioc_changes2.rst

Lines changed: 112 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,117 @@
1-
Changing the Generic IOC
2-
========================
1+
Changing a Generic IOC Part 1
2+
=============================
33

4-
This tutorial will make a simple change to the Generic IOC ``ioc-adsimdetector``.
5-
We will also update the IOC instance ``bl01t-ea-ioc-02`` use the new feature of
6-
the Generic IOC.
74
This is a type 2 change from `ioc_change_types`.
85

9-
We are going to add an additional support module to the Generic IOC and then
10-
use it to add a new record to the IOC instance to use this new support.
6+
The changes that you can make in an IOC instance are limited to what
7+
the author of a generic IOC has made configurable. Therefore you will
8+
occasionally need to update the generic IOC that your instance is using.
9+
Some of the reasons for doing this are:
1110

12-
For this exercise all changes will be local so you will not need to make a
13-
fork of ``ioc-adsimdetector``. The next tutorial will show how to a new
14-
Generic IOC and we will look at the Generic IOC CI at that time.
11+
- Update one or more support modules to new versions
12+
- Add additional support such as autosave or iocStats
13+
- For ibek generated IOC instances, you may need to add or change functionality
14+
in the support YAML file.
1515

16-
TODO: WIP.
16+
This tutorial will make some changes to the generic IOC ``ioc-adsample``.
17+
This Generic IOC is a simplified copy of ``ioc-adsimdetector`` tailored for
18+
use in these tutorials.
19+
20+
For this exercise we will initially work locally inside the ``ioc-adsample``
21+
developer container.
22+
23+
At the end we will push the changes and see the CI build a new version of the
24+
generic IOC container image. This allows for the demonstration of:
25+
26+
- Deploying an IOC instance using a new image published by the CI
27+
- Showing how to do a Pull Request back to the original repository.
28+
29+
For this exercise we will be using an example IOC Instance to test our changes.
30+
Instead of working with a beamline repository, we will use the example ioc instance
31+
that comes with ``ioc-adsample``. It is a good idea for Generic IOC authors to
32+
include an example IOC Instance in their repository for testing changes in
33+
isolation.
34+
35+
36+
Preparation
37+
-----------
38+
39+
Because we want to push our changes we will first make a fork of the
40+
``ioc-adsample`` repository. We will then clone our fork locally and
41+
make the changes there.
42+
43+
To make a fork go to
44+
`ioc-adsample <https://github.com/epics-containers/ioc-adsample>`_
45+
and click the ``Fork`` button in the top right corner. This will create a fork
46+
of the repository under your own GitHub account.
47+
48+
Now, clone the fork, build the container image locally and open the
49+
developer container:
50+
51+
.. code-block:: console
52+
53+
git clone [email protected]:<YOUR GITHUB ACCOUNT NAME>/ioc-adsample.git
54+
cd ioc-adsample
55+
./build
56+
code .
57+
# click the green button in the bottom left corner of vscode and select
58+
# "Reopen in Container"
59+
60+
The ``build`` script does two things.
61+
62+
- it fetches the git submodule called ``ibek-support``. This submodule is shared
63+
between all the EPICS IOC container images and contains the support YAML files
64+
that tell ``ibek`` how to build support modules inside the container
65+
environment.
66+
- it builds the Generic IOC container image locally.
67+
68+
.. note::
69+
70+
The ``build`` script is a convenience script that is provided in the
71+
Generic IOC Template project. It is exactly equivalent to cloning
72+
with ``--recursive`` flag and then running ``ec dev build``.
73+
74+
Verify the Example IOC Instance is working
75+
------------------------------------------
76+
77+
When a new Generic IOC developer container is opened, there are two things
78+
that need to be done before you can run an IOC instance inside of it.
79+
80+
- Build the IOC source code
81+
- Select an IOC instance definition to run
82+
83+
The folder ``ioc`` inside of the ``ioc-adsample`` is where the IOC source code
84+
is created and built. When you open the developer container, this folder does
85+
not yet exist. The following command will create it and build the IOC:
86+
87+
.. code-block:: console
88+
89+
ec ioc build
90+
91+
The IOC instance definition is a YAML file that tells ``ibek`` what the runtime
92+
assets (ie. EPICS DB and startup script) should look like. Previous tutorials
93+
selected the IOC instance definition from a beamline repository. In this case
94+
we will use the example IOC instance that comes with ``ioc-adsample``. The
95+
following command will select the example IOC instance:
96+
97+
.. code-block:: console
98+
99+
ibek dev instance /epics/ioc-adsample/ioc_examples/bl01t-ea-ioc-02
100+
101+
Now run the IOC:
102+
103+
.. code-block:: console
104+
105+
ibek dev run
106+
107+
You should see a iocShell prompt and no error messages above.
108+
109+
.. note::
110+
111+
The ``ec ioc build`` command required to re-create the IOC source code.
112+
This is even though the container you are using already had the IOC
113+
source code built by its Dockerfile (``ioc-adsample/Dockerfile``
114+
contains the same command).
115+
116+
For a detailed explanation of why this is the case see
117+
`ioc-source`

‎docs/user/tutorials/ioc_changes3.rst

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
1-
Making a new Support Module
2-
===========================
1+
Changing a Generic IOC Part 2
2+
=============================
33

4-
This tutorial will create a new Generic IOC for a new support module. We will
5-
then create a new IOC Instance that uses this new support module.
6-
This is a type 3 change from `ioc_change_types`.
4+
This is a type 2 change from `ioc_change_types`.
5+
6+
This tutorial will change the support yaml used by a generic IOC.
77

8-
This exercise will create a new Stream Device support module that implements
9-
a very simple ASCII protocol. So simple that we will be able to test it
10-
by typing into a telnet session.
118

129
TODO: WIP.

‎docs/user/tutorials/ioc_changes4.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Making a new Support Module
2+
===========================
3+
4+
This tutorial will create a new Generic IOC for a new support module. We will
5+
then create a new IOC Instance that uses this new support module.
6+
This is a type 3 change from `ioc_change_types`.
7+
8+
This exercise will create a new Stream Device support module that implements
9+
a very simple ASCII protocol. So simple that we will be able to test it
10+
by typing into a telnet session.
11+
12+
TODO: WIP.

‎docs/user/tutorials/notes.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
Things to write about in the coming chapters.
2+
=============================================
3+
4+
ioc_changes1.rst - simple change to an IOC instance
5+
---------------------------------------------------
6+
done
7+
8+
ioc_changes2.rst - simple change to a generic IOC
9+
-------------------------------------------------
10+
11+
Use a fork of ioc-sampledetector
12+
to update the version number of adsimdetector and to add dev-iocstats
13+
(ioc-sampledetector is copy of ioc-adsimdetector with some changes -
14+
deviocstats is removed and it is using an earlier version of adsimdetector
15+
support)
16+
17+
- push and run the CI
18+
- verify a local instance can use resulting image
19+
- add dev-iocstats and update generic IOC version number
20+
- do a pull request back to ec
21+
22+
ioc_changes3.rst - a change to ibek-support
23+
-------------------------------------------
24+
25+
Add some kind of additional feature into ioc-adsampledetector
26+
maybe something from one of the ADCore plugins
27+
28+
- requires forking and updating ibek-support
29+
- also update ioc-sampledetector to ue the new ibek-support
30+
- verify a local instance can use resulting image
31+
- do a pull request back to ec
32+
33+
34+
generic_ioc.rst - make a new generic IOC
35+
----------------------------------------
36+
37+
This will involve creating a new support module from scratch and
38+
making a generic IOC for it.
39+
40+
The support module will be a very basic stream device.
41+
42+
Note that the generic IOC comes first because it provides the development
43+
environment for the support module.
44+
45+
IMPORTANT: this serves as a how-to for if you already have a support module
46+
and want to make a generic IOC for it.
47+
TODO: maybe it is worth having a seperate how-to for and existing areadetector
48+
support module because this will be a common use case and we can use
49+
ioc-adsimdetector as the template (I made it a template for this reason).
50+

0 commit comments

Comments
 (0)