Differences

This shows you the differences between two versions of the page.

--- project:maerklin:system_control:ble:start [2025/08/30 12:28] – [0x2A27 (hardware revision)] Peter Siegmund
+++ project:maerklin:system_control:ble:start [2025/09/03 09:15] (current) – [Concept] Peter Siegmund
@@ Line 1: / Line 1: @@
-====== Bluetooth Low Energy ======
+===== Bluetooth Low Energy =====
-Bluetooth Low Energy or BLE for short is the transmission protocol of my choice, because it's well defined and has proven to be rock solid. Later in the documentation I refer to default UUIDs, which can be found on the official Bluetooth SIG [[https://bitbucket.org/bluetooth-SIG/public/src/main/assigned_numbers/uuids/|git repository]] (or you search for the PDF).
+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 =====
-BLE hast a three layered protocol. You define a service, characteristics and if needed, descriptors. Every peripheral (our devices, which should be controlled) advertises meta data. In my project it's the manufacturer data of **C0DE**, so I can filter for my devices.
+The BLE protocol is built on a three-layered architecture consisting of:
-===== Services =====
+  - **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).
-I checked the original assigned numbers for services and right of now, the area 0xAxxx is unused, so I occupied these.
+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''.
-Every device will have the **0x180A**, which will tell everyone what it will be. My other services will be the same across other devices, but the characteristics within will be different.
+===== Services =====
-The following section will be a summary of the used services.
+For custom, project-specific services, the UUID range ''0xAxxx'' is used, as this area was officially unassigned at the time of development.
-==== 0x180A (device information service) ====
+==== 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.
-The device information service for describing the device (hardware and software). It will use some of the characteristics (within the 0x2Axx area) from below.
+==== Light Service (0xA000) ====
+This service groups all characteristics required for controlling light sources.
+**(Note: The associated characteristics are not yet fully defined.)**
-==== Light service (0xA000) ====
+==== Settings Service (0xA999) ====
+This service provides general configuration options for the device.
+**(Note: The associated characteristics are not yet fully defined.)**
-==== Settings service (0xA999) ====
+===== Characteristics ======
-===== Characteristics =====
+==== Device Name (0x2A00) ====
+Represents the name of the device as it should appear to the user.
-==== Device name (0x2A00) ====
+==== Firmware Revision (0x2A26) ====
+Returns the current firmware version string. This value is critical for performing Firmware-Over-the-Air (FOTA) updates.
-It depends on the device, as expected.
+==== Hardware Revision (0x2A27) ====
-==== Firmware revision (0x2A26) ====
+Returns the hardware version of the custom PCB. This is relevant because updated board revisions may require different data handling or firmware versions.
-It reflects the firmware version, which is important for FOTA (firmware over the air) updates.
+==== Manufacturer (0x2A29) ====
-==== Hardware revision (0x2A27) ====
+Returns the static string value "mars3142".
-The hardware depends on the custom PCB, because updated boards, sometimes need other BLE data.
-==== 0x2A29 (manufacturer) ====
-The returned value will always be **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.