sm_operation_mode
=================

State machine managing normal warning protective and recovery modes.

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

- :doc:`Runtime_Manager </generated/architecture/runtime-manager-67b5054c-aedb-47b5-8258-c8d97c4f7d69>`

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

- :doc:`REQ-REL-001 </generated/requirements/req-rel-001-2e6b7004-be8f-4e6b-8d4e-e4b18a08ff41>`
- :doc:`REQ-REL-004 </generated/requirements/req-rel-004-6f23cf0d-e838-4f23-b798-f39b79b8042a>`

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

.. image:: /_static/sw_unit_uml/sm_operation_mode_c359a001-cc9a-4359-85ca-556ef59c6bcc_uml.svg
   :alt: UML class diagram for sm_operation_mode
   :class: dblclick-open-image


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


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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-003 </generated/detailed_design/relations/swr-003-0b2cab31-b379-4b2c-a7f0-4c55663fc66e>`
     - composition
     - private
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor embeds operation mode state machine.

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

.. _dt-2c44c837-1349-4c44-920f-b5be6fc543e4:

.. raw:: html

   <span id="dt-2c44c837-1349-4c44-920f-b5be6fc543e4"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_operation_mode_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for sm_operation_mode.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - sm_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Operation mode state.
   * - startup_complete
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Startup completion flag.
   * - degraded_mode
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Degraded mode flag.
   * - transition_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last transition tick.

.. _dt-e3625462-832a-4362-b87d-37ffc12e1fb7:

.. raw:: html

   <span id="dt-e3625462-832a-4362-b87d-37ffc12e1fb7"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_operation_mode_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by sm_operation_mode.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Operation mode event id.
   * - init_ok
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Init completed input.
   * - fault_present
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Fault presence input.
   * - shutdown_request
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Shutdown request input.

.. _dt-74d7dc11-46da-44d7-8151-48cae306ff9a:

.. raw:: html

   <span id="dt-74d7dc11-46da-44d7-8151-48cae306ff9a"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_operation_mode_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for sm_operation_mode operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Mode transition applied.
   * - INVALID_TRANSITION
     - 1
     - Transition invalid for state.
   * - DEGRADED_MODE
     - 2
     - Transitioned to degraded mode.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`sm_operation_mode_context <dt-2c44c837-1349-4c44-920f-b5be6fc543e4>`
     - private
     - Runtime context for sm_operation_mode state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`sm_operation_mode_result <dt-74d7dc11-46da-44d7-8151-48cae306ff9a>`
- **Visibility:** public
- **Description:** Process one sm_operation_mode event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`sm_operation_mode_event <dt-e3625462-832a-4362-b87d-37ffc12e1fb7>`
     - in
     - Process one sm_operation_mode event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`sm_operation_mode_result <dt-74d7dc11-46da-44d7-8151-48cae306ff9a>`
- **Visibility:** public
- **Description:** Initialize sm_operation_mode runtime state and dependencies.



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


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

sm_operation_mode_state
^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide empty description
   
   
   [*] --> Init
   Init --> Normal : EVT_STARTUP_DONE
   
   Normal --> Warning : EVT_WARN_ON
   Warning --> Normal : EVT_WARN_CLEAR
   
   Normal --> Protective : EVT_PROTECT_ENTER
   Warning --> Protective : EVT_PROTECT_ENTER
   Recovery --> Protective : EVT_PROTECT_ENTER
   
   Normal --> Protective : EVT_FAULT_SET
   Warning --> Protective : EVT_FAULT_SET
   
   Protective --> Recovery : EVT_PROTECT_CLEAR
   Recovery --> Normal : EVT_FAULT_CLEAR
   
   state Protective {
     [*] --> Enforced
     Enforced : do / disable_active_outputs()
     Enforced : do / assert_fault_indication()
   }
   
   @enduml


This state machine defines high level operating mode transitions across Init Normal Warning Protective and Recovery and documents how warning events safety triggers and fault lifecycle events govern mode arbitration and output policy.





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.