---
alias: user-guide-driver-ble
tags:
- connect iot
description: "This documentation details a BLE driver for connecting to IoT devices, outlining data types, protocol parameters, and system requirements"
---

# Connect IoT - BLE Driver

Bluetooth Low Energy (Bluetooth LE, BLE, formerly marketed as Bluetooth Smart) is a wireless personal area network technology designed and marketed by the Bluetooth Special Interest Group (SIG) aimed at novel applications in the healthcare, fitness, beacons, security, and home entertainment industries. Compared to Classic Bluetooth, Bluetooth Low Energy is intended to provide considerably reduced power consumption and cost while maintaining a similar communication range.

## Data Types

These are the supported specific data types:

| Name     | Description                      |
|----------|----------------------------------|
| UInt8    | Unsigned Integer 8 bits          |
| UInt16   | Unsigned Integer 16 bits         |
| UInt32   | Unsigned Integer 32 bits         |
| Int8     | Signed Integer 8 bits            |
| Int16    | Signed Integer 16 bits           |
| Int32    | Signed Integer 32 bits           |
| Float    | Floating number                  |
| Double   | Floating double-precision number |
| String   | ASCII value (text string)        |
| Hex      | Hex formatted buffer value       |

Table: BLE specific data types

## Protocol Parameters

The protocol supports the following parameters:

 Name           | Type    | Possible Values             | Default Value    | Description
 -------------- | ------- | --------------------------- | -------------    | ------------------------------
 address        | String  |                             | ""               | Mac address of the BLE device
 id             | String  |                             | ""               | Id of the BLE device
 name           | String  |                             | ""               | Name of the BLE device
 pollInterval   | Integer |                             | 2000             | Time between variable polling when no change value notification is available. Only used in events. (milliseconds)
 bleMode        | Enum    | DirectConnection<br>Listener| DirectConnection | BLE Communication Mode
 byteOrder      | Enum    | BigEndian<br>LittleEndian   | BigEndian        | Byte order of the data of the device
 usbDeviceIndex | Integer |                             | 0                | Index of the BLE usb device

Table: BLE specific parameters

**Note**: If setting more than one device identifier (address, id, name), all of them must match the device properties.

## Extended Parameters

### Property

Name      | Type | Possible Values                      | Default Value |  Description
--------- | ---- | ------------------------------------ | ------------- | ------------------
byteOrder | Enum | Default<br>BigEndian<br>LittleEndian | Default       | Byte order of the data of the device. Use `Default` to use the same setting as defined in the EquipmentSetup Task

### Event Property

Name      | Type    | Possible Values | Default Value |  Description
--------- | ------- | --------------- | ------------- | -----------------------------------------
isTrigger | Boolean |                 | True          | Trigger the event when the value changes  

## Remarks/Behavior

* When an event has more than one property with the `isTrigger` flag:
    * It will be triggered every time any of the properties value changes.
    * The value of the other properties will be requested at that time.
    * It is possible to have multiple triggers with the same set values (because they have not changed). If this behavior is not intended, separate into multiple events each one with its own trigger set.
* When an event has no property with the isTrigger flag, it will **never** be triggered

## Requirements

### Windows

```sh
npm install --global --production windows-build-tools
```

* [Compatible Bluetooth 4.0 USB adapter](https://github.com/sandeepmistry/node-bluetooth-hci-socket#compatible-bluetooth-40-usb-adapters)
* [WinUSB](https://msdn.microsoft.com/en-ca/library/windows/hardware/ff540196.aspx) driver setup for Bluetooth 4.0 USB adapter, using [Zadig tool](https://zadig.akeo.ie/)

1. Insert USB BT dongle
2. Run Zadig from <https://zadig.akeo.ie/>
3. Press Options | List All Devices
4. Select device from dropdown (i.e. CSR8510 A10)
5. Press "Update Driver"

### Ubuntu/Debian/Raspbian

```sh
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
```

### Fedora / Other-RPM based

```sh
sudo yum install bluez bluez-libs bluez-libs-devel
```

## Known issues

* When running in a Windows environment, the BLE stack from Microsoft cannot be used due to limitations and bugs identified but not addressed by Microsoft itself. To bypass this limitation, the communication driver must rely on a raw USB access (using WinUSB) with the BLE adapter.
* USB raw access is only allowed for one process per device. This means only one peripheral can be controlled per BLE adapter.