sm_fan_control
==============

State machine implementing fan control and anti-chatter behavior.

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

- :doc:`Control_Manager </generated/architecture/control-manager-5d7aa461-6b3a-4d7a-958a-4dedb378d932>`

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

- :doc:`REQ-CTL-001 </generated/requirements/req-ctl-001-93ba692f-08a9-43ba-b858-74a01d06b48d>`
- :doc:`REQ-CTL-002 </generated/requirements/req-ctl-002-2f044c2e-9ae4-4f04-973e-af65652a6b5e>`
- :doc:`REQ-CTL-004 </generated/requirements/req-ctl-004-d7e623a0-b76f-47e6-9bc3-70953f065168>`
- :doc:`REQ-REL-003 </generated/requirements/req-rel-003-901d46bf-d37f-401d-8d43-0eb175ccf610>`

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

.. image:: /_static/sw_unit_uml/sm_fan_control_2cd69a94-0987-4cd6-839c-002a437c52e1_uml.svg
   :alt: UML class diagram for sm_fan_control
   :class: dblclick-open-image


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


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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-004 </generated/detailed_design/relations/swr-004-a684f200-ff04-4684-833d-b4759faa392c>`
     - composition
     - private
     - :doc:`ao_control </generated/detailed_design/units/ao-control-c39fee55-334a-439f-9130-242b3170e9e4>`
     - Control active object embeds fan control state machine.

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

.. _dt-701c0b74-dc97-401c-8a05-805abe3129e5:

.. raw:: html

   <span id="dt-701c0b74-dc97-401c-8a05-805abe3129e5"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_fan_control_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for sm_fan_control.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - sm_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Fan SM current state.
   * - output_on
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Fan output state.
   * - override_active
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Override active state.
   * - transition_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last state transition tick.

.. _dt-4c4a43d5-9deb-4c4a-881e-c130715bfb6e:

.. raw:: html

   <span id="dt-4c4a43d5-9deb-4c4a-881e-c130715bfb6e"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_fan_control_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by sm_fan_control.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Fan SM event id.
   * - request_on
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Requested output state.
   * - protect_active
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Protection input.
   * - feedback_ok
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Feedback validity.

.. _dt-2a7e2bca-6b7e-4a7e-aca8-a49db4c4b064:

.. raw:: html

   <span id="dt-2a7e2bca-6b7e-4a7e-aca8-a49db4c4b064"></span><div class="sw-dt-title"><span class="sw-dt-name">sm_fan_control_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for sm_fan_control operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - State transition applied.
   * - INVALID_TRANSITION
     - 1
     - Illegal transition for current state.
   * - FORCED_SAFE
     - 2
     - Output forced to safe state.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`sm_fan_control_context <dt-701c0b74-dc97-401c-8a05-805abe3129e5>`
     - private
     - Runtime context for sm_fan_control state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`sm_fan_control_result <dt-2a7e2bca-6b7e-4a7e-aca8-a49db4c4b064>`
- **Visibility:** public
- **Description:** Process one sm_fan_control event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`sm_fan_control_event <dt-4c4a43d5-9deb-4c4a-881e-c130715bfb6e>`
     - in
     - Process one sm_fan_control event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`sm_fan_control_result <dt-2a7e2bca-6b7e-4a7e-aca8-a49db4c4b064>`
- **Visibility:** public
- **Description:** Initialize sm_fan_control runtime state and dependencies.



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


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

sm_fan_control_state
^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   hide empty description
   
   
   [*] --> Fan_Off
   
   Fan_Off --> Fan_On : EVT_TEMP_ABOVE_ON [not_protective]
   Fan_On --> Holdoff : EVT_TEMP_BELOW_OFF
   Holdoff --> Fan_Off : EVT_TICK_1S [stable_below_off]
   Holdoff --> Fan_On : EVT_TEMP_ABOVE_ON
   
   Fan_On --> Fan_Off : EVT_PROTECT_ACTIVE
   Holdoff --> Fan_Off : EVT_PROTECT_ACTIVE
   Fan_Off --> Fan_Off : EVT_CFG_UPDATE
   Fan_On --> Fan_On : EVT_CFG_UPDATE
   
   @enduml


This state machine captures hysteresis based fan actuation with anti chatter holdoff semantics and protective override handling so temperature threshold crossings produce stable deterministic fan transitions under noisy boundary conditions.