Update docs and CI

Author: coretl

.github/workflows/code.yml

@@ -87,7 +87,7 @@ jobs:
         run: cibuildwheel --output-dir dist
         env:
           CIBW_BUILD: ${{ matrix.python }}*64
-          CIBW_TEST_REQUIRES: pytest-cov ${{ matrix.test_requires }}
+          CIBW_TEST_REQUIRES: pytest-cov p4p ${{ matrix.test_requires }}
           CIBW_TEST_COMMAND: pytest --cov=softioc {project}/tests --cov-report xml:${{ matrix.cov_file }}
           # Disable auditwheel as it isn't compatible with setuptools_dso approach
           # https://github.com/mdavidsaver/setuptools_dso/issues/17

CHANGELOG.rst

@@ -9,7 +9,9 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
 Unreleased_
 -----------
 
-Nothing yet
+Added:
+
+- PVA support to the IOC #17
 
 
 3.0_ - 2021-07-05

docs/examples/example_read_from_ioc.py docs/examples/example_read_from_ioc_ca.pydocs/examples/example_read_from_ioc.py renamed to docs/examples/example_read_from_ioc_ca.py

@@ -1,9 +1,6 @@
-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"))
+caput("MY-DEVICE-PREFIX:AO", "999")
 print(caget("MY-DEVICE-PREFIX:AO"))
-
-softioc.interactive_ioc(globals())

docs/examples/example_read_from_ioc_pva.py

@@ -0,0 +1,7 @@
+from p4p.client.cothread import Context
+
+ctx = Context("pva")
+print(ctx.get("MY-DEVICE-PREFIX:AI"))
+print(ctx.get("MY-DEVICE-PREFIX:AO"))
+ctx.put("MY-DEVICE-PREFIX:AO", "999")
+print(ctx.get("MY-DEVICE-PREFIX:AO"))

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

@@ -1,31 +1,54 @@
 Read data from an IOC
 ======================
 
-This guide explains how to read data from an IOC in a separate Python program. 
+This guide explains how to read data from an IOC in a separate Python program.
 
-.. note:: 
-    Please ensure your firewall allows both TCP and UDP traffic on ports 5064 and 5065. 
+To start, run the `cothread` IOC from `../tutorials/creating-an-ioc` or the
+`asyncio` IOC from `use-asyncio-in-an-ioc` and leave it running at the
+interactive shell.
+
+Using Channel Access
+--------------------
+
+.. 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.
 
+We will read data from the IOC using this script:
 
-To start, run the `cothread` IOC from `../tutorials/creating-an-ioc` or the 
-`asyncio` IOC from `use-asyncio-in-an-ioc` and leave it running at the 
-interactive shell.
+.. literalinclude:: ../examples/example_read_from_ioc_ca.py
 
-We will read data from that IOC using this script:
+You can run this as::
 
-.. literalinclude:: ../examples/example_read_from_ioc.py
+    python -i example_read_from_ioc_ca.py
+
+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)
+
+You should observe the value of ``AI`` being printed out, once per second, every time the PV value
+updates.
+
+Using PVAccess
+--------------
 
 .. 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.
+    Please ensure your firewall allows both TCP and UDP traffic on ports 5075 and 5076.
+    These are used by EPICS for PVAccess to the PVs.
 
-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::
+We will read data from the IOC using this script:
 
-    camonitor("MY-DEVICE-PREFIX:AI", lambda val: print(val))
+.. literalinclude:: ../examples/example_read_from_ioc_pva.py
 
+You can run this as::
 
-You should observe the value of ``AI`` being printed out, once per second, every time the PV value
-updates. 
+    python -i example_read_from_ioc_pva.py
+
+From the interactive command line you can now use the ``ctx.get`` and ``ctx.put`` functions to operate on
+the PVs exposed in the IOC. Another interesting command to try is::
+
+    ctx.monitor("MY-DEVICE-PREFIX:AI", print)
+
+You should observe the value and timestamp of ``AI`` being printed out, once per second, every time the PV value
+updates.

docs/tutorials/creating-an-ioc.rst

@@ -4,8 +4,8 @@ Creating an IOC
 Introduction
 ------------
 
-Once the module has been installed (see `installation`) we can create a 
-simple EPICS Input/Output Controller (IOC). 
+Once the module has been installed (see `installation`) we can create a
+simple EPICS Input/Output Controller (IOC).
 
 An EPICS IOC created with the help of ``pythonIoc`` and `softioc` is
 referred to as a "Python soft IOC".  The code below illustrates a simple IOC
@@ -19,30 +19,32 @@ Each section is explained in detail below:
     :start-after: # Import
     :end-before: # Set
 
-The `softioc` library is part of ``pythonIoc``. The two submodules 
-`softioc.softioc` and `softioc.builder` provide the basic 
+The `softioc` library is part of ``pythonIoc``. The two submodules
+`softioc.softioc` and `softioc.builder` provide the basic
 functionality for Python soft IOCs and are the ones that are normally used.
 
 `cothread` is one of the two possible libraries the IOC can use for
-asynchronous operations. 
-(see `../how-to/use-asyncio-in-an-ioc` for the alternative)
+asynchronous operations.
 
+.. note::
 
+    `cothread` doesn't work on Windows or on a Mac M1. You can use `asyncio`
+    instead by following `../how-to/use-asyncio-in-an-ioc`
 
 .. literalinclude:: ../examples/example_cothread_ioc.py
-    :start-after: # Create 
+    :start-after: # Create
     :end-before: # Boilerplate
 
 PVs are normally created dynamically using `softioc.builder`.  All PV
-creation must be done before initialising the IOC. We define a lambda function for 
-`on_update` on ``ao`` such that whenever we set ``ao``, ``ai`` will be set to the 
-same value. The ``always_update`` flag ensures that the ``on_update`` function is always 
+creation must be done before initialising the IOC. We define a lambda function for
+`on_update` on ``ao`` such that whenever we set ``ao``, ``ai`` will be set to the
+same value. The ``always_update`` flag ensures that the ``on_update`` function is always
 triggered, which is not the default behaviour if the updated value is the same as the
 current value.
 
 
 .. literalinclude:: ../examples/example_cothread_ioc.py
-    :start-after: # Boilerplate 
+    :start-after: # Boilerplate
     :end-before: # Start
 
 
@@ -52,14 +54,14 @@ which must be called in this order.  After calling
 :func:`~softioc.builder.LoadDatabase` it is no longer possible to create PVs.
 
 .. literalinclude:: ../examples/example_cothread_ioc.py
-    :start-after: # Start 
+    :start-after: # Start
     :end-before: # Finally
 
 We define a long-running operation that will increment the value of ``ai`` once per
-second. This is run as a background thread by `cothread`. 
+second. This is run as a background thread by `cothread`.
 
 .. literalinclude:: ../examples/example_cothread_ioc.py
-    :start-after: # Finally 
+    :start-after: # Finally
 
 Finally the application must refrain from exiting until the IOC is no longer
 needed.  The :func:`~softioc.softioc.interactive_ioc` runs a Python
@@ -69,7 +71,7 @@ internals of the IOC while it's running.  The alternative is to call something
 like :func:`cothread.WaitForQuit` or some other `cothread` blocking
 action.
 
-In this interpreter there is immediate access to methods defined in the 
+In this interpreter there is immediate access to methods defined in the
 `softioc.softioc` module. For example the :func:`~softioc.softioc.dbgf` function
 can be run to observe the increasing value of ``AI``::
 
@@ -79,15 +81,15 @@ can be run to observe the increasing value of ``AI``::
     DBF_DOUBLE:         37
 
 And the :func:`~softioc.softioc.dbpf` method allows data to be set and to observe
-the functionality of the lambda passed to ``on_update`` . We set the value on ``AO`` 
+the functionality of the lambda passed to ``on_update`` . We set the value on ``AO``
 and read the value on ``AI`` (exact values will vary based on time taken)::
 
     >>> dbgf("MY-DEVICE-PREFIX:AI")
     DBF_DOUBLE:         15
     >>> dbpf("MY-DEVICE-PREFIX:AO","999")
-    DBF_DOUBLE:         999       
+    DBF_DOUBLE:         999
     >>> dbgf("MY-DEVICE-PREFIX:AI")
-    DBF_DOUBLE:         1010   
+    DBF_DOUBLE:         1010
 
 
 Creating PVs

docs/tutorials/installation.rst

@@ -35,8 +35,8 @@ You can now use ``pip`` to install the library::
 
     python3 -m pip install softioc
 
-Optionally on Linux or MacOS you can install cothread, which is used in the
-first tutorial::
+Optionally on Linux or MacOS (not M1) you can install cothread, which is used in
+the first tutorial::
 
     python3 -m pip install cothread