hal_event_adapter
=================

HAL adapter converting hardware signals and interrupts into internal events and actions.

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

- :doc:`Platform_HAL </generated/architecture/platform-hal-447497f7-c591-4474-9cc4-6721081a69fe>`

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

- :doc:`REQ-IFC-001 </generated/requirements/req-ifc-001-07d30546-53c1-47d3-a76d-6fb63ea454a4>`
- :doc:`REQ-IFC-005 </generated/requirements/req-ifc-005-e9ec1206-b39c-49ec-bece-33c3fb8a40a0>`

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

.. image:: /_static/sw_unit_uml/hal_event_adapter_9629a78b-294f-4629-b709-fc03c058c26d_uml.svg
   :alt: UML class diagram for hal_event_adapter
   :class: dblclick-open-image


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


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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-017 </generated/detailed_design/relations/swr-017-bbff8d86-bcaf-4bff-a116-49f17f466f26>`
     - dependency
     - private
     - :doc:`ao_monitoring </generated/detailed_design/units/ao-monitoring-d00a296a-5578-400a-89d7-90d6c2b31039>`
     - Monitoring consumes hardware-adapted sensor events.
   * - :doc:`SWR-018 </generated/detailed_design/relations/swr-018-ca46f8fe-aa97-4a46-8056-a112468b3bde>`
     - dependency
     - private
     - :doc:`ao_modbus_server </generated/detailed_design/units/ao-modbus-server-c4a17ec8-b518-44a1-982f-7d2f82fa4b44>`
     - Modbus server uses hardware-adapted UART events.
   * - :doc:`SWR-019 </generated/detailed_design/relations/swr-019-48ca5733-416a-48ca-b154-c51bd9eacfdc>`
     - dependency
     - private
     - :doc:`drv_rgb_led </generated/detailed_design/units/drv-rgb-led-fe18dd0c-8b06-4e18-8db9-3fb3b85538a0>`
     - LED driver uses hardware abstraction events.

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

.. _dt-4f524dae-327c-4f52-bba3-8bc87ee70a78:

.. raw:: html

   <span id="dt-4f524dae-327c-4f52-bba3-8bc87ee70a78"></span><div class="sw-dt-title"><span class="sw-dt-name">hal_event_adapter_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for hal_event_adapter.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - sensor_path_ready
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Sensor HAL path readiness.
   * - uart_path_ready
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - UART HAL path readiness.
   * - led_path_ready
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - LED HAL path readiness.
   * - last_hal_tick
     - :ref:`uint32_t <dt-9930f975-8f88-4930-9e5b-64c21de2689a>`
     - Last adaptation tick.

.. _dt-022a2389-eaf6-422a-b23c-37e842640e7e:

.. raw:: html

   <span id="dt-022a2389-eaf6-422a-b23c-37e842640e7e"></span><div class="sw-dt-title"><span class="sw-dt-name">hal_event_adapter_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by hal_event_adapter.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - HAL adapter event id.
   * - source_channel
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - HAL source channel.
   * - raw_code
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Raw HAL code.
   * - data_valid
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Raw data validation result.

.. _dt-4a899fb6-d425-4a89-9bfa-2bf4435addab:

.. raw:: html

   <span id="dt-4a899fb6-d425-4a89-9bfa-2bf4435addab"></span><div class="sw-dt-title"><span class="sw-dt-name">hal_event_adapter_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for hal_event_adapter operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - HAL event normalized.
   * - SOURCE_UNAVAILABLE
     - 1
     - Expected source unavailable.
   * - NORMALIZATION_ERROR
     - 2
     - Payload normalization failed.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`hal_event_adapter_context <dt-4f524dae-327c-4f52-bba3-8bc87ee70a78>`
     - private
     - Runtime context for hal_event_adapter state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`hal_event_adapter_result <dt-4a899fb6-d425-4a89-9bfa-2bf4435addab>`
- **Visibility:** public
- **Description:** Process one hal_event_adapter event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`hal_event_adapter_event <dt-022a2389-eaf6-422a-b23c-37e842640e7e>`
     - in
     - Process one hal_event_adapter event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`hal_event_adapter_result <dt-4a899fb6-d425-4a89-9bfa-2bf4435addab>`
- **Visibility:** public
- **Description:** Initialize hal_event_adapter runtime state and dependencies.



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



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

hal_event_adapter_activity
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   start
   :Receive raw HAL interrupt or poll data;
   :Normalize hardware payload;
   if (source == sensor) then (yes)
     :Build monitoring event;
   elseif (source == uart) then (yes)
     :Build modbus RX or TX event;
   elseif (source == led driver) then (yes)
     :Build LED driver completion event;
   endif
   :Publish normalized event to dispatcher;
   stop
   @enduml


This activity diagram documents HAL adaptation flow from raw interrupt or polled hardware signals to normalized software events with source specific mapping for sensors communication and LED subsystems.



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

hal_event_adapter_timing
^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   robust "hal_event_adapter" as HAL
   scale max 1200 width
   concise "io event" as E
   
   @0
   E is irq_or_poll
   HAL is normalize_event
   
   @60
   HAL is route_channel
   
   @120
   HAL is publish_upstream
   
   @180
   HAL is idle
   @enduml


This timing diagram characterizes adapter latency from raw hardware event detection to normalized event publication and helps budget interrupt or polling integration delays.



Sequence Diagrams
~~~~~~~~~~~~~~~~~

SEQ-004_Modbus_Event_Servicing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Modbus Server Event Servicing
   
   participant ao_runtime_supervisor
   participant ao_modbus_server
   participant hal_event_adapter
   
   ao_runtime_supervisor -> ao_modbus_server : dispatch comms_event
   ao_modbus_server -> hal_event_adapter : request UART I/O
   hal_event_adapter --> ao_modbus_server : uart_rx/tx completion
   ao_modbus_server -> hal_event_adapter : publish protocol response
   
   @enduml


Runtime-driven communication events are processed by the Modbus server through hardware-adapted UART event exchange.