Connection Overview¶
GAPI operates with both unconnected and connected LE devices.
GAPI list may be used to find unconnected devices which are Advertising.
If an unconnected device supports connections, the GAPI connect method may be used to initiate a connection to it. Additional GAPI methods may then be used with the connection.
There is no inherent GAPI limit to the number of unconnected or connected devices, although there may be product-dependent limitations, particularly on the number of simultaneous connections.
list(params, success, error)¶
- Call:
appc.gapi.prototype.list(params, success, error) - Parameters: params, success, error
params: an object:
{
active: <1 (active) or 0 (passive) scan>
period: <scan period (in seconds); 0, disable scan>
}
success: a callback accepting an object:
{
c: 0, // command
m: 0, // message id (optional)
result: <result code>
subcode: <result subcode>
}
error: a callback accepting an object:
{ result: <result code> }
Description:
Scan for devices that are Advertising.
Since a scan period may be long list consists of several phases:
- acknowledgement of the scan (list success callback)
- report of scan results (report success callback(s))
- indication that the scan period has expired (event success callback)
A list success callback indicates that a scan operation has been successfully initiated.
A report success callback is used to convey Advertising data. This callback may occur 0 or more times during scanning. Different Advertising data may be passed to the report success callback, depending on the value of the active parameter. For example, data may include both rsp and adv properties when active is set to 1. When active is set to 0, no rsp data will be present.
Finally, an event callback indicates that the scan period has expired, and the scan operation has been stopped.
If the application wishes to stop the scan operation prior to receiving the event callback, list may be called again with period set to 0. For example:
gapi.list({ period: 0 }, null, null);
Any other list calls made before the event callback occurs will be followed by a list error callback.
Example:
Active list call:
gapi.list({'active': 1, 'period': 3},
function(robj) {
console.log('list: ' + JSON.stringify(robj, null, 2));
function(robj) {
console.log('list: ' + JSON.stringify(robj, null, 2));
});
Passive list call:
gapi.list({'active': 0, 'period': 5},
function(robj) { console.log(robj);
console.log('list: ' + JSON.stringify(robj, null, 2));
},
function(robj) {
console.log('list: ' + JSON.stringify(robj, null, 2));
});
show(params, success, error)¶
- Call:
appc.gapi.prototype.show(params, success, error) - Parameters: params, success, error
params: an object:
{
did: <device id (address); null or show all devices>
}
success: a callback accepting an object:;
{
c: 2, // command
m: 0, // message id (optional)
result: <result code>
subcode: <result subcode>
}
error: A callback accepting an object:
{ result: <result code> }
Description:
Show information about a device (or all devices) currently connected to a gateway.
The success callback receives a result object with information about the connected device(s). The nodes property is an array of pairs including device id (did) and Received Signal Strength Indication (rssi).
For example:
nodes: [ { rssi: 0, did: '112233445566' }, { rssi: 127, did: '8571bc897124' } ]
The rssi property is an integer given in dBm.
Example:
Using show to find a particular device connected to a gateway:
gapi.show({'did': '112233445566'},
function(robj) {
console.log('show: ' + JSON.stringify(robj, null, 2));
},
function(robj) {
console.log('show: ' + JSON.stringify(robj, null, 2));
});
Using show to find all devices connected to a gateway:.
gapi.show({'did': null},
function(robj) {
console.log('show: ' + JSON.stringify(robj, null, 2));
},
function(robj) {
console.log('show: ' + JSON.stringify(robj, null, 2));
});
connect(params, success, error)¶
- Call:
appc.gapi.prototype.connect(params, success, error) - Parameters: params, success, error
params: an object:
{
did: <device id (address)>,
dtype: <device type; 0 (public), 1, (random)>,
interval_min: <minimum connection interval: 6 to 3200 (times 1.25 msec)>,
interval_max: <maximum connection interval: 6 to 3200 (times 1.25 msec)>,
latency: <connection latency: 0 to 6>,
timeout: <connection timeout: 10 to 320 (times 10msec)>,
wait: <connection establishment wait time: 0 to 15 sec)
}
success: a callback accepting an object:
{
c: 4,
m: 0,
result: <result code>,
node: <device id (address)>,
subcode: <result subcode>
}
error: a callback accepting an object:
{ result: <result code> }
Description:
Connect to a device.
Typically, information about an unconnected device is conveyed in a report success callback during a list operation. If the device appears in a show success callback, this method would indicate the device is already connected.
Example:
Connect to a device (did and dtype may be taken from a report success callback):
var connect_parameter = {
did: '112233445566',
dtype: 1,
interval_min: 80,
interval_max: 800,
latency: 0,
timeout: 600,
wait: 10
};
gapi.connect(connect_parameter,
function(robj) {
console.log('connect: ' + JSON.stringify(robj, null, 2));
},
function(errObj) {
console.log('connect: ERROR: ' + JSON.stringify(robj, null, 2));
});
disconnect(params, success, error)¶
Example:
- Call:
appc.gapi.prototype.disconnect(params, success, error) - Parameters: params, success, error
params: an object:
{
did: <device id (address); null to disconnect from all devices>
}
success: A callback accepting a result object.
{
c: 5, // command
m: 0, // message id (optional)
result: <result code>
subcode: <result subcode>
}
error: A callback accepting a result object.
{ result: <result code> }
Description:
Disconnect from device.
The devices must have been previously connected by a call to connect. The application using GAPI might start running with devices already connected. Such devices can be discovered by calling show. The application can disconnect the previously connected devices after authentication and transport establishment.
Example:
gapi.disconnect({'did': '112233445566'},
function(robj) {
console.log('disconnect: ' + robj.result);
},
function(robj) {
console.log('disconnect: ERROR: ' + robj.result);
});
pair(params, success, error)¶
- Call:
appc.gapi.prototype.pair(params, success, error) - Parameters: params, success, error
params: an object:
{
did: <device id (address), null to unpair all>,
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)>,
bonding: <1 (to create bond), 0 (no bond)>,
mitm: <1 (man-in-the-middle protection)>,
secure: <1 (LE Secure Connection), 0 (LE Legacy)>,
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>
Further details about pairing parameters may be found in Vol 3, H.3 of the Bluetooth Core Version 4.2
success: a callback accepting an object:
{
c: 41,
m: 0,
result: <result code>
subcode: <result subcode>
}
error: a callback accepting an object:
{ result: <result code> }
Description:
Pair or unpair gateway with a device.
A device that wants to share date securely with another device must first pair with that device.
Pairing may be done immediately after a connection has been successfully created.
More information about pairing may be found at: SPP.
Example: unpair
var params = {
"did": "",
"op": 0
};
gapi.pair(params,
function(robj) {
},
function(robj) {
});
Example: pair
// Pair and bond with a device: LE Legacy pairing, JustWorks method.
// A connection must exist.
var params = {
"did": "112233445566",
"op": 1,
"iocap": 3,
"bonding": 1
"mitm": 0,
"secure": 0,
"key_max": 16
"key_value": "",
"key_length": 0,
"init": 1,
"resp": 1
};
gapi.pair(params,
function(robj) {
},
function(robj) {
});
Example: list pairs
var params = {
"did": "",
"op": 2,
};
gapi.pair(params,
function(robj) {
},
function(robj) {
});
Example: set pair key
// set key for pairing operation
// key is binary, but passed as hexified string
// key length, however, is length of binary key (in bytes)
// call may be made in response to: appc.EVENT_AUTHEN_KEY
// connection must exist
var params = {
"did": "112233445566",
"op": 3,
"key_value": "ABCDEF012345",
"key_length": 6
};
gapi.pair(params,
function(robj) {
},
function(robj) {
});