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:

{  
  "c":             56,
  "m":             <input parameter m; default 0>,
  "result":        <result>,
  "subcode":       0,
  "version":       <version; software version>,
  "build":         <build, software build information>,
  "hardware":      <hardware; hardware information>,
  "system":        <system; system version>,
  "ram":           <ram; RAM information>,
  "hci":           <hci; HCI information>
}

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":             <input parameter m; default 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":             <input parameter m; default 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":             <input parameter m; default 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":             <input parameter m; default 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,
  "period":        <scan period (in seconds); 0 (disable scan)>,
  "filter":        <hardware filter; 1 (enable filter), 2 (disable filter)>
}

Response format:

{
  "c":             0,
  "m":             <input parameter m; default 0>,
  "result":        <result>,
  "subcode":       <subcode>
}

Active scan request.

Request format:

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

Response format:

{
  "c":             0,
  "m":             <input parameter m; default 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":          <(optional) device id (address); default: null (all devices)>
}

Response format:

{
  "c":             3,
  "m":             <input parameter m; default 0>,
  "result":        <result>,
  "node":          <device id (address)>,
  "nodes":         <device list; array of connected device objects>
}

Connected Device Object format:

{
  "node":          <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":             <input parameter m; default 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: ("node": <device id (address)>)

{
  "c":             5,
  "m":             <input parameter m; default 0>,
  "node":          <device id (address)>,
  "nodes":         <list of device ids>,
  "result":        <result>,
  "subcode":       <subcode>
}

Response format: ("node": null)

{
  "c":             5,
  "m":             <input parameter m; default 0>,
  "nodes":         <list of device ids>,
  "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":             <input parameter m; default 0>,
  "node":          <device id (address)>,
  "result":        <result>,
  "subcode":       <subcode>,
}
Discover GATT Services

Discover primary GATT Services of a device.

Request format:

{
  "c":             11,
  "node":          <device id (address)>,
  "uuid":          <(optional) GATT Service UUID; default: null (all Services)>,
}

Response format:

{
  "c":             11,
  "m":             <input parameter m; default 0>,
  "result":        <result>,
  "node":          <device id (address)>
  "subcode":       <subcode>,
  "services":      <Services array>
}

The Services array contains objects of format:

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

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":          <(optional) UUID; Characteristic UUID; default: null (all Characteristics)>
}

Response format:

{
  "c":             14,
  "m":             <input parameter m; default 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 Characteristic Descriptor(s).

Request format:

{
  "c":             33,
  "node":          <device id (address)>,
  "sh":            <Characteristic start handle>,
  "uuid":          <(optional) Descriptor UUID; default: null (all Descriptors)>
}

Response format:

{
  "c":            33,
  "m":             <input parameter m; default 0>,
  "result":       <result>,
  "subcode":      <subcode>,
  "node":         <device id (address)>,
  "descriptors":  <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 enable 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 optionally enables Indication or Notification reports to be sent from Netrunr (default: on). This allows control of (wanted or unwanted) Netrunr event messages without affecting the internal Indication or Notification Subscribe state (i.e. the value within the GATT Client Characteristic Configuration Descriptor for the GATT Characteristic).

Subscribe to Indications from a device.

Request format:

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

Response format:

{
  "c":             16,
  "m":             <input parameter m; default 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>,
}

Response format:

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

Enable Indication reports from Netrunr for a device.

Note: this is an optional command; it is only needed if controlling reports separately from Subscribe/Unsubscribe operations (default: on).

Request format:

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

Response format:

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

Enable Notification reports from Netrunr for a device.

Note: this is an optional command; it is only needed if controlling reports separately from Subscribe/Unsubscribe operations (default: on).

Request format:

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

Response format:

{
  "c":             27,
  "m":             <input parameter m; default 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 optionally 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":             <input parameter m; default 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":             <input parameter m; default 0>,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>
}

Disable Indication reports from Netrunr for a device.

Note: this is an optional command; it is only needed if controlling reports separately from Subscribe/Unsubscribe operations.

Request format:

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

Response format:

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

Disable Notification reports from Netrunr for a device.

Note: this is an optional command; it is only needed if controlling reports separately from Subscribe/Unsubscribe operations.

Request format:

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

Response format:

{
  "c":             27,
  "m":             <input parameter m; default 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":            <input parameter m; default 0>,
  "result":       <result>,
  "subcode":      <subcode>,
  "node":         <device id (address)>,
  "value":        <Attribute value>
}
Read GATT Characteristic by UUID

Read a GATT Characteristic in a device by UUID.

Request format:

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

Response format:

{
  "c":            21,
  "m":            <input parameter m; default 0>,
  "result":       <result>,
  "subcode":      <subcode>,
  "node":         <device id (address)>,
  "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>,
}

Response format:

{
  "c":            22,
  "m":            <input parameter m; default 0>,
  "result":       <result>,
  "subcode":      <subcode>,
  "node":         <device id (address)>,
  "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":             <input parameter m; default 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>,
} 

Response format:

{
  "c":             29,
  "m":             <input parameter m; default 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>,
} 

Response format:

{
  "c":             30,
  "m":             <input parameter m; default 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":             <input parameter m; default 0>,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>,
  "value":         <Attribute value>
}
Read GATT Descriptor Long

Read a long GATT Descriptor.

Request format:

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

Response format:

{
  "c":             37,
  "m":             <input parameter m; default 0>,
  "result":        <result>,
  "subcode":       <subcode>,
  "node":          <device id (address)>,
  "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":             <input parameter m; default 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>,
} 

Response format:

{
  "c":             36,
  "m":             <input parameter m; default 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:

{
  "report":        1,
  "result":        <result>,
  "subcode":       <subcode>,
  "nodes": [{
    "node":        <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

Indication format:

{
  "c":             <26>,
  "node":          <device id (address)>
  "result":        <result>,
  "subcode":       <subcode>,
  "report":        <26>,
  "notifications": [{
    "handle":      <Characteristic handle>,
    "value":       <Characteristic value>,
    "tss":         <timestamp (sec)>,
    "tsus":        <timestamp (usec)>
  }]
}

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

Notification format:

{
  "c":             <27>,
  "node":          <device id (address)>,
  "result":        <result>,
  "subcode":       <subcode>,
  "report":        <27>,
  "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_DEBUG =                              57;
GAPI_UPLOAD =                             58;
GAPI_ADVERTISE =                          59;
GAPI_REBOOT =                             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;