search

WebThingsIO / api

Web Thing API Specification
http://iot.mozilla.org/wot/
Other
164 stars 25 forks source link

Replace Eddystone beacons with custom BLE beacon #110

Closed mrstegeman closed 5 years ago

mrstegeman commented 5 years ago

This would allow us to differentiate webthings from other generic beacons. HomeKit does this as well. Their beacon includes a myriad of useful information about the device that can be read without having to connect to the device.

We already have our own DNS-SD service type, so this is just the BLE counterpart.

mrstegeman commented 5 years ago

Below is the BLE advertisement data for HAP (HomeKit Accessory Protocol), for reference.

6.4.2 HAP BLE 2.0 Advertisement Format

All bytes in the Advertisement Data are reserved and must not be used for any other purpose. The advertisement data must include the following fields:

6.4.2.1 Flags

Table 6-28 Flags Description

Length AD Type Value
0x02 0x01 0bxxxxxx1x

6.4.2.2 Manufacturer Data

Table 6-29 Manufacturer Specific Data

Length AD Type Company ID Type AIL SF 48-bit Device ID
0x12 0xFF 0x4C 0x00 0x06 0xXX 0x00/0x01 0xXX 0xXX 0xXX 0xXX 0xXX 0xXX

Table 6-30 Manufacturer Specific Data - continued

ACID GSN CN CV
0xXX 0xXX 0xXX 0xXX 0xXX 0x02

Table 6-31 Advertising Intervals

Value Advertising Interval
0x2D 10-25 ms
0x4D 26-100 ms
0x6D 101-300 ms
0x8D 301-500 ms
0xAD 501-1250 ms
0xCD 1251-2500 ms
0xED > 2500 ms

Table 6-32 HAP Pairing Status Flag

Value Description
0b0 The accessory has been paired with a controllers.
0b1 The accessory has not been paired with any controllers.

6.4.2.3 Local Name

Table 6-33 Local Name

Length AD Type Value
0xXX 0x08/0x09 0xXX 0xXX ... 0xXX
mrstegeman commented 5 years ago

References #75

benfrancis commented 5 years ago

If we did this, I think it we should try and turn it into a standard for web thing URL discovery as opposed to something proprietary for our gateway implementation. The question is whether this would be an extension of Eddystone, or something else. And whether it could be standardised via the W3C as part of the Web of Things, or would need to be done separately or through another standards body.

I bet @scottjenson has some ideas, and @phoddie has similarly proposed adding more metadata to mDNS broadcasts.

My main concern would be how much this duplicates the Thing Description itself, and what happens if the two (or three) get out of sync. Currently both Bluetooth beacons and mDNS broadcasts are used as a URL discovery mechanism, then the web layer takes over the rest. I quite like the simplicity of that to be honest, but I can see the attraction of including more metadata in the broadcasts themselves.

mrstegeman commented 5 years ago

@benfrancis I absolutely agree that this should not be proprietary to our implementation. Rather, the webthing mDNS service, and this new beacon type, should both be standardized as part of (or as an extension of) the WoT.

Right now, additional metadata in the broadcast may indeed be a duplication. However, when things start being protected by security mechanisms, such that the Thing Description cannot be read without first authenticating with the device, it makes sense to have some basic information in the broadcast. For example, with HomeKit devices, this is how we're able to classify devices as basic thing types before actually pairing with them.

While additional metadata is not necessary at this time, having our own, separate broadcast type allows us to add it in the future without having to change the fundamental broadcast type.

mrstegeman commented 5 years ago

To add to the information posted above, about HomeKit's Bluetooth beacon format, here is what is included in their mDNS broadcasts.

5.4 Discovery

Accessories advertise their presence on the network via Bonjour. HAP clients browse for them and if any are found and determined to be compatible, they are displayed to the user. The Bonjour service type is:

_hap._tcp

The name of the Bonjour service is the user-visible name of the accessory, e.g. "LED Bulb M123", and must match the name provided in the Accessory Information Service of the HAP Accessory object that has an instanceID of 1. The name may contain any Unicode character and is encoded using UTF-8. It has a maximum length of 63 bytes, which may be fewer than 63 characters as a single Unicode character may require multiple bytes. Additional data needed for discovery-time metadata is advertised via a TXT record associated with the Bonjour service. TXT record keys are intentionally short to minimize network traffic. Accessories must confirm to the TXT records as defined in Table 5-7 (page 69)

Table 5-7 _hap._tcp Bonjour TXT Record Keys

Key Description
"c#" Current configuration number. Required.
Must update when an accessory, service, or characteristic is added or removed on the accessory server.
Accessories must increment the config number after a firmware update.
This must have a range of 1-4294967295 and wrap to 1 when it overflows.
This value must persist across reboots, power cycles, etc.
"ff" Feature flags (e.g. "0x3" for bits 0 and 1). Required if non-zero. See Table 5-8 (page 69).
"id" Device ID (Device ID (page 36)) of the accessory. The Device ID must be formatted as "XX:XX:XX:XX:XX:XX", where "XX" is a hexadecimal string representing a byte. Required.
This value is also used as the accessory's Pairing Identifier.
"md" Model name of the accessory (e.g. "Device1,1"). Required.
"pv" Protocol version string <major>.<minor> (e.g. "1.0"). Required if value is not "1.0".
The client should check this before displaying an accessory to the user. If the major version is greater than the major version the client software was built to support, it should hide the accessory from the user. A change in the minor version indicates the protocol is still compatible. This mechanism allows future versions of the protocol to hide itself from older clients that may not know how to handle it.
"s#" Current state number. Required.
This must have a value of "1".
"sf" Status flags (e.g. "0x04" for bit 3). Value should be an unsigned integer. Required if non-zero. See Table 5-9 (page 70). Required.
"ci" Accessory Category Identifier. Required. Indicates the category that best describes the primary function of the accessory. This must have a range of 1-65535. This must take values defined in Table 12-3 (page 254). This must persist across reboots, power cycles, etc.

Table 5-8 Bonjour TXT Record Feature Flags

Mask Bit Description
0x01 1 Supports HAP Pairing. This flag is required for all HomeKit accessories.
0x02-0x80 2-8 Reserved.

Table 5-9 Bonjour TXT Status Flags

Mask Bit Description
0x01 1 Accessory has not been paired with any controllers.
0x02 2 Accessory has not been configured to join a Wi-Fi network.
0x04 3 A problem has been detected on the accessory.
0x08-0x80 4-8 Reserved.
mrstegeman commented 5 years ago

We've now stopped supporting Eddystone beacons, as they're no longer supported by any major OS.