Differences

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

--- project:maerklin:system_control:ble:start [2025/08/30 12:39] – [Presentation format (0x2904)] 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.
-==== Device information service (0x180A) ====
+For custom, project-specific services, the UUID range ''0xAxxx'' is used, as this area was officially unassigned at the time of development.
-The device information service for describing the device (hardware and software). It will use some of the characteristics (within the 0x2Axx area) from below.
+==== 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) ====
+==== 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) ====
+==== Settings Service (0xA999) ====
+This service provides general configuration options for the device.
+**(Note: The associated characteristics are not yet fully defined.)**
-===== Characteristics =====
+===== Characteristics ======
-==== Device name (0x2A00) ====
+==== Device Name (0x2A00) ====
+Represents the name of the device as it should appear to the user.
-It depends on the device, as expected.
+==== Firmware Revision (0x2A26) ====
-==== Firmware revision (0x2A26) ====
+Returns the current firmware version string. This value is critical for performing Firmware-Over-the-Air (FOTA) updates.
-It reflects the firmware version, which is important for FOTA (firmware over the air) updates.
+==== Hardware Revision (0x2A27) ====
-==== 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.
-The hardware depends on the custom PCB, because updated boards, sometimes need other BLE data.
 ==== Manufacturer (0x2A29) ====
+Returns the static string value "mars3142".
-The returned value will always be **mars3142**.
 ===== Descriptors =====
-==== User description (0x2901) ====
+==== 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//).
-This value will name the characteristics, which are custom, so it could be shown in the user interface.
+==== Presentation Format (0x2904) =====
-==== 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.
-We will use it to define the user interface. If the format is a bool, the ui should show one on/off switch.
+==== Valid Range (0x2906) ====
-==== 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.