Home > ble-for-iot > alt-api

Alternative API for BLE IoT Gateway

A BLE IoT gateway (ble-iot-gwy) provides web access from a PC or mobile to remote Bluetooth Low Energy (BLE) devices over the Internet or nearby BLE devices over a local LAN (wired or wireless).

This document describes an alternative API (ALT-API) to the Bluetooth SIG-proposed GATT REST API (called SIG-API in this document).

The SIG-API exposes BLE-specific device access interface. The ALT-API provides a web interface that maps web-friendly abstract data access to a BLE-specific device access.

Terms and Overview

Terms used in the BLE specifications are not very meaningful to a developer who has not been familiar with Bluetooth technology. Before introducing the API, let me briefly introduce terms used in BLE and the API.

The table below presents major BLE terms and its meanings. The 'In API' column presents corresponding terms used in the API which are more familiar to a developer withou much BLE experience.

In BLE In API Description
peripheral node BLE device that contains data to read or write
central host BLE-capable controller that reads from or writes data to a peripheral
service - named group of characteristics
characteristic data item named piece of data a central can read and/or write
UUID - identifier of a service or characteristic. The UUID length is 128 bits. Standard UUIDs defined or assiged to a third party by Bluetooth SIG can be abbreviated to 16 bits or 32 bits
properties data permissions information about whether a characteristic is readable, writable or report-capable
descriptor data attributes information that controls access to a characteristic
CCCD - a special descriptor that enables or disables notification (or indication)
notification report data change report of a characteristic sent from peripheral to central
indication report notification with receipt response from central

A gateway is a controller or host (central in a BLE term) and talks to a BLE device or node (peripheral) to read and write data items (characteristic). Data items are organized into a data group called service.

Data access

There are three data-oriented operations a gateway can do to a node:

Information about a node

In order to do the data operations, a gateway must collect information about nodes:

Information gathering

There are several preparatory operations with which a host collects information about nodes.

In BLE In API Who does Description
advertise - node Broadcast information about itself such as bluetooth address, connectable or not, manufacturer data, etc.
scan - host Collect advertised data from nearby nodes
connect open host Make a data transfer link with a node
disconnect close host Break a connection. Node can break a connection too.

A BLE node starts advertising when it is powered on or directed by the user. A host starts scanning to collect advertised data of nearby nodes. The host has then several options to do:

A node usually stops advertising when a connection to a host is made. It will resume advertising when the connection is shut down. A host usually stops scanning when a connection to one or more nodes are made. It will resume scanning when no connections remain open. A host or node, however, can choose to keep scanning or advertising while connected if its BLE hardware or software allows to do so.

How a Connection is handled

A connection to a node can be explicitely requested by a web client, or the gateway automatically handle connections as needed.

The gateway may automatically connect to a node if it sees it necessary. A connection has to be made when a list of services and items are requested, reading or writing of a data item is requested, and/or data change report is requested (as described above). It automatically disconnects from the node if the connection is not in use for a long time (some time has passed since the last operation to the node).

Note: A list of data items (characteristics) are only available while connected. A list of services (data groups) are sometimes available through advertisement prior to making a connection. The word 'sometimes' means it is up to a developer of a BLE device whether to provide the data or not. In addition, there is no guarantee the advertized data is correct. The designer of this API chose to get a precise list of services and items after the connection is made.

API

There are three types of API functions.

Request parameters

Common request parameters used in a URL request of all these types of functions are:

Parameter Description Example
node Node (peripheral) is identified by bluetooth device address "c0:ab:2a:6a:1a:89"
service Service (data group) is identified by a UUID "180f" or "9ff94af7-2ef2-42ab-8bae-e018b82453b5"
item Data item (characteristic) is identified by a UUID "2a19" or "9ff94af8-2ef2-42ab-8bae-e018b82453b5"

There are three types of UUIDs used in BLE (Bluetooth Core Spec v4.2, Part B SDP, 2.5.1 UUID)

The API accepts a device address or UUID consisting of either lower or upper case letters, with or without colons (:) or hyphens (-).

URL format

The 'URL' column in API function tables below shows the essential part of a whole URL actually used. The format of an entire URL is 'http://gateway/prefix/nodes' for '/nodes' request. For example, it will be 'http://gateway.example.com/altapiv1/nodes' (or 'https:...').

Response format

Reponses returned by the API functions are in JSON format.

Example (list of services):

[{"uuid":"1800"},{"uuid":"1801"},{"uuid":"180f"}]

Query API

The table below summarizes query or information gathering functions.

Method URL Description
GET /nodes[?connectable] Get a list of all nearby nodes or only connectable nodes if 'connectable=true' is specified
GET /nodes/node/services Get a list of services of a specified node
GET /nodes/node/services/service/items Get a list of data items of a specified service in a specified node

Node information format

A query response for list of nodes is an array of objects containing the following data. Each object describes a single node:

Item Description Example
address bluetooth device address "c0:ab:2a:6a:1a:89"
addressType peripheral.addressType "random" or "public"
connectable true if connectable
localName name of the node (if specified) "NRF51"
serviceUuids array of service uuids (not always available) [ "180f", "9ff94af7-2ef2-42ab-8bae-e018b82453b5" ]
manufacturerData manufacturer data Apple iBeacon data included here
rssi radio strength -45

What kind of advertisement data is available depends on an underlying BLE implementation (not all of data are provided) and a specific BLE device (developer of the devices chooses what information to provide).

Service information format

A query response for list of services (data groups) is an array of objects containing the following data. Each object describes a single service.

Item Description Example
uuid service uuid "180f" or "9ff94af7-2ef2-42ab-8bae-e018b82453b5"

Data item information format

A query response for list of data items (characteristics) is an array of objects containing the following data. Each object describes a single item:

Item Description Example
uuid characteristic uuid "2a19" or "9ff94af8-2ef2-42ab-8bae-e018b82453b5"
properties array of avaialbe data permissions [ "read", "notify" ]

For reference, noble may return the following properties: 'broadcast', 'read', 'writeWithoutResponse', 'write', 'notify', 'indicate', 'authenticatedSignedWrites' and 'extendedProperties'.

Data access API

The table below summarizes data access functions.

Method URL Description
GET /nodes/node/services/service/items/item/value Read a value from a specified data item
PUT /nodes/node/services/service/items/item/value/value[?noresponse=true] Write a value to a specified data item. No acknowledge response will be requested if 'noresponse=true' is specified
GET /nodes/node/services/service/items/item/report Request reporting of data/status changes of a specified item

BLE allows two types of write operations. The difference is whether to request a node to return an acknowledge response indicating success or failure of a write operation.

The 'status report' request is special in that it opens an event stream between a web client and the gateway through which server-sent events are sent from the gateway to the web client.

The BLE status report can be done in one of two ways: indication and notification. The gateway or underlying BLE implementaion will choose whichever is available. In BLE a setup is needed to start and end subscription; a CCCD descriptor of the corresponding characteristic must be modified. The subscription setup is automatically done by the gateway or underlying BLE implementaion.

Request value format

This applies to the last part of the 'write item' request, value. A value to be written to a data item is represented by a single URL component.

A data item value passed to the gateway from a web client should be one of the following formats:

hex

Any value can be expressed as a string of even-numbered hexadecimal characters. The length of the hex string determines the length of the byte string; one byte requires two characters.

Example Length Remark
01000000 four
ab00cd three
AB00CD three in upper-case
40414243 four

~string

The fourth hex string in the example above, '40414243', contains only printable ASCII characters (0x20 to 0x7E). In this case, it can be expressed as an ASCII string by prefixing a tilda (~) character as in:

.length.integer

The third format, called dotted integer format in this API, represents a little-endian integer in decimal format having a specified length, ie. the number of bytes the interger occupies. The length should be one of 1, 2 or 4.

For example '01000000' in the above example can be expressed as:

You can specify either a positive, negative or unsigned value within the range.

Example:

Response value format

This applies to 'read item' and 'status report' responses. The response body is in JSON format.

A data item value returned to the web client takes the following format:

{ len: length, hex: hex, [num: integer,] [str: string] }

The order of the fields may be different than the above. The 'len' and 'hex' fields are always present. The hex value is a string of even-numbered lower-case hexadecimal characters, such as '01000000' or 'ab00cd'. The length is the length of the byte string represented by the hex string; two hex characters show one byte.

The 'num' field will be present if the length of the byte string is one, two or four. Its value will be an integer in little endian order converted from the byte string, such as 1 for '01000000'.

A byte value is treated as an unsigned vlaue while two-byte or four-byte value is treated as signed value.

The 'str' field will be present if all the bytes of the data are within printable ASCII range (0x20 to 0x7E). Its vlaue is the ASCII string such as '@ABC' for '40414243' or 'ABC' for '414243'.

Example Remark
{ hex: "01000000", len: 4, num: 1 } four-byte string seen as an integer
{ hex: "ffffffff", len: 4, num: -1 } seen as a negative integer
{ hex: "40414243", len: 4, num: 1128415552, str: "@ABC" } can also be seen as an ASCII string
{ hex: "414243", len: 3, str: "ABC" } not seen as an integer
{ hex: "ab00cd", len: 3 } seen as just a three-byte string
{ hex: "ff", len: 256 } treated as an unsigned byte
{ hex: "ffff", len: 2, num: -1 } signed
{ hex: "ffffffff", len: 4, num: -1 } signed

Setup API

The table below summarizes setup or control functions.

Method URL Description
POST /wakeup Wake up and start scanning
POST /sleep Stop scanning and enter sleep mode
POST /nodes/node/open Connect to a node if not already yet
POST /nodes/node/close Disconnect from a node

These are hints to the gateway and not necessarily required. However, issuing wakeup and open request several seconds before issuing a query or data access function guarantees a smooth operation. A request to get a list of services or data items (characteristics) without an open request or immediately after an open request may fail because the node information is not ready yet (depending on a specific alt-api implementation).

Even without a wakeup request, the gateway starts scanning when it receives an API function that requires scanning. Even without an open request, the gateway connects to a node when it receives an API that requires a connection to the node.

Even if no sleep or close request is received, the gateway may choose to do so if it does not receive any request from any web client for a long time.

Explicitly issuing close and sleep requests avoids unnecessary network traffic and saves power consumption of the gateway.

BLE defines a white list feature. A target node can be preset to a host and made readily available. Most alt-api implementation will have a configuration feature that a particular node can be connected immediately when found.


Copyright (c) 2019 Kobu.Com. All rights reserved.

Written: 2019-Oct-10
Updated: 2019-Oct-15 (noble/win version)
Updated: 2019-Oct-24 (published)