Data formats

GAPI requests and responses are internally formatted as JSON.

In order to transport binary data over JSON, certain property values are encoded.

Advertising data properties, specified as Generic Access Profile types per the Bluetooth® specification, are represented with JSON integers and JSON arrays, as well as UTF-8 strings.

Binary encoding (hex-ASCII representation)

GAPI binary data are generally represented using hexadecimal ("hex-ASCII") strings; a few exceptions are noted below. In hex-ASCII, two printable characters (each having a value in the range 0-9 or A-F) are used to represent one octet of binary data.

Endianness

For multiple octet values, data are transfered octet by octet in little-endian format. For example, a UUID value of 0x1800 will be represented in little-endian format as 2 octets (0x00 and 0x18) which are hex-ASCII encoded into the character string '0018'.

Examples of data passing through GAPI using the hex-string representation are:

  • Device addresses
  • GATT UUIDs
  • Characteristic Values

Exceptions to the hex-string rule are:

  • GATT Attribute handles (big-endian format, but only used as opaque values)

Transport channels

GAPI can run over multiple transports (e.g. HTTPS, MQTTS).

To support routing, GAPI uses a gateway identifier or gwid. Each gwid is unique.

Although not strictly needed to use the GAPI JavaScript SDK, GAPI internally uses a connectivity channel with MQTTS in order to differentiate messages at the transport level. Channels include:
1 - Transaction-in (client-to-gateway)
2 - Transaction-out (gateway-to-client)
3 - Report-in (client-to-gateway)
4 - Report-out (gateway-to-client)
5 - Event-in (client-to-gateway)
6 - Event-out (gateway-to-client)

The data channels are used to transfer GAPI request and response information in a transactional way.

The report channels are used to transfer recurring information (such as scan responses and GATT Notifications).

The event channels are used to transfer unsolicited or other information (such as Security Manager Requests, encryption changes, unexpected device disconnections, low-level protocol command status, and certain types of low-level errors, e.g. hardware error).

Each channel is uni-directional; information may flow independently in either direction.

Generic codes

GAPI uses a set of codes (JSON properties) to indicate information type and status.

These include result, subcode, event, and report.

Result

The JSON result property may have the following values:
200 - success
400 - bad request
401 - authentication error
403 - forbidden request
404 - request not found
405 - method not allowed
406 - parameters not acceptable
408 - request timeout
409 - conflict (e.g. request already in progress)
412 - request precondition failed
441 - parameter missing
442 - parameter value not valid
443 - unexpected internal condition
500 - internal error
504 - no connection
505 - connection exists
507 - out of resources (e.g. memory)

Subcode

The JSON subcode property contains internal system information and may have the following values:
3 - invalid handle
4 - invalid connection handle
5 - unused connection handle
6 - invalid parameter
7 - connection in progress
8 - connection timeout
9 - connection limit exceeded
10 - connection exists
11 - disconnection in progress
12 - no discovered GATT container
13 - no GATT entity
14 - invalid address type
15 - no address
16 - invalid call state
17 - invalid operation
18 - value too small
19 - value too large
20 - flow control error
21 - computation failed
22 - authentication error
23 - encryption error
24 - ATT timeout
25 - pairing bond lost
26 - generic I/O error
97 - resources exceeded
98 - unknown error

256 - internal error
257 - internal timeout

1024 - HCI error min
1025 - unknown HCI command
1026 - unknown connection handle
1027 - hardware failure
1029 - authentication failure (incorrect PIN or key)
1030 - PIN or key missing
1031 - memory capacity exceeded
1032 - connection timeout
1033 - connection limit exceeded
1035 - connection exists
1036 - command disallowed
1037 - connection rejected due to limited resources
1038 - connection rejected due to security reasons
1039 - connection rejected due to unacceptable address
1040 - connection accept timeout exceeded
1041 - unsupported feature or parameter value
1042 - invalid HCI parameter
1043 - remote user terminated connection
1044 - remote device terminate connection due to low resources
1045 - remote device terminated connection due to power off
1046 - connection terminated locally
1047 - repeated attempts failed
1048 - pairing not allowed
1050 - unsupported remote feature
1071 - insufficient security
1083 - unacceptable connection parameters
1280 - HCI error max

2048 - GATT error min
2049 - invalid handle
2050 - read not permitted
2051 - write not permitted
2052 - invalid PDU
2053 - insufficient authentication
2054 - request not supported
2055 - invalid offset
2056 - insufficient authorization
2057 - prepare queue full
2058 - attribute not found
2059 - attribute not long
2060 - insufficient encryption key size
2061 - invalid attribute value length
2062 - unlikely error
2063 - insufficient encryption
2064 - unsupported group type
2065 - insufficient resources
2176 - application error
2304 - GATT error max

Event

The JSON event property specifies an internal system action and may have the following values:
1 - unexpected device disconnect
2 - command complete
3 - command status
4 - hardware error
5 - read rssi
6 - read channel map
7 - connection complete
8 - advertising report
9 - connection update complete
10 - connection cancellation
11 - read remote features complete
12 - LTK request
13 - remote connection parameter request
14 - data length change
15 - read local P256 key complete
16 - generate dhkey compelete
17 - enhanced connection complete
18 - direct advertising report
19 - encryption change
20 - encryption key refresh
32 - pairing complete
33 - GATT error
34 - non-specific error
37 - security request
38 - GAPI request error
39 - GAPI list command complete
40 - transmit power
41 - authentication key request
42 - pairing request
44 - LE random number

Report

The JSON report property typically specifies a GAPI command associated with the report. Values are defined by globals appc.GG_API_....

1 - advertising report
26 - indication 27 - notification