docs: add comprehensive documentation structure and API reference

Created topic-based documentation: - basics.rst: core concepts and fundamental usage - cyclic_programming.rst: PLC-style programming with Cycletools - event_programming.rst: event-driven patterns and callbacks - advanced.rst: gateway IOs, replace_io_file, watchdog management - installation.rst and quickstart.rst: getting started guides Added complete API reference in docs/api/: - All device classes including ModularBaseConnect_4_5 and GatewayMixin - I/O, helper, and main class documentation Enhanced Sphinx configuration with RTD theme and improved autodoc settings. Removed auto-generated modules.rst and revpimodio2.rst.
2026-03-31 23:18:04 +02:00 · 2026-02-03 14:59:39 +01:00
parent b35edac694
commit 2eac69b7bd
15 changed files with 3513 additions and 102 deletions
--- a/docs/api/device.rst
+++ b/docs/api/device.rst
@@ -0,0 +1,163 @@
+==============
+Device Classes
+==============
+
+Classes for managing Revolution Pi devices.
+
+.. currentmodule:: revpimodio2.device
+
+Device
+======
+
+.. autoclass:: Device
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Base class for all Revolution Pi devices.
+
+DeviceList
+==========
+
+.. autoclass:: DeviceList
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__, __getitem__, __iter__
+
+   Container for accessing devices.
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Access device by name
+       dio_module = rpi.device.DIO_Module_1
+
+       # Access device by position
+       first_device = rpi.device[0]
+
+       # Iterate all devices
+       for device in rpi.device:
+           print(f"Device: {device.name}")
+
+Base
+====
+
+.. autoclass:: Base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Base class for Revolution Pi base modules.
+
+GatewayMixin
+============
+
+.. autoclass:: GatewayMixin
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   Mixin class providing gateway functionality for piGate modules.
+
+ModularBaseConnect_4_5
+======================
+
+.. autoclass:: ModularBaseConnect_4_5
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Base class for Connect 4 and Connect 5 modules.
+
+Core
+====
+
+.. autoclass:: Core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Revolution Pi Core module.
+
+Connect
+=======
+
+.. autoclass:: Connect
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Revolution Pi Connect module.
+
+Connect4
+========
+
+.. autoclass:: Connect4
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Revolution Pi Connect 4 module.
+
+Connect5
+========
+
+.. autoclass:: Connect5
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Revolution Pi Connect 5 module.
+
+DioModule
+=========
+
+.. autoclass:: DioModule
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Digital I/O module.
+
+RoModule
+========
+
+.. autoclass:: RoModule
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Relay output module.
+
+Gateway
+=======
+
+.. autoclass:: Gateway
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Gateway module (ModbusTCP, Profinet, etc.).
+
+Virtual
+=======
+
+.. autoclass:: Virtual
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Virtual device for custom applications.
--- a/docs/api/helper.rst
+++ b/docs/api/helper.rst
@@ -0,0 +1,194 @@
+==============
+Helper Classes
+==============
+
+Helper classes for cyclic and event-driven programming.
+
+.. currentmodule:: revpimodio2.helper
+
+Cycletools
+==========
+
+.. autoclass:: Cycletools
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Toolkit provided to cyclic functions via ``.cycleloop()``.
+
+   This class provides tools for cyclic functions including timing flags
+   and edge markers. Note that edge markers (flank flags) are all True
+   during the first cycle!
+
+   **Attributes:**
+
+
+
+      Reference to RevPiModIO core object
+
+
+
+      Reference to RevPiModIO device object
+
+
+
+      Reference to RevPiModIO io object
+
+
+
+      True only on first cycle
+
+
+
+      True when shutdown signal received
+
+
+
+      Current function execution time in seconds
+
+
+
+      Container for cycle-persistent variables
+
+   **Toggle Flags** - Alternate between True/False:
+
+
+
+      1 cycle True, 1 cycle False
+
+
+
+      2 cycles True, 2 cycles False
+
+
+
+      5 cycles True, 5 cycles False
+
+
+
+      10 cycles True, 10 cycles False
+
+
+
+      20 cycles True, 20 cycles False
+
+   **Flank Flags** - True every nth cycle:
+
+
+
+      True every 5 cycles
+
+
+
+      True every 10 cycles
+
+
+
+      True every 15 cycles
+
+
+
+      True every 20 cycles
+
+   **Example:**
+
+   .. code-block:: python
+
+       def main(ct: revpimodio2.Cycletools):
+           if ct.first:
+               # Initialize
+               ct.var.counter = 0
+
+           # Main logic
+           if ct.changed(ct.io.sensor):
+               ct.var.counter += 1
+
+           # Blink LED using timing flag
+           ct.io.led.value = ct.flag5c
+
+           if ct.last:
+               # Cleanup
+               print(f"Final: {ct.var.counter}")
+
+Change Detection
+----------------
+
+
+Timer Functions
+---------------
+
+On-Delay Timers
+~~~~~~~~~~~~~~~
+
+
+Off-Delay Timers
+~~~~~~~~~~~~~~~~
+
+
+Pulse Timers
+~~~~~~~~~~~~
+
+
+EventCallback
+=============
+
+.. autoclass:: EventCallback
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Thread for internal event function calls.
+
+   This class is passed to threaded event handlers registered with
+   ``as_thread=True``. The event function receives this thread object
+   as a parameter to access event information and control execution.
+
+   **Attributes:**
+
+
+
+      Name of IO that triggered the event
+
+
+
+      Value of IO when event was triggered
+
+
+
+      Threading event for abort conditions
+
+   **Example:**
+
+   .. code-block:: python
+
+       def threaded_handler(eventcallback: revpimodio2.EventCallback):
+           print(f"{eventcallback.ioname} = {eventcallback.iovalue}")
+
+           # Interruptible wait (3 seconds)
+           if eventcallback.exit.wait(3):
+               print("Wait interrupted!")
+               return
+
+           # Check if stop was called
+           if eventcallback.exit.is_set():
+               return
+
+       # Register as threaded event
+       rpi.io.button.reg_event(threaded_handler, as_thread=True)
+
+Methods
+-------
+
+
+ProcimgWriter
+=============
+
+.. autoclass:: ProcimgWriter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Internal thread for process image writing and event management.
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -0,0 +1,148 @@
+.. _api_reference:
+
+=============
+API Reference
+=============
+
+Complete API reference for RevPiModIO2 Python library.
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Overview
+========
+
+RevPiModIO provides several main classes for programming Revolution Pi hardware:
+
+* :class:`~revpimodio2.modio.RevPiModIO` - Main class for managing all devices and IOs
+* :class:`~revpimodio2.modio.RevPiModIOSelected` - Manage specific devices only
+* :class:`~revpimodio2.modio.RevPiModIODriver` - Write data to virtual device inputs
+* :class:`~revpimodio2.io.IOList` - Container for accessing IOs
+* :class:`~revpimodio2.io.IOBase` - Base class for all IO objects
+* :class:`~revpimodio2.helper.Cycletools` - Toolkit for cyclic programming
+* :class:`~revpimodio2.helper.EventCallback` - Event handler class
+
+Quick Examples
+==============
+
+Basic Usage
+-----------
+
+.. code-block:: python
+
+    import revpimodio2
+
+    # Initialize
+    rpi = revpimodio2.RevPiModIO(autorefresh=True)
+
+    # Read input and control output
+    if rpi.io.button.value:
+        rpi.io.led.value = True
+
+    # Cleanup
+    rpi.exit()
+
+Cyclic Programming
+------------------
+
+.. code-block:: python
+
+    import revpimodio2
+
+    rpi = revpimodio2.RevPiModIO(autorefresh=True)
+
+    def main_cycle(ct: revpimodio2.Cycletools):
+        if ct.first:
+            ct.var.counter = 0
+
+        if ct.changed(ct.io.sensor):
+            ct.var.counter += 1
+
+    rpi.cycleloop(main_cycle)
+
+Event-Driven Programming
+------------------------
+
+.. code-block:: python
+
+    import revpimodio2
+
+    rpi = revpimodio2.RevPiModIO(autorefresh=True)
+
+    def on_change(ioname, iovalue):
+        print(f"{ioname} = {iovalue}")
+
+    rpi.io.button.reg_event(on_change)
+    rpi.handlesignalend()
+    rpi.mainloop()
+
+Constants
+=========
+
+Edge Detection
+--------------
+
+.. py:data:: revpimodio2.RISING
+   :type: int
+
+   Detect low-to-high transitions
+
+.. py:data:: revpimodio2.FALLING
+   :type: int
+
+   Detect high-to-low transitions
+
+.. py:data:: revpimodio2.BOTH
+   :type: int
+
+   Detect any transition
+
+LED Colors
+----------
+
+.. py:data:: revpimodio2.OFF
+   :type: int
+
+   LED off
+
+.. py:data:: revpimodio2.GREEN
+   :type: int
+
+   Green LED
+
+.. py:data:: revpimodio2.RED
+   :type: int
+
+   Red LED
+
+IO Types
+--------
+
+.. py:data:: INP
+   :type: int
+   :value: 300
+
+   Input type
+
+.. py:data:: OUT
+   :type: int
+   :value: 301
+
+   Output type
+
+.. py:data:: MEM
+   :type: int
+   :value: 302
+
+   Memory type
+
+See Also
+========
+
+* :doc:`../installation` - Installation guide
+* :doc:`../quickstart` - Quick start guide
+* :doc:`../basics` - Core concepts
+* :doc:`../cyclic_programming` - Cyclic programming patterns
+* :doc:`../event_programming` - Event-driven programming patterns
+* :doc:`../advanced` - Advanced topics
--- a/docs/api/io.rst
+++ b/docs/api/io.rst
@@ -0,0 +1,212 @@
+====================
+IO Classes and Types
+====================
+
+Classes for managing Revolution Pi inputs and outputs.
+
+.. currentmodule:: revpimodio2.io
+
+IOList
+======
+
+.. autoclass:: IOList
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__, __getitem__, __contains__, __iter__
+
+   Container for accessing all IO objects.
+
+   The IOList provides multiple ways to access IOs:
+
+   * **Direct attribute access**: ``rpi.io.button.value``
+   * **String-based access**: ``rpi.io["button"].value``
+   * **Iteration**: ``for io in rpi.io: ...``
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Direct access
+       value = rpi.io.I_1.value
+       rpi.io.O_1.value = True
+
+       # String-based access
+       value = rpi.io["I_1"].value
+
+       # Check if IO exists
+       if "sensor" in rpi.io:
+           print(rpi.io.sensor.value)
+
+       # Iterate all IOs
+       for io in rpi.io:
+           print(f"{io.name}: {io.value}")
+
+IOBase
+======
+
+.. autoclass:: IOBase
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Base class for all IO objects.
+
+   **Properties:**
+
+
+
+      IO name from piCtory configuration
+
+
+
+      Current IO value (read/write)
+
+
+
+      Byte address in process image
+
+
+
+      Byte length (0 for single bits)
+
+
+
+      IO type: 300=INPUT, 301=OUTPUT, 302=MEMORY
+
+
+
+      Whether value is signed
+
+
+
+      "little" or "big" endian
+
+
+
+      Configured default value from piCtory
+
+
+
+      Comment/description from piCtory
+
+
+
+      Export flag status
+
+Event Registration Methods
+---------------------------
+
+
+Value Manipulation Methods
+---------------------------
+
+
+IntIO
+=====
+
+.. autoclass:: IntIO
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   IO objects with integer value access.
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Get integer value
+       temp = rpi.io.temperature.get_intvalue()
+
+       # Set integer value
+       rpi.io.setpoint.set_intvalue(1500)
+
+Integer Value Methods
+---------------------
+
+
+IntIOCounter
+============
+
+.. autoclass:: IntIOCounter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Counter input objects with reset capability.
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Read counter
+       count = rpi.io.counter.value
+
+       # Reset counter
+       rpi.io.counter.reset()
+
+StructIO
+========
+
+.. autoclass:: StructIO
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Structured IO with format strings for complex data types.
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Get structured value
+       value = rpi.io.sensor_data.get_structvalue()
+
+Structured Value Methods
+------------------------
+
+
+MemIO
+=====
+
+.. autoclass:: MemIO
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Memory IO with variant value access (string or integer).
+
+RelaisOutput
+============
+
+.. autoclass:: RelaisOutput
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Relay output with switching cycle counter.
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Get number of switching cycles
+       cycles = rpi.io.relay.get_switching_cycles()
+
+IOEvent
+=======
+
+.. autoclass:: IOEvent
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Internal class for IO event management.
--- a/docs/api/revpimodio.rst
+++ b/docs/api/revpimodio.rst
@@ -0,0 +1,141 @@
+==================
+RevPiModIO Classes
+==================
+
+Main classes for managing Revolution Pi hardware.
+
+.. currentmodule:: revpimodio2.modio
+
+RevPiModIO
+==========
+
+.. autoclass:: RevPiModIO
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Main class for managing all devices and IOs from the piCtory configuration.
+
+   This class manages the complete piCtory configuration and loads all devices
+   and IOs. It handles exclusive management of the process image and ensures
+   data synchronization.
+
+   **Constructor Parameters:**
+
+   :param autorefresh: Automatically sync process image (recommended: True)
+   :type autorefresh: bool
+   :param monitoring: Read-only mode for supervision (no writes)
+   :type monitoring: bool
+   :param syncoutputs: Load current output values on initialization
+   :type syncoutputs: bool
+   :param debug: Enable detailed error messages and logging
+   :type debug: bool
+
+   **Key Attributes:**
+
+
+
+      Access to all configured inputs/outputs
+
+
+
+      Access to RevPi Core values (LEDs, status)
+
+
+
+      Access to specific devices by name
+
+
+
+      Update frequency in milliseconds
+
+
+
+      Threading event for clean shutdown
+
+
+
+      Count of read/write failures
+
+
+
+      Exception threshold (0 = disabled)
+
+   **Example:**
+
+   .. code-block:: python
+
+       import revpimodio2
+
+       # Initialize with auto-refresh
+       rpi = revpimodio2.RevPiModIO(autorefresh=True)
+
+       # Access IOs
+       if rpi.io.button.value:
+           rpi.io.led.value = True
+
+       # Clean shutdown
+       rpi.exit()
+
+Loop Execution Methods
+----------------------
+
+
+Data Synchronization Methods
+-----------------------------
+
+
+Utility Methods
+---------------
+
+
+RevPiModIOSelected
+==================
+
+.. autoclass:: RevPiModIOSelected
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Manage only specific devices from the piCtory configuration.
+
+   Use this class when you only need to control specific devices instead of
+   loading the entire configuration.
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Manage only specific devices
+       rpi = revpimodio2.RevPiModIOSelected("DIO_Module_1", "AIO_Module_1")
+
+RevPiModIODriver
+================
+
+.. autoclass:: RevPiModIODriver
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Write data to virtual device inputs for driver development.
+
+   **Example:**
+
+   .. code-block:: python
+
+       # Create driver for virtual device
+       driver = revpimodio2.RevPiModIODriver("VirtualDevice")
+
+DevSelect
+=========
+
+.. autoclass:: DevSelect
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :special-members: __init__
+
+   Customized search filter for RevPiModIOSelected.