ao_monitoring
=============

Active object sampling sensors and emitting validated measurement events.

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

- :doc:`Monitoring_Manager </generated/architecture/monitoring-manager-62cbb1ac-6119-42cb-bdea-ff4737e1e316>`

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

- :doc:`REQ-MON-001 </generated/requirements/req-mon-001-ad3c334f-75ee-4d3c-8555-284ceb5f2420>`
- :doc:`REQ-MON-002 </generated/requirements/req-mon-002-203fdbf6-ce18-403f-8421-71871a49bc6f>`
- :doc:`REQ-MON-003 </generated/requirements/req-mon-003-c2121c70-1b3f-4212-8110-dc02cfbcf151>`
- :doc:`REQ-MON-004 </generated/requirements/req-mon-004-4ef1c290-65c8-4ef1-a918-d6ce3f17c00b>`
- :doc:`REQ-REL-002 </generated/requirements/req-rel-002-91745d89-b7da-4174-8429-de274ce0ecc0>`

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

.. image:: /_static/sw_unit_uml/ao_monitoring_d00a296a-5578-400a-89d7-90d6c2b31039_uml.svg
   :alt: UML class diagram for ao_monitoring
   :class: dblclick-open-image


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

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

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

   * - Relation
     - UML Type
     - Visibility
     - Target Unit
     - Description
   * - :doc:`SWR-017 </generated/detailed_design/relations/swr-017-bbff8d86-bcaf-4bff-a116-49f17f466f26>`
     - dependency
     - private
     - :doc:`hal_event_adapter </generated/detailed_design/units/hal-event-adapter-9629a78b-294f-4629-b709-fc03c058c26d>`
     - Monitoring consumes hardware-adapted sensor events.
   * - :doc:`SWR-021 </generated/detailed_design/relations/swr-021-d46faa2a-6198-446f-a3cd-06bc7ebc4102>`
     - association
     - public
     - :doc:`ao_control </generated/detailed_design/units/ao-control-c39fee55-334a-439f-9130-242b3170e9e4>`
     - Monitoring publishes validated sensor snapshots to control for decision logic.
   * - :doc:`SWR-022 </generated/detailed_design/relations/swr-022-1a1ac8b4-d11a-4a1a-a69a-c5c583cf4816>`
     - association
     - public
     - :doc:`ao_safety </generated/detailed_design/units/ao-safety-572b6978-4204-472b-adc9-dfab6db77544>`
     - Monitoring publishes validated sensor snapshots to safety for protective evaluation.

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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-007 </generated/detailed_design/relations/swr-007-2b7a6716-5c99-4b7a-8851-5d5cc5fa7507>`
     - dependency
     - public
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor dispatches monitoring events.

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

.. _dt-43068ab0-2ef2-4306-9aa0-b5b601b1a1e8:

.. raw:: html

   <span id="dt-43068ab0-2ef2-4306-9aa0-b5b601b1a1e8"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_monitoring_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for ao_monitoring.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - sample_period_ms
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Sampling period.
   * - last_sample_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last sampling tick.
   * - rpm_sampling_enabled
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - RPM sampling enable state.
   * - bounds_valid
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Last bounds validation result.

.. _dt-51e38746-2bfe-41e3-9845-4c36fde605be:

.. raw:: html

   <span id="dt-51e38746-2bfe-41e3-9845-4c36fde605be"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_monitoring_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by ao_monitoring.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Monitoring event signal id.
   * - temperature_c
     - :ref:`int16_t <dt-cbd13cc4-2cb1-4bd1-8a7b-05f377f9f90b>`
     - Measured temperature.
   * - supply_voltage_mv
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Measured supply voltage.
   * - fan_rpm
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Measured fan speed.

.. _dt-8533615b-4835-4533-b5dd-f199c0f00a15:

.. raw:: html

   <span id="dt-8533615b-4835-4533-b5dd-f199c0f00a15"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_monitoring_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for ao_monitoring operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Monitoring snapshot published.
   * - SENSOR_RANGE_ERROR
     - 1
     - Sample out of bounds.
   * - HAL_DATA_MISSING
     - 2
     - Required HAL data unavailable.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`ao_monitoring_context <dt-43068ab0-2ef2-4306-9aa0-b5b601b1a1e8>`
     - private
     - Runtime context for ao_monitoring state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`ao_monitoring_result <dt-8533615b-4835-4533-b5dd-f199c0f00a15>`
- **Visibility:** public
- **Description:** Process one ao_monitoring event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`ao_monitoring_event <dt-51e38746-2bfe-41e3-9845-4c36fde605be>`
     - in
     - Process one ao_monitoring event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`ao_monitoring_result <dt-8533615b-4835-4533-b5dd-f199c0f00a15>`
- **Visibility:** public
- **Description:** Initialize ao_monitoring runtime state and dependencies.



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



Activity Diagrams
~~~~~~~~~~~~~~~~~

ao_monitoring_activity
^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   start
   :Trigger periodic sampling;
   :Read temperature;
   :Read supply voltage;
   if (fan command ON?) then (yes)
     :Read fan RPM;
   endif
   :Validate physical bounds;
   if (any value invalid?) then (yes)
     :Set validity flags false;
   else (no)
     :Set validity flags true;
   endif
   :Publish IF_SensorSnapshot;
   stop
   @enduml


This activity diagram defines ao_monitoring control flow for one acquisition cycle including trigger source conditional RPM acquisition physical range validation and IF SensorSnapshot publication with validity flags used by downstream control and safety logic.



Timing Diagrams
~~~~~~~~~~~~~~~

ao_monitoring_timing
^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   robust "ao_monitoring" as MON
   scale max 1200 width
   concise "500ms scheduler" as S
   
   @0
   S is tick
   MON is sample_temp
   
   @120
   MON is sample_voltage
   
   @250
   MON is sample_rpm_if_needed
   
   @380
   MON is validate
   
   @500
   MON is publish_snapshot
   S is tick
   
   @enduml


This timing diagram decomposes the 500 ms monitoring cadence into sensor read stages validation and publish phase so requirement conformance can be checked against worst case execution and scheduling jitter.



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-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.