Merge pull request #28 from epics-containers/dev

complete rtems ioc tutorial

Author: gilesknap

docs/user/reference/ioc_helm_chart.rst

@@ -3,7 +3,7 @@ IOC Helm Chart Details
 
 IOC instances are described using a helm chart which in turn generates
 a Kubernetes manifest to tell Kubernetes what resources to create in order
-to run for the IOC instance.
+to run the IOC instance.
 
 Here we will look inside the template IOC instance in the template
 domain repository blxxi-template.

docs/user/tutorials/create_beamline.rst

@@ -98,6 +98,9 @@ repo in the future.
         to your unique name and edit the ``name:`` field at the top of
         ``Chart.yaml`` to match the folder name.
 
+        If you do this - remember to substitute in your own name in the
+        following steps, replacing bl01t-ea-ioc-01.
+
 #.  Add your new repo to your VSCode workspace and take a look at what you
     have.
 
@@ -167,6 +170,5 @@ for it and published ready for deployment to your cluster.
 In the next tutorial we will look into what we have created in more detail
 and we will deploy and test the new example IOC.
 
-
-TODO: I need to describe the contents of beamline-chart folder somewhere and
-this might be a good place to do that.
+For details of what goes into the helm chart of an IOC instance see
+`../reference/ioc_helm_chart`.

docs/user/tutorials/ioc_changes.rst

@@ -114,6 +114,8 @@ in the container like this:
 
 When you type exit on the iocShell the container will stop and and be removed.
 
+.. _local_deploy_ioc:
+
 Deploying a Beta IOC Instance to The Cluster
 ============================================
 

docs/user/tutorials/rtems_ioc.rst

@@ -235,10 +235,59 @@ You are now ready to deploy the IOC instance to the cluster and test it out.
 Deploying an RTEMS IOC Instance
 -------------------------------
 
-TODO:
+To deploy an IOC instance to the cluster you can use one of two approaches:
 
-Once you have the correct configuration in your RTEMS boot-loader and you have
-deployed the kubernetes IOC instance, you can restart the IOC with
-the ``reset`` command. This will cause it to reboot and it should pick
-up your binary from the network and start the IOC. You should see the
-iocShell fire up and run
+- push your beamline repo to GitHub and tag it. Then use ``ec ioc deploy`` to
+  deploy the resulting versioned IOC instance. This was covered for linux IOCs
+  in `deploy_example`.
+
+- use ``ec ioc deploy-local`` to directly deploy the local copy of the IOC
+  instance helm chart to kubernetes as a beta version. This was covered for
+  linux IOCs in `local_deploy_ioc`.
+
+Both types of deployment of IOC instances above work exactly the same for
+linux and RTEMS IOCs. We will do the latter as it is quicker for
+the purposes of the tutorial.
+
+Execute the following commands:
+
+.. code-block:: bash
+
+    cd bl01t
+    ec ioc deploy-local iocs/bl01t-ea-ioc-02
+
+When an RTEMS Kubernetes pod runs up it will make a telnet connection to
+the hard IOC's console and present the console as stdin/stdout of the
+container. This means once you have done the above deployment the command:
+
+
+.. code-block:: bash
+
+    ec logs bl01t-ea-ioc-02 -f
+
+will show the RTEMS console output, and follow it along (``-f``) as the IOC
+starts up. You can hit ``^C`` to stop following the logs.
+
+You can also attach to the container and interact with the RTEMS console via
+the telnet connection with:
+
+.. code-block:: bash
+
+    ec attach bl01t-ea-ioc-02
+
+Most likely for the first deploy your IOC will still be sitting at the
+``MVME5500>`` prompt. If you see this prompt when you attach then you need
+to type ``reset`` to restart the boot-loader. This should then go through
+the boot-loader startup and eventually start the IOC.
+
+Checking your RTEMS IOC
+-----------------------
+
+To verify that your RTEMS IOC is working you should be able to execute the
+following commands and get correct sum of the A and B values:
+
+.. code-block:: bash
+
+    caput bl01t-ea-ioc-02:A 12
+    caput get bl01t-ea-ioc-02:B 13
+    caget get bl01t-ea-ioc-02:SUM