ao_safety
=========

Active object evaluating safety events and enforcing protective actions.

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

- :doc:`Safety_Manager </generated/architecture/safety-manager-02c1300e-5e7b-42c1-b86c-e6624aed8975>`

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

- :doc:`REQ-SAF-001 </generated/requirements/req-saf-001-ba0b5edf-8bb0-4a0b-9175-d3aa8e9c5723>`
- :doc:`REQ-SAF-002 </generated/requirements/req-saf-002-7d84fdcd-bc2d-4d84-b9f5-3001a0ec3450>`
- :doc:`REQ-SAF-003 </generated/requirements/req-saf-003-5a4ec5ad-c37c-4a4e-b0ad-79a98d401f67>`
- :doc:`REQ-SAF-004 </generated/requirements/req-saf-004-eb6c1ba9-f6c7-4b6c-b0d6-1b944ab4a103>`
- :doc:`REQ-REL-002 </generated/requirements/req-rel-002-91745d89-b7da-4174-8429-de274ce0ecc0>`

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

.. image:: /_static/sw_unit_uml/ao_safety_572b6978-4204-472b-adc9-dfab6db77544_uml.svg
   :alt: UML class diagram for ao_safety
   :class: dblclick-open-image


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

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

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

   * - Relation
     - UML Type
     - Visibility
     - Target Unit
     - Description
   * - :doc:`SWR-005 </generated/detailed_design/relations/swr-005-1a631235-b0de-4a63-9431-fb1916c29b12>`
     - composition
     - private
     - :doc:`sm_protection </generated/detailed_design/units/sm-protection-e1628b27-5592-4162-9c22-2c606ccff38a>`
     - Safety active object embeds protection state machine.
   * - :doc:`SWR-014 </generated/detailed_design/relations/swr-014-86ba7392-f338-46ba-8b08-c2d142ce142a>`
     - association
     - public
     - :doc:`ao_diagnostics </generated/detailed_design/units/ao-diagnostics-393df213-9fc6-493d-94c4-e56fb9ff6d08>`
     - Safety publishes protective-state and fault events to diagnostics.

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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-009 </generated/detailed_design/relations/swr-009-2afa4333-8e78-4afa-b24a-ff1b6408c8db>`
     - dependency
     - public
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor dispatches safety events.
   * - :doc:`SWR-012 </generated/detailed_design/relations/swr-012-35848c24-0415-4584-9144-977152f6a07a>`
     - association
     - public
     - :doc:`ao_control </generated/detailed_design/units/ao-control-c39fee55-334a-439f-9130-242b3170e9e4>`
     - Control and safety coordinate control override behavior.
   * - :doc:`SWR-022 </generated/detailed_design/relations/swr-022-1a1ac8b4-d11a-4a1a-a69a-c5c583cf4816>`
     - association
     - public
     - :doc:`ao_monitoring </generated/detailed_design/units/ao-monitoring-d00a296a-5578-400a-89d7-90d6c2b31039>`
     - Monitoring publishes validated sensor snapshots to safety for protective evaluation.

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

.. _dt-3a9ce51f-e052-4a9c-bfca-a8b23c7dbc16:

.. raw:: html

   <span id="dt-3a9ce51f-e052-4a9c-bfca-a8b23c7dbc16"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_safety_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for ao_safety.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - protection_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Protection state.
   * - latch_active
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Protection latch state.
   * - override_active
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Output override active.
   * - last_transition_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last protection transition tick.

.. _dt-464eb032-db88-464e-88f7-3b897a9e72d5:

.. raw:: html

   <span id="dt-464eb032-db88-464e-88f7-3b897a9e72d5"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_safety_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by ao_safety.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Safety event signal id.
   * - hazard_detected
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Hazard detection input.
   * - temperature_c
     - :ref:`int16_t <dt-cbd13cc4-2cb1-4bd1-8a7b-05f377f9f90b>`
     - Safety-evaluated temperature.
   * - clear_request
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Latch clear request.

.. _dt-7f1ab59d-66f6-4f1a-bfe6-9efcd95efc0f:

.. raw:: html

   <span id="dt-7f1ab59d-66f6-4f1a-bfe6-9efcd95efc0f"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_safety_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for ao_safety operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Safety evaluation applied.
   * - PROTECTION_ENTERED
     - 1
     - Entered protection state.
   * - LATCH_BLOCKED
     - 2
     - Clear denied by latch guard.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`ao_safety_context <dt-3a9ce51f-e052-4a9c-bfca-a8b23c7dbc16>`
     - private
     - Runtime context for ao_safety state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`ao_safety_result <dt-7f1ab59d-66f6-4f1a-bfe6-9efcd95efc0f>`
- **Visibility:** public
- **Description:** Process one ao_safety event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`ao_safety_event <dt-464eb032-db88-464e-88f7-3b897a9e72d5>`
     - in
     - Process one ao_safety event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`ao_safety_result <dt-7f1ab59d-66f6-4f1a-bfe6-9efcd95efc0f>`
- **Visibility:** public
- **Description:** Initialize ao_safety runtime state and dependencies.



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



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

ao_safety_activity
^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   start
   :Receive IF_SensorSnapshot and IF_FanCommand context;
   if (temp > 85C?) then (yes)
     :Set protective request;
   elseif (voltage < 18V?) then (yes)
     :Set protective request;
   elseif (voltage > 30V?) then (yes)
     :Set protective request;
   elseif (sensor invalid?) then (yes)
     :Set protective request;
   else (no)
     :Evaluate clear condition;
   endif
   :Dispatch sm_protection event;
   :Publish IF_OperatingStatus and IF_FaultEvent;
   stop
   @enduml


This activity diagram details ao_safety hazard evaluation across temperature voltage and signal validity conditions and documents the decision path that emits protection events and status updates consumed by diagnostics and indication services.



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

ao_safety_timing
^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   robust "ao_safety" as SAFE
   scale max 1200 width
   concise "hazard event" as H
   
   @0
   H is asserted
   SAFE is evaluate
   
   @300
   SAFE is protective_entry
   
   @800
   SAFE is outputs_disabled
   
   @1000
   SAFE is status_published
   
   @enduml


This timing diagram captures protective entry latency from hazard assertion through evaluation and output shutdown to final status publication supporting verification of one second protection response requirements.



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