Characteristic to offer configuration

[Ernst79]

Issue moved from home-assistant/bthome.io#11. Issue originally created by @balloob

Some data we want the receiver to know but it never changes. It would be nice if we could offer a read-only characteristic for receivers to fetch this. It could contain:

• Device class
• Interval that data is send (for unavailable tracking)
• Extended name
• Firmware name
• Firmware version
• Model name
• Manufacturer name

The flow would be:

• Receiver sees a BTHome packet
• Receiver makes a connection to fetch the static configuration
• Receiver will from time to time refresh the static configuration

Example is the pvvx ATC firmware, that also holds device info and keys, that can be read after connecting to the device
https://github.com/pvvx/ATC_MiThermometer#control-function-id-when-connected

[pvvx]

I hope these will be typical UUIDs?

Device Information:
SERVICE_UUID_DEVICE_INFORMATION 0x180A // Device Information Service
CHARACTERISTIC_UUID_MODEL_NUMBER 0x2A24 // Model Number String
CHARACTERISTIC_UUID_SERIAL_NUMBER 0x2A25 // Serial Number String
CHARACTERISTIC_UUID_FIRMWARE_REV 0x2A26 // Firmware Revision String
CHARACTERISTIC_UUID_HARDWARE_REV 0x2A27 // Hardware Revision String
CHARACTERISTIC_UUID_SOFTWARE_REV 0x2A28 // Software Revision String
CHARACTERISTIC_UUID_MANUFACTURER_NAME 0x2A29 // Manufacturer Name String

This list is fully processed in all typical Xiaomi thermometers and with custom firmware, except for the atc1441 option.

https://github.com/pvvx/ATC_MiThermometer#control-function-id-when-connected - The link points to a short description of the service UUID with a specific command format that is different for each device, and not to standard UUIDs.
! If pin code is set then service UUIDs (configuration management) are available only when bonded and pin code is entered. !

[Ernst79]

It looks like they use the official descriptions.
https://www.bluetooth.com/specifications/specs/device-information-service-1-1/

I still have to check the UUIDs, as they don’t give them in this document. They refer to the core Bluetooth specs, will look into that later, but I assume that these will correspond to the ones Xiaomi and you have used. Makes sense to use the same.

From the Device Information service documentation

3 Service Characteristics 

The Device Information Service may expose one or more of the characteristics shown in Table 3.1. It is possible that none of the characteristics below are included. Unless otherwise specified, only one instance of each characteristic shall be present. 

Characteristic Name	Characteristic Qualifier	Mandatory Properties	Optional Properties	Security Permissions
Manufacturer Name String	O	Read		None
Model Number String	O	Read		None
Serial Number String	O	Read		None
Hardware Revision String	O	Read		None
Firmware Revision String	O	Read		None
Software Revision String	O	Read		None
System ID	O	Read		None
IEEE 11073-20601 Regulatory Certification Data List	O	Read		None
PnP ID	O	Read		None

Table 3.1: Device Information Service characteristics 

[pvvx]

• Device class

There may be difficulties here.
Not all implementations can be mapped to comparable code.
https://www.ampedrftech.com/datasheets/cod_definition.pdf

• Interval that data is send (for unavailable tracking)

I do not know such a UUID characteristic.
There is a UUID for the connection interval, but not for the advertising interval.

• Extended name

These are the base UUIDs:

[Ernst79]

I don’t think we need the device class, as this is already defined in the different object_ids.

Data interval isn’t needed either, one of the latest HA versions has now implemented a dynamic time before it becomes unavailable, based on the interval it received the last x advertisements.

[pvvx]

Data interval isn’t needed either, one of the latest HA versions has now implemented a dynamic time before it becomes unavailable, based on the interval it received the last x advertisements.

BLE_UUID_SCAN_PARAMETERS_SERVICE 0x1813
https://github.com/oesmith/gatt-xml/blob/master/org.bluetooth.service.scan_parameters.xml
ScanIntervalWindow 0x2A4F The Scan Interval Window characteristic is used to store the scan parameters of the GATT Client.
https://github.com/oesmith/gatt-xml/blob/master/org.bluetooth.characteristic.scan_interval_window.xml
ScanRefresh 0x2A31 The Scan Refresh characteristic is used to notify the Client that the Server requires the Scan Interval Window characteristic to be written with the latest values upon notification.
https://github.com/oesmith/gatt-xml/blob/master/org.bluetooth.characteristic.scan_refresh.xml

So far I have not seen implementations with UUID_SCAN_PARAMETERS.

[pvvx]

Due to incorrect encoding in BTHome v2, it cannot be supported in ESPHome and other implementations on small SoCs. Requires version 3.

[Ernst79]

What do you mean with “incorrect encoding in BTHome V2”? Can you explain what is wrong (and how to fix)?

[pvvx]

There is no way to identify the size of variables without special tables. When adding a new ID, a mandatory firmware update is required.
Example: We introduce a variable that is not served by HA, but is needed for another application. As a result, we get uncertainty with further versions of HA and we are obliged to follow the changes and constantly update all programs.

---

An example of such a variable is the time in the device. Many SoCs do not have a dedicated clock crystal, and the timing drifts. A third party program can match the counter and decide to synchronize if the drift is large. There is no need to display the time counter in the user interface.

There may also be other variables that are only needed for transfer between devices. The current v2 format requires that you ask for permission to enter them and wait to be entered into the HA.
With the introduction of BT5.0, the size of an ad frame is unlimited and can even contain text for MQTT and other floating-size variables.
BTHome v1 supports all this. But v2 is not.
Increasing the transmission frame size only affects standalone (battery powered) devices. The increase in transmission frame size is offset by a similar increase in transmission interval and is not much of a burden.
A big power savings for a standalone BLE device can be obtained in BT5.0 format of extended advertising with a scan option. In this case, only a short header is present on the main channels, and the message itself is transmitted at the request of scanning on additional channels.

---

How will the parsing of two messages received during the same ad event but from different sources - from the scan request and from the main frame - behave now? ->Will be combined into one promotional event or ? advertisements with multiple measurements of the same type
Similar question with extended adv., where the maximum message length is 1650 bytes. But there may be several messages :) The size of the UUID structure is limited to 255 bytes. If a message contains several BTHome structures, will they be merged?

What do you think of the Advertising ID in Extended Advertising? Advertising identifier - advertising package number.

BT5.3 introduced "AdvDataInfo", the equivalent of "package ID" in BTHome. "Package ID" becomes redundant.

[Ernst79]

Example: We introduce a variable that is not served by HA, but is needed for another application. As a result, we get uncertainty with further versions of HA and we are obliged to follow the changes and constantly update all programs.

An example of such a variable is the time in the device. Many SoCs do not have a dedicated clock crystal, and the timing drifts. A third party program can match the counter and decide to synchronize if the drift is large. There is no need to display the time counter in the user interface.

Just thinking, but if we add a time object id to BTHome, and we don't want to use it in Home Assistant, we should just make HA to skip the object id, and continue with the next. This should be possible, as we know the data length, also in V2.
BTW, i saw your request for a unix time object, I will add that in the near future. Having some family health issues at the moment, so can take a bit longer.

There may also be other variables that are only needed for transfer between devices. The current v2 format requires that you ask for permission to enter them and wait to be entered into the HA.
I guess that is the same for V1, as long as we haven't updated HA to a new BTHome version, it won't work.
With the introduction of BT5.0, the size of an ad frame is unlimited and can even contain text for MQTT and other floating-size variables.
BTHome v1 supports all this. But v2 is not.

Yes, but at the moment, we don't have any text objects, both not in V1 as well as not in V2. Yes, of course V1 is able to just use a string for any object id, but that would just confuse the receiving side. (e.g. in V1 using an object id of temperature and using a string format will probably not work correctly in HA, as temperature sensors are expected to be a float or integer). But I don't see any objection adding an object id for a text sensor with variable length. This can be added both in V1 and in V2, we only have to modify the code a little bit in V2, such that we can add a length byte in the data for text sensors. In V1, this is already there, but I don't see a big issue adding this to V2. Something like

if obj_meas_type in VARIABLE_LENGTH_SENSORS:
    obj_data_length = obj_data_start[0]
else:
     obj_data_length = MEAS_TYPES[obj_meas_type].data_length

How will the parsing of two messages received during the same ad event but from different sources - from the scan request and from the main frame - behave now? ->Will be combined into one promotional event or ? advertisements with multiple measurements of the same type

Good question. But I was thinking that the characteristics should only contain specific data for configuration, e.g. device information. A next step could be sensor data as well, but that is probably for BTHome V3 or V4.

Similar question with extended adv., where the maximum message length is 1650 bytes. But there may be several messages :) The size of the UUID structure is limited to 255 bytes. If a message contains several BTHome structures, will they be merged?

What do you think of the Advertising ID in Extended Advertising? Advertising identifier - advertising package number.

BT5.3 introduced "AdvDataInfo", the equivalent of "package ID" in BTHome. "Package ID" becomes redundant.

Again, good questions (and suggestions). This is something for the future to figure out.