sm_protection
=============

State machine governing protective entry hold and exit.

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/sm_protection_e1628b27-5592-4162-9c22-2c606ccff38a_uml.svg
   :alt: UML class diagram for sm_protection
   :class: dblclick-open-image


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


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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-005 </generated/detailed_design/relations/swr-005-1a631235-b0de-4a63-9431-fb1916c29b12>`
     - composition
     - private
     - :doc:`ao_safety </generated/detailed_design/units/ao-safety-572b6978-4204-472b-adc9-dfab6db77544>`
     - Safety active object embeds protection state machine.

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

.. _dt-99f20b7b-85e6-49f2-9fcc-b1d420c2e70e:

.. raw:: html

   <span id="dt-99f20b7b-85e6-49f2-9fcc-b1d420c2e70e"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_protection_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for sm_protection.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - sm_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Protection SM state.
   * - hazard_latched
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Hazard latch state.
   * - override_forced
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Forced override state.
   * - transition_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last transition tick.

.. _dt-f76d9e29-0ed5-476d-ae70-375d71faeb8b:

.. raw:: html

   <span id="dt-f76d9e29-0ed5-476d-ae70-375d71faeb8b"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_protection_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by sm_protection.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Protection SM event id.
   * - hazard_detected
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Hazard trigger input.
   * - clear_request
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Clear request input.
   * - sensor_valid
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Sensor validity guard input.

.. _dt-9430e902-7ff2-4430-8fca-320b7409cb5a:

.. raw:: html

   <span id="dt-9430e902-7ff2-4430-8fca-320b7409cb5a"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_protection_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for sm_protection operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Protection transition applied.
   * - INVALID_TRANSITION
     - 1
     - Transition blocked by guards.
   * - LATCH_ACTIVE
     - 2
     - Hazard latch remains active.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`sm_protection_context <dt-99f20b7b-85e6-49f2-9fcc-b1d420c2e70e>`
     - private
     - Runtime context for sm_protection state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`sm_protection_result <dt-9430e902-7ff2-4430-8fca-320b7409cb5a>`
- **Visibility:** public
- **Description:** Process one sm_protection event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`sm_protection_event <dt-f76d9e29-0ed5-476d-ae70-375d71faeb8b>`
     - in
     - Process one sm_protection event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`sm_protection_result <dt-9430e902-7ff2-4430-8fca-320b7409cb5a>`
- **Visibility:** public
- **Description:** Initialize sm_protection runtime state and dependencies.



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


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

sm_protection_state
^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide empty description
   
   
   [*] --> Idle
   
   Idle --> Protective_Entry : EVT_TEMP_HIGH
   Idle --> Protective_Entry : EVT_VOLT_LOW
   Idle --> Protective_Entry : EVT_VOLT_HIGH
   Idle --> Protective_Entry : EVT_SENSOR_INVALID
   
   Protective_Entry : entry / latch_fault_source()
   Protective_Entry : entry / disable_active_outputs()
   Protective_Entry --> Protective_Hold : EVT_FAULT_LATCH
   
   Protective_Hold : do / keep_outputs_disabled()
   Protective_Hold : do / fault_indication_on()
   Protective_Hold --> Exit_Eval : EVT_CLEAR_CONDITION
   
   Exit_Eval --> Protective_Hold : EVT_TEMP_HIGH
   Exit_Eval --> Protective_Hold : EVT_VOLT_LOW
   Exit_Eval --> Protective_Hold : EVT_VOLT_HIGH
   Exit_Eval --> Idle : EVT_TICK_500MS [all_safe_for_exit]
   
   @enduml


This state machine specifies protection entry hold and guarded exit behavior including hazard source latching mandatory output disable enforcement and clear condition evaluation that prevents unsafe return to normal operation.