New how-to read from an IOC. Some touchups to other work.

Author: AlexanderWells-diamond

docs/examples/example_read_from_ioc.py

@@ -0,0 +1,12 @@
+from softioc import softioc
+from cothread.catools import caget, caput, camonitor
+
+print(caget("MY-DEVICE-PREFIX:AI"))
+print(caget("MY-DEVICE-PREFIX:AO"))
+print(caput("MY-DEVICE-PREFIX:AO", "999"))
+print(caget("MY-DEVICE-PREFIX:AO"))
+
+def print_val(value: float):
+    print(value)
+
+softioc.interactive_ioc(globals())

docs/how-to/read-data-from-ioc.rst

@@ -0,0 +1,31 @@
+Read data from an IOC
+======================
+
+This guide explains how to read data from an IOC from a separate Python program. 
+
+.. note:: 
+    Please ensure your firewall allows both TCP and UDP traffic on ports 5064 and 5065. 
+    These are used by EPICS for channel access to the PVs.
+
+
+To start, run the :mod:`cothread` IOC from :doc:`../tutorials/creating-an-ioc` or the 
+:mod:`asyncio` IOC from :doc:`use-asyncio-in-an-ioc` and leave it running at the 
+interactive shell.
+
+We will read data from that IOC using this script:
+
+.. literalinclude:: ../examples/example_read_from_ioc.py
+
+.. note::
+    You may see warnings regarding the missing "caRepeater" program. This is an EPICS tool
+    that is used to track when PVs start and stop. It is not required for this simple example,
+    and so the warning can be ignored.
+
+From the interactive command line you can now use the ``caget`` and ``caput`` functions to operate on 
+the PVs exposed in the IOC. Another interesting command to try is::
+
+    camonitor("MY-DEVICE-PREFIX:AI", print_val)
+
+
+You should observe the value of ``AI`` being printed out, once per second, every time the PVs value
+updates. 

docs/how-to/use-asyncio-in-an-ioc.rst

@@ -13,7 +13,8 @@ an IOC.
 
 
 The ``dispatcher`` is created and passed to :func:`~softioc.softioc.iocInit`. This is what 
-allows the use of :mod:`asyncio` functions in this IOC.
+allows the use of :mod:`asyncio` functions in this IOC. It contains a new event loop to handle
+this.
 
 The ``async update`` function will increment the value of ``ai`` once per second,
 sleeping that coroutine between updates.
@@ -28,5 +29,5 @@ shell open. The values of the PVs can be queried using the methods defined in th
 Asynchronous Channel Access
 ---------------------------
 
-PVs can be retrieved in an asynchronous manner by using the :py:mod:`aioca` module. 
-It provides ``await``-able implementations of ``caget``, ``caput``, etc.
+PVs can be retrieved externally from a PV in an asynchronous manner by using the :py:mod:`aioca` module. 
+It provides ``await``-able implementations of ``caget``, ``caput``, etc. See that module for more information.

docs/index.rst

@@ -60,6 +60,7 @@ Table Of Contents
 
     how-to/use-asyncio-in-an-ioc
     how-to/make-publishable-ioc
+    how-to/read-data-from-ioc
 
 .. toctree::
     :caption: Explanations