1.. _module-pw_bluetooth_profiles: 2 3===================== 4pw_bluetooth_profiles 5===================== 6.. pigweed-module:: 7 :name: pw_bluetooth_profiles 8 9.. attention:: 10 11 :bdg-ref-primary-line:`module-pw_bluetooth_profiles` is under construction, 12 depends on the experimental :bdg-ref-primary-line:`module-pw_bluetooth` 13 module and may see significant breaking API changes. 14 15The ``pw_bluetooth_profiles`` module provides a collection of implementations 16for basic Bluetooth profiles built on top of the ``pw_bluetooth`` module API. 17These profiles are independent from each other 18 19-------------------------- 20Device Information Service 21-------------------------- 22The ``device_info_service`` target implements the Device Information Service 23(DIS) as defined in the specification version 1.1. It exposes up to nine 24different basic properties of the device such as the model, manufacturer or 25serial number, all of which are optional. This module implements the GATT 26server-side service (``bluetooth::gatt::LocalServiceDelegate``) with the 27following limitations: 28 29- The subset of properties exposed and their values are constant throughout the 30 life of the service. 31- The subset of properties is defined at compile time, but the values may be 32 defined at runtime before service initialization. For example, the serial 33 number property might be different for different devices running the same 34 code. 35- All property values must be available in memory while the service is 36 published. Rather than using a callback mechanism to let the user produce the 37 property value at run-time, this module expects those values to be readily 38 available when initialized, but they can be stored in read-only memory. 39 40Usage 41----- 42The main intended usage of the service consists on creating and publishing the 43service, leaving it published forever referencing the values passed on 44initialization. 45 46The subset of properties exposed is a template parameter bit field 47(``DeviceInfo::Field``) and can't be changed at run-time. The ``pw::span`` 48values referenced in the ``DeviceInfo`` struct must remain available after 49initialization to avoid copying them to RAM in the service, but the 50``DeviceInfo`` struct itself can be destroyed after initialization. 51 52Example code: 53 54.. code-block:: cpp 55 56 using pw::bluetooth_profiles::DeviceInfo; 57 using pw::bluetooth_profiles::DeviceInfoService; 58 59 // Global serial number for the device, initialized elsewhere. 60 pw::InlineString serial_number(...); 61 62 // Select which fields to expose at compile-time with a constexpr template 63 // parameter. 64 constexpr auto kUsedFields = DeviceInfo::Field::kModelNumber | 65 DeviceInfo::Field::kSerialNumber | 66 DeviceInfo::Field::kSoftwareRevision; 67 68 // Create a DeviceInfo with the values. Values are referenced from the 69 // service, not copied, so they must remain available while the service is 70 // published. 71 DeviceInfo device_info = {}; 72 device_info.model_number = pw::as_bytes(pw::span{"My Model"sv}); 73 device_info.software_revision = pw::as_bytes(pw::span{REVISION_MACRO}); 74 device_info.serial_number = pw::as_bytes( 75 pw::span(serial_number.data(), serial_number.size())); 76 77 DeviceInfoService<kUsedFields, pw::bluetooth::gatt::Handle{123}> 78 device_info_service{device_info}; 79 device_info_service.PublishService(...); 80