Support for GATT Characteristic and Object Type
Ernst79 opened this issue · 5 comments
@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.
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
CayenneLPPGATT 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)
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
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
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
The current version is released as 7.7.0. Automatic sensor creation will be added in a future release.