Latest Version: 2.0.0
This library provides a foundation for activating end-user devices via Bluetooth LE on imp modules that support this wireless technology (currently imp004m and imp006 only) using BlinkUp™.
The BTLEBlinkUp library is intended for Electric Imp customers only. It contains device-side Squirrel code which enables BlinkUp™ device activation using enrollment and WiFi credentials transmitted by a companion app running on a mobile device. The companion app must contain the Electric Imp BlinkUp SDK, use of which is authorized by API key. Only Electric Imp customers can be provided with a suitable BlinkUp API key. Code for the companion app is not part of this library, but iOS example code is available separately.
You can view the library’s source code on GitHub. Click here to see information on other versions of this library.
To include this library in your project, add #require "bt_firmware.lib.nut:1.0.0" and #require "btleblinkup.device.lib.nut:2.0.0" at the top of your device code.
Please see the repo BluetoothBlinkUp for working iOS and Squirrel application code which makes use of this library.
In order to support BlinkUp for device activation, the production application code which makes use of this library must be running when the device is first powered up by an end-user. To ensure this happens, you must have your Connected Factory configured so that newly assembled devices receive their application after blessing (this is the default) and not after they are activated. This is a setting of the Production Device Group to which you have set your devices to be assigned upon blessing.
Please see How To Implement The Connected Factory Process for more information.
Note Until a device has been activated, it has no agent. While the library can make use of a device’s agent in order that the agent URL can be sent to the BlinkUp mobile app, your code will need to gather this information after activation.
This library requires the separate library Bluetooth Firmware:
#require "bt_firmware.lib.nut:1.0.0"
#require "btleblinkup.device.lib.nut:2.0.0"
One of the firmware versions included in Bluetooth Firmware should then be included in your BTLEBlinkUp instantiation call:
// For imp004m
local bt = BTLEBlinkUp(serviceUUIDs, BT_FIRMWARE.CYW_43438);
// For imp006
local bt = BTLEBlinkUp(serviceUUIDs, BT_FIRMWARE.CYW_43455);
| Parameter | Type | Required? | Description |
|---|---|---|---|
| uuids | Array of strings | Yes | Specify your application’s UUIDs for the BlinkUp service delivered by the library. See BLE Service UUIDs, below |
| firmware | String or blob | Yes | The required Bluetooth firmware for your device. See Dependencies, above |
| lpoPin | imp pin object | No | The imp GPIO pin connected to the Bluetooth LE radio’s LPO_IN pin. Default: hardware.pinE |
| regonPin | imp pin object | No | The imp GPIO pin connected to the Bluetooth LE radio’s BT_REG_ON pin. Default: hardware.pinJ |
| uart | imp uart object | No | The imp UART on which the imp’s Bluetooth radio is connected. Default: hardware.uartFGJH |
Note The last three parameters are required only on the imp004m. imp006-based applications should not supply arguments to these parameters; indeed, they will be ignored if you do.
The constructor's uuids parameter is used to set UUIDs for the BlinkUp services delivered by the library. The UUIDs are supplied as a table which must contain the following keys:
| Key | UUID Role |
|---|---|
| blinkup_service_uuid | The BlinkUp service itself |
| ssid_setter_uuid | The BlinkUp service’s WiFi SSID setter characteristic |
| password_setter_uuid | The BlinkUp service’s WiFi password setter characteristic |
| planid_setter_uuid | The BlinkUp service’s Plan ID setter characteristic |
| token_setter_uuid | The BlinkUp service’s Enrolment Token setter characteristic |
| blinkup_trigger_uuid | The BlinkUp service’s BlinkUp initiation characteristic |
| wifi_getter_uuid | The BlinkUp service’s WiFi network list characteristic |
| wifi_clear_trigger_uuid | The BlinkUp service’s clear imp WiFi settings characteristic |
You must provide UUIDs for all of these keys or BlinkUp will fail and a runtime error with be thrown. Electric Imp reserves the right to add additional keys in future, so you should not extend this list yourself. If you wish your imp-enabled device to serve other GATT services alongside the BlinkUp service, this can be done using the serve() function detailed below.
The value of each key is a string.
Note The Bluetooth instance established by the constructor can be accessed by the host Squirrel using the instance’s ble property. You should always check that this instance is not null before performing any actions upon it.
This method provides the easiest way to provide BlinkUp via Bluetooth LE. It boots up the imp’s Bluetooth LE radio; sets up and serves two GATT services: BlinkUp and the standard Device Information service; prepares the imp to receive connections from the mobile app being used to provide the imp with activation data; and advertises the imp’s availability to other Bluetooth LE devices.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| advert | String or blob | No | The imp’s Bluetooth LE advertisement payload, up to 31 bytes in length. If you do not specify a payload, the library generates one for you using the BlinkUp service UUID (default or supplied) and the type of imp module as a device name string (eg. imp004m) |
| callback | Function | No | A function which will be triggered when a remote device connects to the imp, or actively disconnects from it |
The callback function has a single parameter of its own into which a table is passed containing any of the following keys:
| Key | Type | Notes |
|---|---|---|
| conn | imp API BluetoothConnection instance | See hardware.bluetooth.onconnect() |
| address | String | The hexadecimal address of the connecting device |
| security | Integer | The security mode of the connection (1, 3 or 4) |
| state | String | The state of the remote device: "connected" or "disconnected" |
| error | String | In the event of an error, a description of the error; otherwise null |
Nothing.
local bt = BTLEBlinkUp();
bt.listenForBlinkUp(null, function(data) {
server.log("Device " + data.address + " has " + data.state);
});
This method allows you to inform the instance of the URL of host device's agent. You can also set this directly via the object property agentURL. If set, the agent URL will be included in the device information service provided by the instance.
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | Integer | No | The URL of the device's agent (Default: "") |
String — the agent URL applied.
local bt = BTLEBlinkUp();
// Register a handler to receive the agent URL from the agent
agent.on("set.agent.url", function(url) {
// Set the agentURL property and configure BLE
bt.setAgentURL(url);
configureBLEBlinkUp();
}.bindenv(this));
// Ask the agent for its URL
// Agent simply returns its URL as a string
agent.send("get.agent.url", true);
This method applies the required security mode: 1, 3 or 4. For more information, please see hardware.bluetooth.setsecurity(). If any errors are encountered, eg. an incorrect security mode has been requested, the method will report the fact and set the security level to the default: no security. For this mode, no value need be passed into pin, but modes 3 and 4 both require the provision of a six-digit decimal PIN code for pairing. This can be a string or an integer.
| Parameter | Type | Required | Description |
|---|---|---|---|
| mode | Integer | No | The required BLE security mode (Default: 1) |
| pin | Integer or string | No | The six-digit PIN code (Required for modes 3 and 4) |
Integer — the security mode applied.
local advert = "\x11\x07\x19\xD7\x68\xF3\x7C\xAF\xF2\xA5\xC9\x48\x55\xC4\xBE\x47\xDA\xFA\x0A\x09\x69\x6D\x70\x30\x30\x34\x2D\x42\x42";
local bt = BTLEBlinkUp();
bt.setSecurity(4, "163524");
bt.listenForBlinkUp(advert, function(data) {
server.log("Device " + data.address + " has " + data.state);
});
This method sets up and begins serving BlinkUp and standard Device Information GATT services. The BlinkUp service uses the UUIDs supplied to the class constructor (or the defaults, if no UUIDs were specified). The latter uses the following UUIDs, as per the Bluetooth LE standard:
service = { "uuid": 0x180A,
"chars": [
{ "uuid": 0x2A29, "value": "Electric Imp" }, // Manufacturer name
{ "uuid": 0x2A25, "value": hardware.getdeviceid() }, // Serial number
{ "uuid": 0x2A24, "value": imp.info().type }, // Model number
{ "uuid": 0x2A26, "value": imp.getsoftwareversion() } // Firmware revision
] };
Note serve() is called implicitly by listenForBlinkUp().
| Parameter | Type | Required | Description |
|---|---|---|---|
| otherServices | Array of tables | No | An array of service definition tables (or a single such service as a table) as detailed here. These are loaded and served alongside the two services mentioned above |
Nothing.
// Add Battery Level service
local bls = { "uuid": 0x180F,
"chars": [
{ "uuid": 0x2A19,
"read": function(conn) {
local b = blob(1);
local battery_percent = hardware.vbat() / 4.2 * 100;
b.writen(battery_percent, 'b');
return b;
}.bindenv(this) }
] };
bt.serve(bls);
This method advertises the imp to other Bluetooth LE-enabled devices using the argument passed into advert, or a self-generated advert based on the BlinkUp service UUID and the host imp’s type as its name, if advert is null. The parameters min and max are also optional, and default to 100 (milliseconds; the minimum and maximum advertising interval).
Note advertise() is called implicitly by listenForBlinkUp().
| Parameter | Type | Required | Description |
|---|---|---|---|
| advert | String | No | The imp’s Bluetooth LE advertisement payload, up to 31 bytes in length. If you do not specify a payload, the library generates one for you using the BlinkUp service UUID (default or supplied) and the type of imp module as a device name string (eg. imp004m) |
| min | Integer | No | The minimum advertising interval in ms (Default: 100) |
| max | Integer | No | The maximum advertising interval in ms (Default: 100) |
Nothing.
local advert = "\x11\x07\x19\xD7\x68\xF3\x7C\xAF\xF2\xA5\xC9\x48\x55\xC4\xBE\x47\xDA\xFA\x08\x09\x69\x6D\x70\x30\x30\x34\x6D";
bt = BTLEBlinkUp();
bt.setSecurity(1);
bt.serve();
bt.advertise(advert, 90, 110);
server.log("Bluetooth running...");
This method registers a callback function that will be triggered when a remote device connects to the imp, or manually disconnects from it.
Note onConnect() is called implicitly by listenForBlinkUp().
| Parameter | Type | Required | Description |
|---|---|---|---|
| callback | Function | No | A function which will be triggered when a remote device connects to the imp, or actively disconnects from it |
The callback function has a single parameter of its own into which a table is passed containing any of the following keys:
| Key | Type | Notes |
|---|---|---|
| conn | imp API BluetoothConnection instance | See hardware.bluetooth.onconnect() |
| address | String | The hexadecimal address of the connecting device |
| security | Integer | The security mode of the connection (1, 3 or 4) |
| state | String | The state of the remote device: "connected" or "disconnected" |
| error | String | In the event of an error, a description of the error; otherwise null |
Nothing.
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.0 | GitHub | Initial release |
| 2.0.0 | GitHub | Add imp006 support |
This library is licensed under the terms and conditions of the MIT License.