ao_control
==========

Active object processing measurement and config events to generate control actions.

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/ao_control_c39fee55-334a-439f-9130-242b3170e9e4_uml.svg
   :alt: UML class diagram for ao_control
   :class: dblclick-open-image


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

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

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

   * - Relation
     - UML Type
     - Visibility
     - Target Unit
     - Description
   * - :doc:`SWR-004 </generated/detailed_design/relations/swr-004-a684f200-ff04-4684-833d-b4759faa392c>`
     - composition
     - private
     - :doc:`sm_fan_control </generated/detailed_design/units/sm-fan-control-2cd69a94-0987-4cd6-839c-002a437c52e1>`
     - Control active object embeds fan control state machine.
   * - :doc:`SWR-012 </generated/detailed_design/relations/swr-012-35848c24-0415-4584-9144-977152f6a07a>`
     - association
     - public
     - :doc:`ao_safety </generated/detailed_design/units/ao-safety-572b6978-4204-472b-adc9-dfab6db77544>`
     - Control and safety coordinate control override behavior.
   * - :doc:`SWR-013 </generated/detailed_design/relations/swr-013-5a0f41f9-a086-4a0f-b0c4-97af4e3443c5>`
     - association
     - public
     - :doc:`ao_diagnostics </generated/detailed_design/units/ao-diagnostics-393df213-9fc6-493d-94c4-e56fb9ff6d08>`
     - Control publishes operational and fault-relevant events to diagnostics.

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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-008 </generated/detailed_design/relations/swr-008-b9e7b61d-045b-49e7-b041-d6b915ad9131>`
     - dependency
     - public
     - :doc:`ao_runtime_supervisor </generated/detailed_design/units/ao-runtime-supervisor-46acab8f-6426-46ac-9b10-6f02a2ca442d>`
     - Runtime supervisor dispatches control events.
   * - :doc:`SWR-021 </generated/detailed_design/relations/swr-021-d46faa2a-6198-446f-a3cd-06bc7ebc4102>`
     - association
     - public
     - :doc:`ao_monitoring </generated/detailed_design/units/ao-monitoring-d00a296a-5578-400a-89d7-90d6c2b31039>`
     - Monitoring publishes validated sensor snapshots to control for decision logic.

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

.. _dt-1997f235-f58e-4997-af34-1ee0d4ec5226:

.. raw:: html

   <span id="dt-1997f235-f58e-4997-af34-1ee0d4ec5226"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_control_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for ao_control.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - control_mode
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Control mode state.
   * - fan_command_on
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Last commanded fan output.
   * - threshold_c
     - :ref:`int16_t <dt-cbd13cc4-2cb1-4bd1-8a7b-05f377f9f90b>`
     - Configured activation threshold.
   * - hysteresis_band_c
     - :ref:`int16_t <dt-cbd13cc4-2cb1-4bd1-8a7b-05f377f9f90b>`
     - Configured hysteresis band.

.. _dt-11dbc093-6248-41db-adfe-f7eafdc7b819:

.. raw:: html

   <span id="dt-11dbc093-6248-41db-adfe-f7eafdc7b819"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_control_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by ao_control.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Control event signal id.
   * - snapshot_valid
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Incoming sensor snapshot validity.
   * - temperature_c
     - :ref:`int16_t <dt-cbd13cc4-2cb1-4bd1-8a7b-05f377f9f90b>`
     - Temperature sample for decision.
   * - protect_active
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Protection override input.

.. _dt-75d1cf9e-091c-45d1-a352-b93ab04ee7e0:

.. raw:: html

   <span id="dt-75d1cf9e-091c-45d1-a352-b93ab04ee7e0"></span><div class="sw-dt-title"><span class="sw-dt-name">ao_control_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for ao_control operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - Control command computed.
   * - INVALID_SNAPSHOT
     - 1
     - Snapshot rejected due to invalidity.
   * - SAFETY_OVERRIDE
     - 2
     - Command forced by safety policy.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`ao_control_context <dt-1997f235-f58e-4997-af34-1ee0d4ec5226>`
     - private
     - Runtime context for ao_control state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`ao_control_result <dt-75d1cf9e-091c-45d1-a352-b93ab04ee7e0>`
- **Visibility:** public
- **Description:** Process one ao_control event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`ao_control_event <dt-11dbc093-6248-41db-adfe-f7eafdc7b819>`
     - in
     - Process one ao_control event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`ao_control_result <dt-75d1cf9e-091c-45d1-a352-b93ab04ee7e0>`
- **Visibility:** public
- **Description:** Initialize ao_control runtime state and dependencies.



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



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

ao_control_activity
^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   start
   :Receive IF_SensorSnapshot;
   if (snapshot valid?) then (yes)
     :Evaluate thresholds and hysteresis;
     if (protective active?) then (yes)
       :Force fan OFF command;
     else (no)
       :Compute fan command ON or OFF;
     endif
     :Publish IF_FanCommand;
     :Publish IF_OperatingStatus update;
   else (no)
     :Emit controlled safe output policy;
   endif
   stop
   @enduml


This activity diagram defines ao_control decision flow from validated sensor snapshot intake through threshold and hysteresis evaluation to fan command generation with explicit protective override logic and status publication side effects.



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

ao_control_timing
^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   robust "ao_control" as CTRL
   scale max 1200 width
   concise "sampling tick" as TICK
   
   @0
   TICK is idle
   CTRL is waiting
   
   @100
   TICK is sensor_snapshot
   CTRL is evaluating
   
   @400
   CTRL is command_ready
   
   @500
   CTRL is published
   
   @enduml


This timing diagram allocates the control cycle budget relative to the sampling tick and shows ordering from input availability to command publication to support deterministic control latency analysis and schedulability review.



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.