ao_modbus_server
================

Active object handling Modbus RTU request and response event flows.

Inherited Component
-------------------

- :doc:`Comms_Modbus_RTU </generated/architecture/comms-modbus-rtu-0c1dd904-b8d3-4c1d-afbd-c026dd6fb637>`

Inherited Requirements
----------------------

- :doc:`REQ-IFC-001 </generated/requirements/req-ifc-001-07d30546-53c1-47d3-a76d-6fb63ea454a4>`
- :doc:`REQ-IFC-002 </generated/requirements/req-ifc-002-bb29ed45-4c97-4b29-a1e1-d272f4e4f7ef>`
- :doc:`REQ-IFC-003 </generated/requirements/req-ifc-003-5c72ccd2-b7f1-4c72-9d19-c7656c98196e>`
- :doc:`REQ-IFC-004 </generated/requirements/req-ifc-004-d156d04c-89f2-4156-9724-dae00d6c83d7>`

Relationship Diagram
--------------------

.. image:: /_static/sw_unit_uml/ao_modbus_server_c4a17ec8-b518-44a1-982f-7d2f82fa4b44_uml.svg
   :alt: UML class diagram for ao_modbus_server
   :class: dblclick-open-image


SW Unit Relations
-----------------

Outgoing Relations
~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - Relation
     - UML Type
     - Visibility
     - Target Unit
     - Description
   * - :doc:`SWR-018 </generated/detailed_design/relations/swr-018-ca46f8fe-aa97-4a46-8056-a112468b3bde>`
     - dependency
     - private
     - :doc:`hal_event_adapter </generated/detailed_design/units/hal-event-adapter-9629a78b-294f-4629-b709-fc03c058c26d>`
     - Modbus server uses hardware-adapted UART events.
   * - :doc:`SWR-020 </generated/detailed_design/relations/swr-020-fbf5d76d-87e9-4bf5-8203-94fe5044896a>`
     - dependency
     - private
     - :doc:`ao_config_manager </generated/detailed_design/units/ao-config-manager-75815879-88a1-4581-88cc-9ba567d73b34>`
     - Modbus server forwards configuration update requests to config manager for validation and commit.

Incoming Relations
~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-011 </generated/detailed_design/relations/swr-011-b11605dd-0b96-4116-8c4a-5d080c1e6801>`
     - dependency
     - public
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor dispatches communication events.

Data Types
----------

.. _dt-09d41de2-de6b-49d4-a9dd-662c79d40a85:

.. raw:: html

   <span id="dt-09d41de2-de6b-49d4-a9dd-662c79d40a85"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_modbus_server_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for ao_modbus_server.

.. rubric:: Struct Members

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - session_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Modbus session state.
   * - last_function_code
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Last processed function code.
   * - exception_active
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Exception response active.
   * - last_request_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last request processing tick.

.. _dt-4da63713-048e-4da6-af8e-042488c1ae40:

.. raw:: html

   <span id="dt-4da63713-048e-4da6-af8e-042488c1ae40"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_modbus_server_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by ao_modbus_server.

.. rubric:: Struct Members

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Modbus event signal id.
   * - function_code
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Requested function code.
   * - register_address
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Starting register address.
   * - register_count
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Register quantity.

.. _dt-96669eba-9b02-4666-80b9-a93799560e69:

.. raw:: html

   <span id="dt-96669eba-9b02-4666-80b9-a93799560e69"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_modbus_server_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for ao_modbus_server operations.

.. rubric:: Enum Members

.. list-table::
   :header-rows: 1

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Transaction served.
   * - FRAME_ERROR
     - 1
     - Frame parsing failed.
   * - MODBUS_EXCEPTION
     - 2
     - Exception response returned.



Attributes
----------

.. list-table::
   :header-rows: 1

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`ao_modbus_server_context <dt-09d41de2-de6b-49d4-a9dd-662c79d40a85>`
     - private
     - Runtime context for ao_modbus_server state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`ao_modbus_server_result <dt-96669eba-9b02-4666-80b9-a93799560e69>`
- **Visibility:** public
- **Description:** Process one ao_modbus_server event and update runtime outputs.

.. rubric:: Parameters

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`ao_modbus_server_event <dt-4da63713-048e-4da6-af8e-042488c1ae40>`
     - in
     - Process one ao_modbus_server event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`ao_modbus_server_result <dt-96669eba-9b02-4666-80b9-a93799560e69>`
- **Visibility:** public
- **Description:** Initialize ao_modbus_server runtime state and dependencies.



Dynamic Behaviour
-----------------


State Machines
~~~~~~~~~~~~~~

ao_modbus_server_state
^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide empty description
   
   
   [*] --> Comms_Init
   Comms_Init --> Idle : EVT_INIT_DONE
   
   Idle --> Rx_Frame : EVT_FRAME_RX
   Rx_Frame --> Validate : EVT_FRAME_COMPLETE
   Validate --> Respond : EVT_REQ_VALID
   Validate --> Error : EVT_REQ_INVALID
   Validate --> Error : EVT_CRC_FAIL
   
   Respond : do / build_modbus_response()
   Respond --> Idle : EVT_TX_DONE
   
   Error : do / send_exception_response()
   Error --> Idle : EVT_TX_DONE
   Error --> Idle : EVT_TIMEOUT
   
   @enduml


This state machine models Modbus request processing phases including frame reception validation protocol error handling and response transmission to ensure deterministic interface behavior for valid and invalid master transactions.





Sequence Diagrams
~~~~~~~~~~~~~~~~~

SEQ-001_Runtime_Event_Orchestration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Runtime Event Orchestration
   
   participant ao_runtime_supervisor
   participant evt_timer_service
   participant evt_dispatcher
   participant ao_monitoring
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_timer_service : init periodic tick
   ao_runtime_supervisor -> evt_dispatcher : init event loop
   loop each scheduler tick
     evt_timer_service -> ao_runtime_supervisor : tick event
     ao_runtime_supervisor -> evt_dispatcher : dispatch cycle
     evt_dispatcher -> ao_monitoring : monitor_event
     evt_dispatcher -> ao_control : control_event
     evt_dispatcher -> ao_safety : safety_event
     evt_dispatcher -> ao_diagnostics : diagnostics_event
     evt_dispatcher -> ao_modbus_server : comms_event
   end
   
   @enduml


Primary runtime interoperability sequence showing scheduler tick propagation through dispatcher fan-out and deterministic active-object processing order across monitoring control safety diagnostics and communication units.


SEQ-004_Modbus_Event_Servicing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Modbus Server Event Servicing
   
   participant ao_runtime_supervisor
   participant ao_modbus_server
   participant hal_event_adapter
   
   ao_runtime_supervisor -> ao_modbus_server : dispatch comms_event
   ao_modbus_server -> hal_event_adapter : request UART I/O
   hal_event_adapter --> ao_modbus_server : uart_rx/tx completion
   ao_modbus_server -> hal_event_adapter : publish protocol response
   
   @enduml


Runtime-driven communication events are processed by the Modbus server through hardware-adapted UART event exchange.


SEQ-005_Startup_To_Ready
^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_timer_service
   participant evt_dispatcher
   participant ao_monitoring
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_timer_service : init()
   ao_runtime_supervisor -> evt_dispatcher : init()
   ao_runtime_supervisor -> ao_monitoring : init()
   ao_runtime_supervisor -> ao_control : init()
   ao_runtime_supervisor -> ao_safety : init()
   ao_runtime_supervisor -> ao_diagnostics : init()
   ao_runtime_supervisor -> ao_modbus_server : init()
   
   group readiness gates
     evt_timer_service --> ao_runtime_supervisor : EVT_TIMER_READY
     evt_dispatcher --> ao_runtime_supervisor : EVT_DISPATCH_READY
     ao_monitoring --> ao_runtime_supervisor : EVT_AO_READY
     ao_control --> ao_runtime_supervisor : EVT_AO_READY
     ao_safety --> ao_runtime_supervisor : EVT_AO_READY
     ao_diagnostics --> ao_runtime_supervisor : EVT_AO_READY
     ao_modbus_server --> ao_runtime_supervisor : EVT_AO_READY
   end
   
   ao_runtime_supervisor -> evt_dispatcher : EVT_INIT_OK / start Run
   @enduml


Startup lifecycle sequence with explicit readiness gates before entering Run state.


SEQ-007_Controlled_Shutdown
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_dispatcher
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   participant ao_modbus_server
   
   ao_runtime_supervisor -> evt_dispatcher : EVT_SHUTDOWN_REQ
   ao_runtime_supervisor -> ao_control : stop outputs to safe state
   ao_runtime_supervisor -> ao_safety : keep protective policy active
   ao_runtime_supervisor -> ao_diagnostics : publish shutdown status
   ao_runtime_supervisor -> ao_modbus_server : stop comm servicing
   
   ao_modbus_server --> ao_runtime_supervisor : EVT_STOPPED
   ao_diagnostics --> ao_runtime_supervisor : EVT_STOPPED
   ao_safety --> ao_runtime_supervisor : EVT_STOPPED
   ao_control --> ao_runtime_supervisor : EVT_STOPPED
   evt_dispatcher --> ao_runtime_supervisor : EVT_STOPPED
   
   ao_runtime_supervisor -> ao_runtime_supervisor : EVT_ALL_STOPPED / Shutdown complete
   @enduml


Controlled shutdown sequence defining stop ordering and completion criteria.