Netrunr MQTT API

1. Introduction

MQTT is a messaging system for exchanging information between programs. MQTT is described in the MQTT specification.

Netrunr uses MQTT to provide fast and secure communications between Netrunr clients (programs that wish to access or control a Netrunr gateway) and Netrunr gateway servers.

This document describes the specific MQTT configuration and message formats used by the Netrunr MQTT API. The Netrunr MQTT API is also referred to as the Netrunr Gateway Application Interface (Netrunr GAPI or GAPI), especially when packaged as an SDK for access by different programming languages and libraries.

2. Overview

There are several aspects of the Netrunr MQTT API:

2.1 Netrunr Configuration

Netrunr must be setup and configured to access an MQTT server that will also support access by a Netrunr MQTT API client.

For Netrunr Configuration details, see Netrunr Configuration.

2.2 Netrunr Client MQTT Configuration

Netrunr clients may define the following standard MQTT configuration options:

The MQTT server name, port, and client id are typically specified by the MQTT server, while the topics used by the MQTT client program (or library) must be the same as those configured into a Netrunr gateway, as explained later.

The MQTT server name may be a host name or IP address.

The MQTT port is an integer; for example 1883 (default non-TLS port), 8883 (default TLS port).

The MQTT client id is a string unique to each client.

If the MQTT server supports TLS, then the client program (or library) may use TLS..

The MQTT server may requires client authentication, either using a client username and password or a TLS client certificate and private key file.

2.3 Netrunr Client MQTT Message Data Format

MQTT transfers messages as UTF-8 encoded strings.

Netrunr builds on this, transfering messages packaged as JSON using UTF-8 encoded strings.

JSON is used to represent all Netrunr GAPI information, including commands, command responses, reports, and status/events.

In order to transport binary data over JSON, certain data values are encoded. These include:

The encoding format used is hexadecimal ("hex-ASCII"). In hex-ASCII, two printable characters (each having a value in the range of 0-9 or A-F) are used to represent one byte of binary data.

For multi-byte values, byte order is important. Consistent with the Bluetooth Specification, multi-byte values are transferred in little-endian format. For example, a UUID value of 0x1800 is represented in little-endian format as 2 octets (0x00 and 0x18) which are hex-ASCII encoded into the character string '0018'. An exception to this rule are handles, which are represented in big-endian format.

2.4 Netrunr Client MQTT Operation

Netrunr clients may publish and subscribe to several message topics to communicate with Netrunr.

Multiple message topics are used to reduce MQTT "echo" messages, and to allow programs to monitor different kinds of activity separately.

Although the Netrunr Client MQTT API is fully asynchronous, it has a transaction-like (request/response) aspect as well. This has several implications:

These restrictions are necessary to simplify pipelining operation and error recovery in Netrunr client programs. The client only needs to track the state of one Global command and one Connection-oriented command per connected device. If a client sends multiple commands without awaiting a command response, the gateway will respond with a result set to an error value (see Netrunr GAPI Response Results).

Further details of client operation are described below.

3. Operation

3.1 Netrunr Client MQTT Configuration

MQTT client configuration information is provided to the MQTT client library or program used to implement the MQTT client as previously outlined.

Netrunr clients use the following standard MQTT configuration information:

Netrunr clients may use the following topics:

The names used to specify Netrunr topics must be identical to those those configured into a Netrunr gateway. If more than one gateway is used, it may be convenient to use a combination of the name of the gateway and type of topic to uniquely define each Netrunr gateway and each topic (e.g. 'data in'='NRxyz/1', 'data out'='NRxyz/2', ... where 'NRxyz' is a name unique to each Netrunr, and the values of '/N' are used to represent each topic.

If the MQTT server supports TLS, then the client program (or library) may also support TLS.

If the MQTT server requires client authentication with a client username and password, the client program (or library) must specify these values. If these values are not specified, the MQTT server may disconnect the client, or (worse) not respond to client messages to a Netrunr or transfer Netrunr messages to a client.

If the MQTT server requires client authentication (and usually TLS encryption) with a TLS client certificate and private key file, it may be necessary to generate these files differently depending on the MQTT server used. MQTT server documentation should describe this process.

3.2 Netrunr Commands

Netrunr clients request Netrunr gateways to perform functions by sending commands (or requests). Netrunr gateways respond to requests by sending Netrunr responses. Gateways may also send additional information (known as reports and/or events) depending on the specific client request.

For example, a client request for Netrunr version information would be followed by a Netrunr response containing the version details. In this case, no additional reports or events are used.

A Netrunr client request to scan for Bluetooth Low Energy devices is followed by a Netrunr response, acknowledging the request and then later by 0 or more Advertising Reports indicating specific devices found and by an end-of-scan event indicating that the scan has completed. The Netrunr response is typically sent immediately after the client request is received, but the reports and/or events may be sent much later. A Netrunr client should be prepared to receive reports and events at any time.

Specific Netrunr commands (requests) are described below.

Note: although commands, reports, and events are transfered in JSON format (without internal spaces), they are described here using an expanded JavaScript-like notation to improve readability. In this notation, braces ({ and }) delimit objects, brackets ([[ and ] delimit arrays) and quotes (") delimit strings.

3.2.1 Global commands

Get Netrunr Version Information

Get Netrunr system and software version information.

Request format:

{  
  "c":             56  
}  

Response format:

{  
  "result":        <result>,
  "version":       <version; software version>,
  "system":        <system; system version>
}

result is defined in Netrunr GAPI Response Results.

Advertise

These commands configure and control periodically transmitted advertisments.

Command: Set Advertising Parameters

Advertising parameters cannot be changed unless Advertising is disabled.

Request format:

{
  "c":             59,
  "op":            1,
  "enable":        0,
  "channels":      <channels; 1 (channel 37), 2 (channel 38), 4 (channel 39); default: 0 (all channels)>,
  "interval":      <interval (in 0.625 msec increments), range: 160 - 16384>,
  "type":          <type; 2 (scannable undirected, 3 (non-connectable undirected)>,
  "period":        <period (in msec); advertising rotation period, if multiple advertisements, >= 100>
}

Response format:

{
  "c":             59,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>
}

result is defined in Netrunr GAPI Response Results.

subcode is defined in Netrunr GAPI Response Subcodes.

Command: Set Advertising Data

Advertising data may be changed at any time.

Request format:

{
  "c":             59,
  "op":            2,
  "ad":            <advertising data (encoded string(s))>,
  "sd":            <(optional) scan data (encoded string(s))>,
}

ad and sd are hex-ASCII encoded strings, prefixed by a hex-ASCII encoded length. The length (before hex-ASCII encoding) is the length of the original string (also before hex-ASCII encoding).

If more than one advertisement data and scan data string are defined within ad and sd, advertisements will be rotated, according to the rotation period (period). In this case, each data string will be preceded by a length field.

Response format:

{
  "c":             59,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>
}
Command: Enable Advertising

Enable transmission of advertisement data.

Request format:

{
  "c":             59,
  "op":            4,
  "enable":        1
}

Response format:

{
  "c":             59,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>
}
Disable Advertising

Disable transmission of advertisement data.

Request format:

{
  "c":             59,
  "op":            4,
  "enable":        0
}

Response format:

{
  "c":             59,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>
}
Scan

Scan for Bluetooth Low Energy devices.

A response will be sent as soon as the command is processed.

Reports will be sent to the client when Advertisements are received by the gateway (see Netrunr Reports).

An event will be sent to the client when a scan has completed (see Netrunr Events).

If hardware filtering is enabled, duplicate Advertising reports within a scan period will not be sent. If hardware filtering is disabled, duplicate Advertising reports within a scan period will be sent. This may result in a large amount of data during a scan.

Two types of scan operation requests are supported: passive scan and active scan.

Passive scan request.

Request format:

{
  "c":             0,
  "passive":       1,
  "period":        <scan period (in seconds); 0 (disable scan)>,
  "filter":        <hardware filter; 1 (enable filter), 2 (disable filter)>
}

Response format:

{
  "c":             0,
  "result":        <result>,
  "subcode":       <subcode>
}

Active scan request.

Request format:

{
 "c":              1,
 "active":         1,
 "period":         <scan period (in seconds); 0 (disable scan)>,
 "filter":         <hardware filter; 1 (enable filter), 2 (disable filter)>
}

Response format:

{
  "c":             0,
  "result":        <result>,
  "subcode":       <subcode>
}
Show Connections

Check if a device is connected, or get a list of all existing device connections.

Check if a device is connected.

Request format:

{
  "c":             3,
  "node":          <device id (address)>
}

Response format:

{
  "c":             3,
  "m":             0,
  "result":        <result>,
  "node":          <device id (address)>
  "nodes":         <device list; array of Connected Device Objects>
}

Connected Device Object format:

{
  "did":           <device id (address)>
  "rssi":          <received signal strength indicator (dBm); -127 to 20>
}

Get a list of all existing device connections.

Request format:

{
  "c":             2,
  "enable":        1
}

Response format:

{
  "c":             2,
  "m":             0,
  "result":        <result>,
  "nodes":         <device list; array of Connected Device Objects>
}

Connected Device Object format:

{
  "did":           <device id (address)>
  "rssi":          <received signal strength indicator (dBm); -127 to 20>
}
Connect

Connect to a device.

Request format:

{
  "c":             4,
  "node":          <device id (address)>,
  "dtype":         <device type; 0 (public), 1, (random)>,
  "interval_min":  <minimum connection interval (in 1.25 msec increments): 6 to 3200>,
  "interval_max":  <maximum connection interval (in 1.25 msec increments): 6 to 3200>,
  "latency":       <connection latency: 0 to 6>,
  "timeout":       <connection timeout (in 10msec increment): 10 to 320>,
  "wait":          <connection establishment wait time (in sec): 0 to 15>
}

Response format:

{
  "c":             4,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}
Disconnect

Disconnect device(s).

Request format:

{
  "c":             5,
  "node":          <device id (address); `null` to disconnect all devices>
}

Response format:

{
  "c":             5,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>
}

3.2.2 Connection-oriented commands

Pair Device

Pair, unpair, or list devices paired with a gateway.

Request format:

{
  "c":             41,
  "node":          <device id (address)>,
  "op":            <0 (unpair), 1 (pair), 2 (list pairs), 3 (key)>,
  "iocap":         <device I/O capabilities, range: 0 - 4>,
  "oob":           <1 (out-of-band mode), 0 (not out-of-band)>,
  "auth":          <(sc<<3) | (mitm<<2) | bonding>
  "key_max":       <maximum key length, range: 7 - 16>,
  "key_value":     <key; string (hexified binary array), length: 0 - 32>,
  "key_length":    <key length (of unhexified binary array), length: 0 - 16>,
  "init":          <initiator keys distributed, length: 0 - 7>,
  "resp":          <responder keys distributed, length: 0 - 7>
}

auth specifies zero or more of the following security properties:

sc      - 1<<3 (LE Secure Connection)
mitm    - 1<<2 (Man-in-the-middle (MITM) protection)
bonding - 0 (no bonding), 1 (bonding) 

Response format:

{
  "c":             41,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
}
Discover GATT Services

Discover all primary GATT Services of a device.

Request format:

{
  "c":             9,
  "node":          <device id (address)>,
  "primary"        1
}

Response format:

{
  "c":             9,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "services":      <Services array>
}

The Services array contains objects of format:

{
  "end":           <Service end handle>
  "handle":        <Service start handle>
  "uuid":          <Service UUID>
  "primary":       <primary Service>
}

Discover primary GATT Services of a device by Service UUID.

Request format:

{
  "c":             11,
  "node":          <device id (address)>,
  "uuid":          <GATT Service UUID>,
  "primary"        1
}

Response format:

{
  "c":             11,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "services":      <Services array>
}

The Services array contains objects of format:

{
  "end":           <Service end handle>,
  "handle":        <Service start handle>,
  "uuid":          <Service UUID>,
  "primary":       <primary Service>
}

Note: GATT Services should always be Discovered before Characteristics or Descriptors to insure that GATT Service information is cached.

Discover GATT Characteristics

Discover GATT Characteristics of a device.

Request format:

{
  "c":             14,
  "node":          <device id (address)>,
  "sh":            <Service start handle>,
  "eh":            <Service end handle>,
  "uuid":          <UUID; Characteristic UUID, or UUID of Characteristic ('2803' -> '0328') for all Characteristics>
}

Response format:

 {
   "c":            14,
   "m":            0,
   "result":       <result>,
   "subcode":      <subcode>,
   "node":         <device id (address)>,
   "characteristics": <Characteristics array>
}

The Characteristics array contains objects of format:

{
  "properties":    <Characteristic properties>,
  "handle":        <Characterisitc start handle>,
  "end":           <Characteristic end handle>,
  "uuid":          <Characteristic UUID>
}

Note: GATT Services should always be Discovered before Characteristics or Descriptors to insure that GATT Service information is cached.

Discover GATT Descriptors

Discover all Characteristic Descriptors (all Descriptors for a Characteristic).

Request format:

{
  "c":             32,
  "node":          <device id (address)>,
  "sh":            <Characteristic start handle>,
  "eh":            <Characteristic end handle>,
}

Response format:

 {
   "c":            32,
   "m":            0,
   "result":       <result>,
   "subcode":      <subcode>,
   "node":         <device id (address)>,
   "characteristics": <Descriptors array>
}

The Descriptors array contains objects of format:

{
  "handle":        <Descriptor handle>,
  "uuid":          <Descriptor UUID>
}

Note: GATT Characteristics should always be Discovered before Descriptors to insure that GATT Characteristic information is cached.

Discover a specified Characteristic Descriptor(s).

Request format:

{
  "c":             33,
  "node":          <device id (address)>,
  "sh":            <Characteristic start handle>,
  "eh":            <Characteristic end handle>,
  "uuid":          <Descriptor UUID>
}

Response format:

 {
   "c":            33,
   "m":            0,
   "result":       <result>,
   "subcode":      <subcode>,
   "node":         <device id (address)>,
   "characteristics": <Descriptors array>
}

The Descriptors array contains objects of format:

{
  "handle":        <Descriptor handle>,
  "uuid":          <Descriptor UUID>
}

Note: GATT Characteristics should always be Discovered before Descriptors to insure that GATT Characteristic information is cached.

Subscribe

Two sets of commands are used to allow Indications and Notifications.

The first set of commands Subscribes to Indications or Notifications from a specified device and GATT Characteristic.

The second set of commands enables Indication or Notification reports to be sent from Netrunr. This allows control of (wanted or unwanted) Netrunr event messages without affecting the Indication or Notification Subscribe state within the GATT Descriptor of a GATT Characteristic in a device.

Subscribe to Indications from a device.

Request format:

{
  "c":             16
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "indicate":      1
}

Response format:

{
  "c":             16,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

Subscribe to Notifications from a device.

Request format:

{
  "c":             18
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "notify":        1
}

Response format:

{
  "c":             18,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

Enable Indication reports from Netrunr for a device.

Request format:

{
  "c":             26,
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "indicate":      1,
  "event":         1
}

Response format:

{
  "c":             26,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

Enable Notification reports from Netrunr for a device.

Request format:

{
  "c":             27,
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "notify":        1,
  "event":         1
}

Response format:

{
  "c":             27,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}
Unsubscribe

Two sets of commands are used to disallow Indications and Notifications.

The first set of commands Unsubscribes to Indications or Notifications from a specified device and GATT Characteristic.

The second set of commands disables Indication or Notification reports being sent from Netrunr. This allows control of (wanted or unwanted) Netrunr event messages without affecting the Indication or Notification Subscribe state within the GATT Descriptor of a GATT Characteristic in a device.

Unsubscribe from Indications from a device.

Request format:

{
  "c":             17
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
}

Response format:

{
  "c":             17,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

Unsubscribe from Notifications from a device.

Request format:

{
  "c":             19
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
}

Response format:

{
  "c":             19,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

Disable Indication reports from Netrunr for a device.

Request format:

{
  "c":             26,
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "indicate":      1,
  "event":         0
}

Response format:

{
  "c":             26,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

Disable Notification reports from Netrunr for a device.

Request format:

{
  "c":             27,
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "notify":        1,
  "event":         0
}

Response format:

{
  "c":             27,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}
Read GATT Characteristic by Handle

Read a GATT Characteristic in a device by handle.

Request format:

{
  "c":            20,
  "node":         <device id (address)>,
  "ch":           <Characteristic handle>
}

Response format:

{
  "c":            20,
  "m":            0,
  "result":       <result>,
  "subcode":      <subcode>,
  "node":         <device id (address)>,
  "handle":       <Attribute handle>,
  "value":        <Attribute value>
}
Read GATT Characteristic by UUID

Read a GATT Characteristic in a device by UUID.

Request format:

{
  "c":            20,
  "node":         <device id (address)>,
  "start":        <Start handle>,
  "end":          <End handle>,
  "uuid":         <Characteristic UUID>
}

Response format:

{
  "c":            20,
  "m":            0,
  "result":       <result>,
  "subcode":      <subcode>,
  "node":         <device id (address)>,
  "handle":       <Attribute handle>,
  "value":        <Attribute value>
}
Read GATT Characteristic Long

Read a long GATT Characteristic in a device.

Request format:

{
  "c":            22,
  "node":         <device id (address)>,
  "ch":           <Characteristic handle>,
  "long":         1
}

Response format:

{
  "c":            22,
  "m":            0,
  "result":       <result>,
  "subcode":      <subcode>,
  "node":         <device id (address)>,
  "handle":       <Attribute handle>,
  "value":        <Attribute value>
}
Write GATT Characteristic

Write a GATT Characteristic in a device.

Request format:

{
  "c":             28,
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "value":         <Characteristic Attribute value>
} 

Response format:

{
  "c":             28,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}
Write GATT Characteristic Long

Write a long GATT Characteristic in a device.

Request format:

{
  "c":             29,
  "node":          <device id (address)>,
  "ch":            <Characteristic handle>,
  "value":         <Characteristic Attribute value>,
  "long":          1
} 

Response format:

{
  "c":             29,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}
Write GATT Characteristic without response

Write a GATT Characteristic in a device without a response.

Request format:

{
  "c":             30,
  "node":          <device id (address)>
  "ch":            <Characteristic handle>,
  "value":         <Characteristic Attribute value>,
  "noresponse":    1
} 

Response format:

{
  "c":             30,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}
Read GATT Descriptor

Read GATT Descriptor.

Request format:

{   
  "c":             34,
  "node":          <device id (address)>,
  "dh":            <Descriptor handle>
}

Response format:

{
  "c":             34,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>,
  "handle":        <Attribute handle>,
  "value":         <Attribute value>
}
Read GATT Descriptor Long

Read a long GATT Descriptor.

Request format:

{   
  "c":             37,
  "node":          <device id (address)>,
  "dh":            <Descriptor handle>,
  "long":          1
}

Response format:

{
  "c":             34,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>,
  "handle":        <Attribute handle>,
  "value":         <Attribute value>
}
Write GATT Descriptor

Request format:

{
  "c":             35,
  "node":          <device id (address)>,
  "dh":            <Descriptor handle>,
  "value":         <Descriptor Attribute value>
} 

Response format:

{
  "c":             35,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}
Write GATT Descriptor Long

Request format:

{
  "c":             36,
  "node":          <device id (address)>,
  "dh":            <Descriptor handle>,
  "value":         <Descriptor Attribute value>,
  "long":          1
} 

Response format:

{
  "c":             36,
  "m":             0,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

3.3 Netrunr Reports

Reports are sent to the client to indicate repeating or periodic data, such as scan Advertising Reports or GATT Notifications.

Advertising Report

Advertising report format:

{
  "nodes": [{
    "did":         <device id (address)>,
    "ev":          <advertising event type>,
    "dtype":       <device type (0, public; 1, random)>,
    "adv":         <advertising data>,
    "rsp":         <scan response data>,
    "rssi":        <RSSI>,
    "tss":         <timestamp of scan result (sec)>,
    "tsus":        <timestamp of scan result (usec)>
  }]
}

The Advertising event type is one of the following:

0, Connectable undirected advertising
1, Connectable directed advertising
2, Scannable undirected advertising
3, Non connectable undirected advertising
4, Scan response

Advertising data is an array of objects, each object containing a type property (t) and value property (v) as defined in the Bluetooth Generic Access Profile.

Scan response data is an array of objects, each object containing a type property (t) and value property (v) as defined in the Bluetooth Generic Access Profile.

Notification

Notification format:

{
  "notifications": [{
    "handle":      <Characteristic handle>,
    "value":       <Characteristic value>,
    "tss":         <timestamp (sec)>,
    "tsus":        <timestamp (usec)>
  }]
}

The Characteristic handle and Characteristic value are hex-ASCII encoded.

3.4 Netrunr Events

Events are sent to the client to indicate status or error conditions.

Event format:

{ 
  "result":        <result>,
  "subcode":       <subcode>,
  "event":         <event type>,
  "node":          <device id (if any)>
}

Appendix

Netrunr GAPI Command Codes

GAPI_GAP_PASSIVE =                        0;
GAPI_GAP_ACTIVE =                         1;
GAPI_GAP_ISENABLED =                      2;
GAPI_GAP_NODE =                           3;
GAPI_GAP_CONNECT =                        4;
GAPI_GAP_ENABLE =                         5;
GAPI_GAP_NAME =                           6;
GAPI_GATT_NODES =                         7;
GAPI_GATT_NODES_NODE =                    8;
GAPI_GATT_SERVICES =                      9;
GAPI_GATT_SERVICES_PRIMARY =              10;
GAPI_GATT_SERVICES_PRIMARY_UUID =         11;
GAPI_GATT_SERVICES_SERVICE =              12;
GAPI_GATT_SERVICE_CHARS =                 13;
GAPI_GATT_CHARS_UUID =                    14;
GAPI_GATT_CHARS_CHAR =                    15;
GAPI_GATT_CHARS_CHAR_INDICATE_ON =        16;
GAPI_GATT_CHARS_CHAR_INDICATE_OFF =       17;
GAPI_GATT_CHARS_CHAR_NOTIFY_ON =          18;
GAPI_GATT_CHARS_CHAR_NOTIFY_OFF =         19;
GAPI_GATT_CHARS_CHAR_READ =               20;
GAPI_GATT_CHARS_READ_UUID =               21;
GAPI_GATT_CHARS_CHAR_READ_LONG =          22;
GAPI_GATT_CHARS_READ_MULTIPLE =           23;
GAPI_GATT_CHARS_CHAR_READ_INDICATE =      24;
GAPI_GATT_CHARS_CHAR_READ_NOTIFY =        25;
GAPI_GATT_CHARS_CHAR_SUBSCRIBE_INDICATE = 26;
GAPI_GATT_CHARS_CHAR_SUBSCRIBE_NOTIFY =   27;
GAPI_GATT_CHARS_CHAR_WRITE =              28;
GAPI_GATT_CHARS_CHAR_WRITE_LONG =         29;
GAPI_GATT_CHARS_CHAR_WRITE_NORESPONSE =   30;
GAPI_GATT_CHARS_CHAR_WRITE_RELIABLE =     31;
GAPI_GATT_CHARS_CHAR_DESCS =              32;
GAPI_GATT_DESCS_DESC =                    33;
GAPI_GATT_DESCS_DESC_READ =               34;
GAPI_GATT_DESCS_DESC_WRITE =              35;
GAPI_GATT_DESCS_DESC_WRITE_LONG =         36;
GAPI_GATT_DESCS_DESC_READ_LONG =          37;
GAPI_RSVD38 =                             38;
GAPI_RSVD39 =                             39;
GAPI_RSVD40 =                             40;
GAPI_PAIR =                               41;
GAPI_RSVD42 =                             42;
GAPI_RSVD43 =                             43;
GAPI_RSVD44 =                             44;
GAPI_RSVD45 =                             45;
GAPI_RSVD46 =                             46;
GAPI_RSVD47 =                             47;
GAPI_RSVD48 =                             48;
GAPI_RSVD49 =                             49;
GAPI_RSVD50 =                             50;
GAPI_RSVD51 =                             51;
GAPI_RSVD52 =                             52;
GAPI_RSVD53 =                             53;
GAPI_RSVD54 =                             54;
/* */
GAPI_NO_COMMAND =                         55;
/* */
GAPI_VERSION =                            56;
GAPI_RSVD57 =                             57;
GAPI_RSVD58 =                             58;
GAPI_ADVERTISE =                          59;
GAPI_RSVD60 =                             60;

Netrunr GAPI Response Results (result)

ERROR_SUCCESS =                          200;
ERROR_BAD_REQUEST =                      400;
ERROR_AUTHENTICATION_ERROR =             401;
ERROR_FORBIDDEN_REQUEST =                403;
ERROR_REQUEST_NOT_FOUND =                404;
ERROR_METHOD_NOT_ALLOWED =               405;
ERROR_PARAMETERS_NOT_ACCEPTABLE =        406;
ERROR_CONFLICT =                         409;
ERROR_REQUEST_PRECONDITION_FAILED =      412;
ERROR_PARAMETER_MISSING =                441;
ERROR_PARAMETER_VALUE_NOT_VALID =        442;
ERROR_UNEXPECTED_INTERNAL_CONDITION =    443;
ERROR_INTERNAL_ERROR =                   500;
ERROR_NO_CONNECTION =                    504;
ERROR_CONNECTION_EXISTS =                505;
ERROR_OUT_OF_RESOURCES =                 507;

Netrunr GAPI Response Subcodes (subcode)

SUBCODE_ERROR_SUCCESS =                    0;
SUBCODE_ERROR_RSVD1 =                     -1;
SUBCODE_ERROR_RSVD2 =                     -2;
SUBCODE_ERROR_INVALID_HANDLE =            -3;
SUBCODE_ERROR_INVALID_CONNECTION_HANDLE = -4;
SUBCODE_ERROR_UNUSED_CONNECTION_HANDLE =  -5;
SUBCODE_ERROR_INVALID_PARAMETER =         -6;
SUBCODE_ERROR_CONNECTION_IN_PROGRESS =    -7;
SUBCODE_ERROR_CONNECTION_TIMEOUT =        -8;
SUBCODE_ERROR_CONNECTION_LIMIT =          -9;
SUBCODE_ERROR_CONNECTION_EXISTS =        -10;
SUBCODE_ERROR_DISCONNECT_IN_PROGRESS =   -11;
SUBCODE_ERROR_NO_DISCOVERED_CONTAINER =  -12;
SUBCODE_ERROR_NO_GATT_ENTITY =           -13;
SUBCODE_ERROR_INVALID_ADDRESS_TYPE =     -14;
SUBCODE_ERROR_NO_ADDRESS =               -15;
SUBCODE_ERROR_INVALID_CALL_STATE =       -16;
SUBCODE_ERROR_INVALID_OPERATION =        -17;
SUBCODE_ERROR_TOO_SMALL =                -18;
SUBCODE_ERROR_TOO_LARGE =                -19;
SUBCODE_ERROR_FLOW_CONTROL =             -20;
SUBCODE_ERROR_COMPUTATION_FAILED =       -21;
SUBCODE_ERROR_AUTHENTICATION =           -22;
SUBCODE_ERROR_ENCRYPTION =               -23;
SUBCODE_ERROR_ATT_TIMEOUT =              -24;
SUBCODE_ERROR_BOND_LOST =                -25;
SUBCODE_ERROR_IO =                       -26;
SUBCODE_ERROR_RESOURCES_EXCEEDED =       -97;
SUBCODE_ERROR_UNKNOWN =                  -98;
SUBCODE_ERROR_HCI_BASE =                 -1024;  /* 256 HCI errors */
SUBCODE_ERROR_HCI_BASE_END =             -(1024 + 256);
SUBCODE_ERROR_GATT_BASE =                -2048;  /* 256 GATT errors */
SUBCODE_ERROR_GATT_BASE_END =            -(2048 + 256);

Netrunr GAPI Response Subcodes - HCI

SUBCODE_ERROR_HCI_UNKNOWN                -1025;
SUBCODE_ERROR_HCI_UNKNOWN_CONNECTION_ID  -1026;
SUBCODE_ERROR_HCI_HARDWARE_ERROR         -1027;
SUBCODE_ERROR_HCI_MISSING_PIN_OR_KEY     -1030;
SUBCODE_ERROR_HCI_OUT_OF_MEMORY          -1031;
SUBCODE_ERROR_HCI_CONNECTION_TIMEOUT     -1032;
SUBCODE_ERROR_HCI_OUT_OF_CONNECTIONS     -1033;
SUBCODE_ERROR_HCI_COMMAND_DISALLOWED     -1036;
SUBCODE_ERROR_HCI_REJECTED_RESOURCES     -1037;
SUBCODE_ERROR_HCI_REJECTED_SECURITY      -1038;
SUBCODE_ERROR_HCI_REJECTED_ADDRESSS      -1039;
SUBCODE_ERROR_HCI_CONNECTION_ACC_TIMEOUT -1040;
SUBCODE_ERROR_HCI_UNSUPPORTED_FEATURE    -1041;
SUBCODE_ERROR_HCI_INVALID_PARAMETER      -1042;
SUBCODE_ERROR_HCI_REMOTE_TERMINATED      -1043;
SUBCODE_ERROR_HCI_REMOTE_RESOURCES       -1044;
SUBCODE_ERROR_HCI_REMOTE_POWER_OFF       -1045;
SUBCODE_ERROR_HCI_LOCAL_TERMINATED       -1046;

Netrunr GAPI Response Subcodes - GATT/ATT

SUBCODE_ERROR_ATT_INVALID_HANDLE         -2049;
SUBCODE_ERROR_ATT_READ_NOT_PERMITTED     -2050;
SUBCODE_ERROR_ATT_WRITE_NOT_PERMITTED    -2051;
SUBCODE_ERROR_ATT_INVALID_PDU            -2052;
SUBCODE_ERROR_ATT_INSUFFICIENT_AUTHEN    -2053;
SUBCODE_ERROR_ATT_REQUEST_NOT_SUPPORTED  -2054;
SUBCODE_ERROR_ATT_INVALID_OFFSET         -2055;
SUBCODE_ERROR_ATT_INSUFFICIENT_AUTHOR    -2056;
SUBCODE_ERROR_ATT_QUEUE_FULL             -2057;
SUBCODE_ERROR_ATT_ATTRIBUTE_NOT_FOUND    -2058;
SUBCODE_ERROR_ATT_ATTRIBUTE_NOT_LONG     -2059;
SUBCODE_ERROR_ATT_INVALID_KEY_SIZE       -2060;
SUBCODE_ERROR_ATT_ATTRIBUTE_VALUE_LENGTH -2061;
SUBCODE_ERROR_ATT_UNLIKELY_ERROR         -2062;
SUBCODE_ERROR_ATT_INSUFFICENT_ENCRYPTION -2063;
SUBCODE_ERROR_ATT_UNSUPPORTED_GROUP_TYPE -2064;
SUBCODE_ERROR_ATT_INSUFFICENT_RESOURCES  -2065;

Netrunr GAPI Events

EVENT_DISCONNECT =                        1;
EVENT_COMMAND_COMPLETE =                  2;
EVENT_COMMAND_STATUS =                    3;
EVENT_HARDWARE_ERROR =                    4;
EVENT_READ_RSSI =                         5;
EVENT_READ_CHANNEL_MAP =                  6;
EVENT_CONNECTION_COMPLETE =               7;
EVENT_ADVERTISING_REPORT =                8;
EVENT_LE_CONNECTION_UPDATE_COMPLETE =     9;
EVENT_LE_CONNECTION_CANCEL =             10;
EVENT_LE_READ_REMOTE_FEATURES_COMPLETE = 11;
EVENT_LE_LTK_REQUEST =                   12;
EVENT_LE_REMOTE_CONNECTION_PARAMETER_REQUEST =  13;
EVENT_LE_DATA_LENGTH_CHANGE =            14;
EVENT_LE_READ_LOCAL_P256_KEY_COMPLETE =  15;
EVENT_LE_GENERATE_DHKEY_COMPLETE =       16;
EVENT_LE_ENHANCED_CONNECTION_COMPLETE =  17;
EVENT_LE_DIRECT_ADVERTISING_REPORT =     18;
/* Encryption change: 
 * subcode: status (>= 0), API error (< 0)
 */
EVENT_ENCRYPT_CHANGE =                    19;
EVENT_ENCRYPTION_KEY_REFRESH_COMPLETE =   20;
/* Security Request
 * subcode: security request: authentication request
 */
EVENT_PAIRING_COMPLETE =                  32;
EVENT_GATT_ERROR =                        33;
EVENT_SECURITY_REQUEST =                  37;
EVENT_REQUEST_ERROR =                     38;
EVENT_SCAN_ENABLE =                       39;
EVENT_TRANSMIT_POWER =                    40;
EVENT_AUTHEN_KEY =                        41;
EVENT_PAIR_REQUEST =                      42;

Netrunr Advertising Event Types

ADV_EVENT_TYPE_CONN_UNDIRECTED =           0;
ADV_EVENT_TYPE_CONN_DIRECTED =             1;
ADV_EVENT_TYPE_SCAN_UNDIRECTED =           2;
ADV_EVENT_TYPE_NONCONN_UNDIRECTED =        3;
ADV_EVENT_TYPE_SCAN_RESPONSE =             4;