Skip to content

Latest commit

 

History

History
209 lines (159 loc) · 14.6 KB

README.md

File metadata and controls

209 lines (159 loc) · 14.6 KB
Raw

Advanced Bluetooth Binding

The Advanced Bluetooth binding brings support for Bluetooth technology into Eclipse SmartHome Framework. The following main use cases are supported by the binding:

  • Presence detection. Bluetooth devices can be monitored whether they are in range of a bluetooth adapter (or multiple bluetooth adapters). This feature makes it possible to detect if an object or a person enters or leaves a building or a room.
  • Indoor positioning. Location of a Bluetooth device can be identified based on estimated distance between the device and adapters. This feature allows you to locate things (like your phone or keys) in your house or detect who exactly is in a room.
  • Comprehensive support for Bluetooth Low Energy (Bluetooth Smart) devices. If a bluetooth device supports the Bluetooth specification 4.0, then the standard GATT services and characteristics can be automatically recognized and corresponding thing channels be created for each GATT characteristic and its GATT fields. This feature allows you to connect Bluetooth Smart sensors and other Bluetooth devices.
  • Custom built (non-standard) BLE bluetooth devices support. A custom built Bluetooth device can be automatically recognized like a standard one by specifying a folder on the system disk with custom GATT service and characteristic definitions in XML files.

Table of contents

Installation

The Bluetooth binding can be installed via PaperUI and Eclipse MarketPlace. Please follow this guide.

Supported Things and Discovery

Bluetooth Adapter

There is only one "thing" that represents all adapters (Generic and BlueGiga) in the binding.

  • Generic adapters should appear in the discovery inbox without making any configuration changes: ESH Bluetooth Binding adaptes discivery
  • BlueGiga adapters will appear after configuring serial port regular expression on the binding configuration page: ESH Bluegiga adapters configure WARNING!: It is very important to make the regular expression NOT too wide so that ONLY Bluegiga adapters/ serial ports are matched by the regular expression. If the regular expression is too broad, this can lead to hardware malfunction/damage of other devices that are accidentally matched by the regular expression. USE THIS FEATURE AT YOUR OWN RISK. Regular expression examples:
    • Defining some specific serial ports (preferable option): (/dev/ttyACM1)|(/dev/ttyACM2)
    • Matching all serial ports on Linux: ((/dev/ttyACM)[0-9]{1,3})
    • Matching all serial ports on OSX: (/dev/tty.(usbmodem).*)
    • Matching all serial ports on Windows: ((COM)[0-9]{1,3})
    • Matching all serial ports with some exclusions: (?!/dev/ttyACM0|/dev/ttyACM5)((/dev/ttyACM)[0-9]{1,3})
    • Default regular expression is to match nothing: (?!)

Discovered adapters can be added as new things from the PaperUI inbox. It is possible to enable/disable discovery of Bluetooth devices for each added adapter thing: ESH Bluetooth adapter

Generic Bluetooth device

This thing is intended to be used for older versions of bluetooth devices which do not support BLE technology.

Some of mobile phones (older versions) are recognised as generic bluetooth device: ESH Bluetooth generic device discovery

Only Presence detection and Indoor positioning features are available for this type of Bluetooth devices: ESH Bluetooth generic device

BLE enabled Bluetooth device

This thing is used for newer versions of Bluetooth devices which support BLE technology (public and private static address types). ESH Bluetooth ble device discovery

All the binding features are fully supported by this thing. For example, a standard Bluetooth heart rate monitor will look like that: ESH Bluetooth ble device

From the picture above you can see a list of channels that are automatically created for all discovered GATT services and characteristics of the heart rate monitor device.

Beacon Bluetooth device

This thing is used for some Bluetooth devices that periodically change its addresses (private non-resolvable and resolvable address types) to some random addresses in order to protect privacy of their owners. All modern mobile phones (iPhone and Android) evey so often (roughly every 10 minutes) randomly generate a new Bluetooth address and abandon old one making it impossible to track them.

Only Presence detection and Indoor positioning features are available for this type of Bluetooth devices: ESH Beacon Bluetooth device

Usage

Presence detection

Bluetooth devices are able to broadcast (advertise) some information that can be used to identify them via radio signal, normally it is:

  • Device name
  • Device address
  • Service identifiers and data
  • Manufacturer data

Bluetooth receivers (adapters) periodically scan radio frequencies for advertised messages and report them to the binding. By using advertised messages the binding is able automatically discover Bluetooth devices and also track its presence.

The easiest and most effective way to detect presence is to use so called "Bluetooth beacon" devices.

Normally, most of Bluetooth devices broadcast messages, however there are some devices that try to hide themselves from receivers providing privacy for their owners. Many of modern mobile phones (iPhone and Android) evey so often (roughly every 10 minutes) randomly generate a new Bluetooth address and abandon old one making it impossible to track them by its address.

The binding implements an algorithm to match Bluetooth devices not by its address but by a combination of the following:

  • Advertised device name
  • Advertised service UUID/value (not yet implemented)

Moreover, Android and iPhone smartphones also stop advertising (turns off broadcasting so that no any Bluetooth device can find them) once Bluetooth settings screen gets closed. Some mobile apps can be used to enforce Bluetooth broadcasting to be always on, they normally called "Bluetooth beacon simulators".

//TODO list some beacon simulators

Indoor positioning

Bluetooth adapters are capable of sensing strength of radio signal that is transmitted by Bluetooth devices (Received signal strength indication; RSSI). The binding is able to calculate estimated distance between adapters and devices by analysing RSSI levels. The closer device to adapter, the stronger signal. If multiple adapters are installed into the system, the binding can be used to detect location of Bluetooth device by comparing estimated distance between device and adapters.

Multiple adapters must be used in order the indoor positioning to functional effectively.

It is advisable that adapters are physically separated from each other as much as possible. For example, you may want to install Bluetooth adapters in each room of your house so that the binding will be able to locate Bluetooth devices in each room. Therefore defining a location for each adapter is essential: ESH Bluetooth adapter location

The location of the nearest adapter will be reported by Bluetooth device thing: ESH Bluetooth generic device

Bluetooth Smart (BLE) device

  • Xiaomi
  • Smart thermostats (todo)
  • Some blinds (todo)

Extending the binding

In order to add support for new devices, the binding can be extended in several ways - declarative and programmatic:

Implementation notes

The binding extensively uses Java Bluetooth Manager and Bluetooth GATT Parser. More details can be found here.

Bluetooth adapters compatibility matrix

There are two types of adapters that are supported by the binding. Each of them has pros and cons. You may find that not all of them will work for you:

  • Generic adapter (Supported by the TinyB Transport SmartHome extension). This a type of bluetooth adapters that you can buy from your local computer store. These are the most common adapters, most likely you have one already or it is embedded into your PC/laptop (or Raspberry PI). However, there is a major drawback - it works only in Linux based environments, to be more precise, it requires Bluez software installed in your OS.
  • BlueGiga serial adapter (Supported by the BlueGiga Transport SmartHome extension). This a special type of bluetooth adapters that is quite rare. It is not easy to find it in a local computer store, but still possible to buy it over the Internet. One of the most common is Bluegiga BLED112. The main criteria in selecting a BlueGiga adapter is that it must support BGAPI (check this before you buy an adapter).

The following table shows some major features supported by each adapter type:

Generic BlueGiga
Windows - Y
Linux Y Y
Mac - Y
X86 32bit Y Y
X86 64bit Y Y
ARM v6 (Raspberry PI) Y Y
Adapters autodiscovery Y Y
Adapter aliases Y -
Device aliases Y -
BLE devices support Y Y
BR/EDR devices support (legacy BT) Y -

Troubleshooting

Roadmap

  1. Clean up Bluetooth Manager API so it can be shared between multiple clients.
  2. Test and add support for the following devices:
  3. Implement a workaround for mobile phones (recent models of iphone and android) that dynamically allocate MAC addresses so the such phones can be used for presence detection.
  4. Improve indoor positioning performance and accuracy.
  5. Create a new template project (bluetooth binding extension) which demonstrates how to create custom bluetooth bindings.
  6. The ultimate goal: provide a comprehensive and integrated environment for building custom bluetooth devices (sensors) based on the Bluetooth binding, cheap $2 bluetooth board (nrf51822) and Mbed OS. This should bring an easy way to build your own wireless sensors for a very affordable price.