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.

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:

• Read a value from a data item
• Write a value to a data item
• Receive data or status change report about a data item (notification/indication)

Information about a node

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

• nearby nodes
• what services a node has
• what data items belong to a service
• whether a data item is readable, writable or report-capable (properties)

Information gathering

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

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:

• Process advertisement data (of special format called beacon) without connecting to the node
• Connect to a node,
  • Gather list of services and items (characteristics),
  • Read or write data, and/or
  • Request data/status change report (notification/indication)

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.

• query functions
• data access functions
• setup functions (optional)

Request parameters

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

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

• Full 128-bit UUID, such as "9ff94af7-2ef2-42ab-8bae-e018b82453b5". Any UUID can be used as a service or characteristic (item) identifier.
• short 16-bit abbreviation form of a Bluetooth standard UUID called base UUID. "XXXX" stands for "0000XXXX-0000-1000-8000-00805f9b34fb". For example, "2a19" means "00002a19-0000-1000-8000-00805f9b34fb".
• 32-bit abbreviation form of the Bluetooth standard UUID. "XXXXXXXX" stands for "XXXXXXXX-0000-1000-8000-00805f9b34fb". Not rarely used.

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.

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:

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.

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:

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.

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
• ~string
• .length.integer

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.

~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:

• ~@ABC = "@ABC"
• ~ascii = "ascii"

.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:

• .4.1

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

Example:

• .1.1 = [ 0x01 ]
• .1.-1 = [ 0xff ]
• .1.255 = [ 0xff ]
• .2.1 = [0x01, 0x00 ]
• .2.-1 = [0xff, 0xff ]
• .2.65535 = [0xff, 0xff ]
• .4.1 = [ 0x01, 0x00, 0x00, 0x00 ]
• .4.-1 = [ 0xff, 0xff, 0xff, 0xff ]
• .4.4294967295 = [ 0xff, 0xff, 0xff, 0xff ]

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'.

Setup API

The table below summarizes setup or control functions.

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)