===== Bluetooth Low Energy =====

This project utilizes Bluetooth Low Energy (BLE) as its communication protocol. BLE was chosen for its well-defined standard and proven robustness.

The standard UUIDs referenced in this project are based on the numbers officially assigned by the Bluetooth SIG. A complete list can be found in the official [[https://bitbucket.org/bluetooth-SIG/public/src/main/assigned_numbers/uuids|Bluetooth SIG git repository]].

===== Concept =====

The BLE protocol is built on a three-layered architecture consisting of:

  - **Service:** Groups related functions (e.g., "Device Information").
  - **Characteristic:** Contains a single data point or value (e.g., "Firmware Revision").
  - **Descriptor:** Provides metadata about a characteristic (e.g., a human-readable description).

Each peripheral (the device to be controlled) announces its presence and basic data through **advertising**. To uniquely identify and filter for project-specific devices, the manufacturer id is set to ''C0DE''.

===== Services =====

For custom, project-specific services, the UUID range ''0xAxxx'' is used, as this area was officially unassigned at the time of development.

==== Device Information Service (0x180A) ====
This standard service is implemented by every device to provide basic information, such as hardware and software versions. It utilizes some of the standard characteristics from the ''0x2Axx'' range, as described below.

==== Light Service (0xA000) ====
This service groups all characteristics required for controlling light sources.
**(Note: The associated characteristics are not yet fully defined.)**

==== Settings Service (0xA999) ====
This service provides general configuration options for the device.
**(Note: The associated characteristics are not yet fully defined.)**

===== Characteristics ======

==== Device Name (0x2A00) ====
Represents the name of the device as it should appear to the user.

==== Firmware Revision (0x2A26) ====
Returns the current firmware version string. This value is critical for performing Firmware-Over-the-Air (FOTA) updates.

==== Hardware Revision (0x2A27) ====
Returns the hardware version of the custom PCB. This is relevant because updated board revisions may require different data handling or firmware versions.

==== Manufacturer (0x2A29) ====
Returns the static string value "mars3142".

===== Descriptors =====

==== User Description (0x2901) ====
This descriptor provides a user-readable description for a characteristic. It allows a user interface (UI) to display a meaningful name for custom characteristics (e.g., //Brightness// or //Color Temperature//).

==== Presentation Format (0x2904) =====
Defines the data type and format of a characteristic's value to provide hints to the UI for optimal presentation. For example, a //boolean// format signals that a toggle switch is a suitable control.

==== Valid Range (0x2906) ====
Defines a valid range (minimum and maximum) for a characteristic's value. This can be used by a UI to properly configure controls like a slider.