drv_rgb_led
===========

Driver unit applying LED command events to RGB hardware channels.

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

- :doc:`RGB_LED_Driver </generated/architecture/rgb-led-driver-0f6fe814-e3b7-4f6f-a143-4bf245ee5f86>`

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

- :doc:`REQ-IFC-005 </generated/requirements/req-ifc-005-e9ec1206-b39c-49ec-bece-33c3fb8a40a0>`

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

.. image:: /_static/sw_unit_uml/drv_rgb_led_fe18dd0c-8b06-4e18-8db9-3fb3b85538a0_uml.svg
   :alt: UML class diagram for drv_rgb_led
   :class: dblclick-open-image


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

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

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

   * - Relation
     - UML Type
     - Visibility
     - Target Unit
     - Description
   * - :doc:`SWR-019 </generated/detailed_design/relations/swr-019-48ca5733-416a-48ca-b154-c51bd9eacfdc>`
     - dependency
     - private
     - :doc:`hal_event_adapter </generated/detailed_design/units/hal-event-adapter-9629a78b-294f-4629-b709-fc03c058c26d>`
     - LED driver uses hardware abstraction events.

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

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

   * - Relation
     - UML Type
     - Visibility
     - Source Unit
     - Description
   * - :doc:`SWR-016 </generated/detailed_design/relations/swr-016-6a64f3bd-1c48-4a64-bfe6-7a68c20744c6>`
     - dependency
     - public
     - :doc:`ao_status_indication </generated/detailed_design/units/ao-status-indication-2f37d667-1c29-4f37-b12f-138196fec6b0>`
     - Status indication commands LED driver outputs.

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

.. _dt-9db8dabb-85e9-4db8-97f9-380da0d77cf3:

.. raw:: html

   <span id="dt-9db8dabb-85e9-4db8-97f9-380da0d77cf3"></span><div class="sw-dt-title"><span class="sw-dt-name">drv_rgb_led_context</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Internal runtime context for drv_rgb_led.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - driver_state
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Driver state.
   * - color_code
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Applied color code.
   * - blink_period_ms
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - Applied blink period.
   * - hw_ready
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Hardware readiness.

.. _dt-aeba28c0-cc05-4eba-b881-6492d5254856:

.. raw:: html

   <span id="dt-aeba28c0-cc05-4eba-b881-6492d5254856"></span><div class="sw-dt-title"><span class="sw-dt-name">drv_rgb_led_event</span><span class="sw-dt-badge sw-dt-badge-struct">struct</span></div>

Event payload handled by drv_rgb_led.

.. rubric:: Struct Members

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

   * - Name
     - Type
     - Description
   * - signal_id
     - :ref:`uint16_t <dt-036d66c4-d7f5-436d-8f41-bf413e2d3351>`
     - LED driver event id.
   * - requested_color
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Requested color code.
   * - blink_enable
     - :ref:`bool <dt-c71dfd1b-cce2-471d-a034-2a7bdc7b8d25>`
     - Blink command.
   * - intensity_pct
     - :ref:`uint8_t <dt-45402023-5ffe-4540-ba19-64896d87b3dc>`
     - Requested intensity percent.

.. _dt-ba5209b1-fcad-4a52-bfc1-48eee3923525:

.. raw:: html

   <span id="dt-ba5209b1-fcad-4a52-bfc1-48eee3923525"></span><div class="sw-dt-title"><span class="sw-dt-name">drv_rgb_led_result</span><span class="sw-dt-badge sw-dt-badge-enum">enum</span></div>

Result code for drv_rgb_led operations.

.. rubric:: Enum Members

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

   * - Name
     - Value
     - Description
   * - OK
     - 0
     - LED command applied.
   * - HAL_WRITE_ERROR
     - 1
     - HAL write failed.
   * - UNSUPPORTED_PATTERN
     - 2
     - Pattern not supported.



Attributes
----------

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

   * - Attribute
     - Type
     - Visibility
     - Description
   * - ctx
     - :ref:`drv_rgb_led_context <dt-9db8dabb-85e9-4db8-97f9-380da0d77cf3>`
     - private
     - Runtime context for drv_rgb_led state timing and error tracking.

Methods
-------

dispatch
~~~~~~~~

- **Return Type:** :ref:`drv_rgb_led_result <dt-ba5209b1-fcad-4a52-bfc1-48eee3923525>`
- **Visibility:** public
- **Description:** Process one drv_rgb_led event and update runtime outputs.

.. rubric:: Parameters

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

   * - Name
     - Type
     - Direction
     - Description
   * - event
     - :ref:`drv_rgb_led_event <dt-aeba28c0-cc05-4eba-b881-6492d5254856>`
     - in
     - Process one drv_rgb_led event and update runtime outputs.

init
~~~~

- **Return Type:** :ref:`drv_rgb_led_result <dt-ba5209b1-fcad-4a52-bfc1-48eee3923525>`
- **Visibility:** public
- **Description:** Initialize drv_rgb_led runtime state and dependencies.



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



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

drv_rgb_led_activity
^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   start
   :Receive IF_StatusLedCommand;
   :Decode requested color or pattern;
   :Map to hardware channel values;
   :Write PWM or GPIO outputs via HAL;
   if (write failed?) then (yes)
     :Emit driver error event;
   else (no)
     :Confirm applied output;
   endif
   stop
   @enduml


This activity diagram defines driver level translation from abstract LED intents into hardware channel writes including failure handling behavior when output programming does not complete as requested.



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

drv_rgb_led_timing
^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   robust "drv_rgb_led" as LED
   scale max 1200 width
   concise "led command" as C
   
   @0
   C is rx
   LED is decode
   
   @40
   LED is map_hw_values
   
   @90
   LED is write_hw
   
   @150
   LED is applied
   @enduml


This timing diagram shows driver execution from command reception through hardware mapping and write completion to validate tight actuation timing in the LED indication chain.



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

SEQ-003_Status_To_LED_Indication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. uml::

   @startuml
   
   hide footbox
   title Diagnostic Status To LED Indication
   
   participant ao_diagnostics
   participant ao_status_indication
   participant sm_led_indication
   participant drv_rgb_led
   
   ao_diagnostics -> ao_status_indication : IF_OperatingStatus(system_status)
   ao_status_indication -> sm_led_indication : evaluate indication pattern
   sm_led_indication -> ao_status_indication : resolved LED intent
   ao_status_indication -> drv_rgb_led : IF_StatusLedCommand(led_command)
   
   @enduml


Diagnostics status outputs are transformed by status indication logic into concrete LED driver commands.