Support for GATT Characteristic and Object Type

[Ernst79]

@myhomeiot proposed in #548 to add support for the CayenneLPP for DIY sensors. After some research it turns out that the BLE format already has a definition for sensor readings, called GATT Characteristic and Object Type. The service data UUID16 field (0x16) cannot only contain UUID16, but also GATT Characteristic and Object Type service data.

In the following document, the 16-bit UUID for Members (indicator for manufacturers) can be found on page 1-13. But more interesting for DIY sensors are the so called GATT Characteristic and Object Type, which can be found on page 13 and further.

https://btprodspecificationrefs.blob.core.windows.net/assigned-values/16-bit%20UUID%20Numbers%20Document.pdf

An example

A battery reading would read like

04162A1964

04 = length (without the first byte)
16 = service data
2A19 = Battery
64 = in hex is 100 in decimals

The definition of how the actual data should be defined is also defined in the GATT specification supplement.

https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=524815

Again, as example, as battery reading should be defined in 1 byte, raging between 0-100 (equals to 0x00-0x64 in hex)

• Do some reading about CayenneLPP GATT Characteristic and Object Type
• Make a definition how we can recognize our DIY sensors
• Add payload parser
• Create sensors based on the payload (likely to be a significant change in the code)

[Ernst79]

Definition [WIP]

Option 1
Using the Manufacturer Specific Data type 0xFF and defining our own "company". I think this isn't allowed, you have to be a member of the Bluetooth SIG for that.

Option 2
Definition by the Shortened Local Name type0x08
070848415F424C45
07 = length 7 bytes
08 = Shortened Local Name
48415F424C45 = HA_BLE

Option 3
Using the Incomplete List of 128-bit Service Class UUIDs. I think this is allowed, as far as I can see.

My first preference goes to the second option at the moment

[Ernst79]

Data packets

The following data packets are going to be used, following the Bluetooth specifications (table is work in progress)

Object id	Property	Data type	Factor	example	result	Unit in HA
0x2A19	battery	uint8 (1 byte)	1	0416192A59	89	%
0x2A6D	pressure	uint32 (4 bytes)	0.001	07166D2A78091000	1051.0	hPa
0x2A6E	temperature	sint16 (2 bytes)	0.01	05166E2A3409	23.56	°C
0x2A6F	humidity	uint16 (2 bytes)	0.01	05166F2A5419	64.84	%
0x2A7B	dewpoint	sint8 (1 byte)	1	04167b2a18	24	°C
0x2A98	weight	struct (1 byte, flag)) +	bit 0 of flag = 0 = 0.005	0616982A00AA33	66.13	kg (bit 0 of flag = 0)
		uint16 (2 bytes, weight)	bit 0 of flag = 1 = 0.01	0616982A01AA33	132.26	lbs (bit 0 of flag = 1)
0X2AF2	energy	uint32 (4 bytes)	0.001	0716F22A81121000	1053.313	kWh
0X2AFB	illuminance	uint24 (3 bytes)	0.01	0616FB2A34AA00	435.72	lux
0x2B05	power	uint24 (3 bytes)	0.1	052B510A00	264.1	W
0x2B18	voltage	uint16 (2 bytes)	1/64	0516182BB400	2.8125	V
0x2BD6	pm2.5	SFLOAT (2 bytes)	1	0516D62BD204	1234	kg/m3
0x2BD7	pm10	SFLOAT (2 bytes)	1	0516D72BAB01	427	kg/m3

The factor is used to convert the broadcasted integer to a decimal, and is defined in the Bluetooth specs.

e.g. 05166E2A3409

05 = length
16 = service data
6E2A = 0x2A6E = "temperature"
3409 = 0x0934 = 2356 --> 2356 * 0.01 = 23.56°C

[Ernst79]

A first Work in Progress version can be found in the HA-BLE branch.

At the moment, I have added the temperature sensor to const.py manually, you can test it by changing this line in const.py to the sensor you want (all sensors from the above table should work). Some example payloads are given in the test_ha_ble.py file

BLE advertisements must contain 070848415f424c45, which means shortened local name = HA_BLE

[Ernst79]

The current version is released as 7.7.0. Automatic sensor creation will be added in a future release.

[Ernst79]

I have been working on a new format for HA BLE, together with input from @pvvx. So this issue will be closed and support for BLE messages that follow the GATT Characteristics will be dropped soon, after the new format has been released. More info on the new format can be found in #548