ao_diagnostics
==============

Active object managing fault and status event processing.

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

- :doc:`Diagnostics_Manager </generated/architecture/diagnostics-manager-ae6163b2-5d17-4e61-8dd9-ebab88ad79a5>`

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

- :doc:`REQ-DIA-001 </generated/requirements/req-dia-001-fa92cae6-1487-4a92-8c97-a25c3582cddd>`
- :doc:`REQ-DIA-002 </generated/requirements/req-dia-002-4740b97f-5a2b-4740-9ce8-97ebd43d96d1>`
- :doc:`REQ-DIA-003 </generated/requirements/req-dia-003-fab25824-204a-4ab2-8dab-4151b35d10d8>`
- :doc:`REQ-DIA-004 </generated/requirements/req-dia-004-6b61fd14-ea69-4b61-9c47-b116bb5a1001>`

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

.. image:: /_static/sw_unit_uml/ao_diagnostics_393df213-9fc6-493d-94c4-e56fb9ff6d08_uml.svg
   :alt: UML class diagram for ao_diagnostics
   :class: dblclick-open-image


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

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

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

   * - Relation
     - UML Type
     - Visibility
     - Target Unit
     - Description
   * - :doc:`SWR-015 </generated/detailed_design/relations/swr-015-15df2300-fd94-45df-87d7-4fce677f4b56>`
     - association
     - public
     - :doc:`ao_status_indication </generated/detailed_design/units/ao-status-indication-2f37d667-1c29-4f37-b12f-138196fec6b0>`
     - Diagnostics publishes status events to indication.

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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-010 </generated/detailed_design/relations/swr-010-5db60957-013d-4db6-9b6b-14b2ef93d645>`
     - dependency
     - public
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor dispatches diagnostics events.
   * - :doc:`SWR-013 </generated/detailed_design/relations/swr-013-5a0f41f9-a086-4a0f-b0c4-97af4e3443c5>`
     - association
     - public
     - :doc:`ao_control </generated/detailed_design/units/ao-control-c39fee55-334a-439f-9130-242b3170e9e4>`
     - Control publishes operational and fault-relevant events to diagnostics.
   * - :doc:`SWR-014 </generated/detailed_design/relations/swr-014-86ba7392-f338-46ba-8b08-c2d142ce142a>`
     - association
     - public
     - :doc:`ao_safety </generated/detailed_design/units/ao-safety-572b6978-4204-472b-adc9-dfab6db77544>`
     - Safety publishes protective-state and fault events to diagnostics.

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

.. _dt-bbc5a55a-0bdf-4bc5-be99-c87a3a3e1996:

.. raw:: html

   <span id="dt-bbc5a55a-0bdf-4bc5-be99-c87a3a3e1996"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_diagnostics_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for ao_diagnostics.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - fault_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Fault lifecycle state.
   * - active_fault_code
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Current fault code.
   * - fault_latched
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Fault latch status.
   * - last_publish_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last diagnostics publish tick.

.. _dt-0217d256-2c86-4217-8a5a-496892909677:

.. raw:: html

   <span id="dt-0217d256-2c86-4217-8a5a-496892909677"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_diagnostics_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by ao_diagnostics.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Diagnostics event signal id.
   * - fault_code
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Fault code payload.
   * - severity
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Fault severity level.
   * - clear_request
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Fault clear request.

.. _dt-a47ad694-b167-447a-a7ae-ec95deb438a3:

.. raw:: html

   <span id="dt-a47ad694-b167-447a-a7ae-ec95deb438a3"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_diagnostics_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for ao_diagnostics operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Diagnostics update published.
   * - FAULT_CAPTURED
     - 1
     - Fault captured and reported.
   * - CLEAR_REJECTED
     - 2
     - Clear rejected by diagnostics policy.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`ao_diagnostics_context <dt-bbc5a55a-0bdf-4bc5-be99-c87a3a3e1996>`
     - private
     - Runtime context for ao_diagnostics state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`ao_diagnostics_result <dt-a47ad694-b167-447a-a7ae-ec95deb438a3>`
- **Visibility:** public
- **Description:** Process one ao_diagnostics event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`ao_diagnostics_event <dt-0217d256-2c86-4217-8a5a-496892909677>`
     - in
     - Process one ao_diagnostics event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`ao_diagnostics_result <dt-a47ad694-b167-447a-a7ae-ec95deb438a3>`
- **Visibility:** public
- **Description:** Initialize ao_diagnostics runtime state and dependencies.



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


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

ao_diagnostics_state
^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide empty description
   
   
   [*] --> Diag_Init
   Diag_Init --> No_Fault : EVT_INIT_DONE
   
   No_Fault --> Fault_Active : EVT_FAULT_RAISED
   Fault_Active --> Fault_Latched : EVT_PROTECT_ACTIVE
   Fault_Active --> No_Fault : EVT_FAULT_CLEAR_REQ [no_active_fault]
   
   Fault_Latched : do / keep_last_fault()
   Fault_Latched --> No_Fault : EVT_FAULT_CLEAR_REQ [safe_to_clear]
   
   No_Fault : do / publish_status_normal()
   Fault_Active : do / publish_status_fault()
   Fault_Latched : do / publish_status_protective()
   
   @enduml


This state machine formalizes diagnostics fault lifecycle handling across no fault active fault and latched fault states and clarifies when status publication and fault clear requests are accepted or rejected.





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-002_Protection_And_Fault_Propagation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Control-Safety-Diagnostics Fault Propagation
   
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   
   ao_control -> ao_safety : IF_FanCommand(command_request)
   ao_safety --> ao_control : IF_FanCommand(override_feedback)
   
   ao_control -> ao_diagnostics : IF_OperatingStatus(control_status)
   alt protection or fault detected
     ao_control -> ao_diagnostics : IF_FaultEvent(control_fault)
     ao_safety -> ao_diagnostics : IF_OperatingStatus(protection_state)
   end
   
   @enduml


Control and safety coordinate fan command decisions and publish operating/fault status into diagnostics for downstream handling.


SEQ-003_Status_To_LED_Indication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Diagnostic Status To LED Indication
   
   participant ao_diagnostics
   participant ao_status_indication
   participant sm_led_indication
   participant drv_rgb_led
   
   ao_diagnostics -> ao_status_indication : IF_OperatingStatus(system_status)
   ao_status_indication -> sm_led_indication : evaluate indication pattern
   sm_led_indication -> ao_status_indication : resolved LED intent
   ao_status_indication -> drv_rgb_led : IF_StatusLedCommand(led_command)
   
   @enduml


Diagnostics status outputs are transformed by status indication logic into concrete LED driver commands.


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-006_Degraded_Entry_And_Recovery
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide footbox
   participant ao_runtime_supervisor
   participant evt_dispatcher
   participant ao_control
   participant ao_safety
   participant ao_diagnostics
   
   ao_runtime_supervisor -> evt_dispatcher : dispatch cycle
   alt degraded entry criteria met
     note over ao_runtime_supervisor: init_timeout OR required_service_failed OR fatal_fault
     ao_runtime_supervisor -> ao_control : EVT_DEGRADED
     ao_runtime_supervisor -> ao_safety : EVT_DEGRADED
     ao_runtime_supervisor -> ao_diagnostics : EVT_DEGRADED
     ao_runtime_supervisor -> evt_dispatcher : restrict noncritical events
   end
   
   ao_runtime_supervisor -> evt_dispatcher : periodic degraded dispatch
   
   alt recovery criteria met
     note over ao_runtime_supervisor: fault_cleared AND watchdog_ok AND required_services_ready
     ao_runtime_supervisor -> evt_dispatcher : EVT_RESET
     ao_runtime_supervisor -> ao_control : EVT_RECOVERY
     ao_runtime_supervisor -> ao_safety : EVT_RECOVERY
     ao_runtime_supervisor -> ao_diagnostics : EVT_RECOVERY
   end
   @enduml


Lifecycle sequence for degraded entry triggers and guarded recovery back to Run.


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.