Device.bluetoothPairDevice()
Overview
On an Android device, pairs a Bluetooth device, or returns information about an already paired device.
This function will start the pairing process, and will return immediately. If not already paired, the OS and/or the device may display pairing dialogs.
Added in version 2.1.29
Format
var started = Device.bluetoothPairDevice(address, discover, function callback(result));
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| address | The MAC address of the device to pair. | String | Required | The MAC address must be six hex octets separated by colons. The hex must use uppercase digits, or an error will be returned. |
| discover | Specifies if discovery should be used to pair the device. The default is false. | Boolean | Optional | If enabled, the device must already be in pairing mode, or the operation will fail. Devices paired without using discovery may report an unknown device class. |
| callback | A function that is called when the pairing operation has completed. | Function | Optional | |
| result | A result object that contains the status of the pairing operation. | Object | Parameter | See Result Object definition below. |
| started | Indicates if the pairing process is started. | Boolean | Return value | A return value of false indicates a pairing operation is already in progress or that the application cannot pair at this time. |
Result Object
| Value | Description | Type |
|---|---|---|
| status | A status code indicating result of the pairing operation. See Status Codes below. | Integer |
| info | Information on the paired device. Will be null for any status codes other than success. See Info Object below. | String |
Status Codes
| Value | Description |
|---|---|
| 0 | Success. The device was successfully paired, or the device was already paired. |
| 1 | Address invalid. The MAC address must be 12 uppercase hex digits separated by colons. |
| 2 | Bluetooth not available. The Bluetooth option is disabled or unavailable on the device. |
| 3 | Failed to pair. The pairing option timed out, the user canceled the dialog, or the device is out of range. More information is available in the log. |
| 4 | Error pairing. General error to pair the device. More information is available in the log. |
Info Object
| Value | Description | Type |
|---|---|---|
| name | The friendly name of the Bluetooth device. | String |
| address | The MAC address of the Bluetooth device. | String |
| class | The device class of the Bluetooth device. See Bluetooth Class of device below. | Integer |
| uuids | An array of Bluetooth supported feature UUIDs reported for the device. See Bluetooth Supported Feature UUIDs below. | Array of string |
Bluetooth Class of Device
The Bluetooth class of device is a number identifier that helps to categorize devices. This information is broadcast when the device is in pairing mode and collected during discovery. If a device is connected without discovery, it may be set to Unknown (7936 (0x1F00)).
See "Class of Device" in the Assigned Numbers document at https://www.bluetooth.com/specifications/assigned-numbers/
Here are a few common classes:
| Class | Description |
|---|---|
| 1028 (0x0404) | Audio/Video - Headset |
| 1048 (0x0418) | Audio/Video - Headphones |
| 1044 (0x0414) | Audio/Video - Loudspeaker |
| 1664 (0x0680) | Imaging - Printer |
| 7936 (0x1F00) | Unknown |
Bluetooth Supported Feature UUIDs
UUIDs specify services provided by a Bluetooth device.
See "SDP Service Class and Profile Identifiers" in Assigned Numbers document at https://www.bluetooth.com/specifications/assigned-numbers/
Here are a few common UUIDs:
| Class | Description |
|---|---|
| 00000000-0000-1000-8000-00805f9b34fb | Bluetooth Base |
| 00001108-0000-1000-8000-00805f9b34fb | Headset Profile |
| 0000111e-0000-1000-8000-00805f9b34fb | Hands-Free Profile |
| 00001101-0000-1000-8000-00805f9b34fb | Serial Port Profile |
| 0000110b-0000-1000-8000-00805f9b34fb | Advanced Audio Distribution Profile |
Example
/* Tries to connect to the Bluetooth device "00:11:22:AA:BB:CC" when the F1 key is pressed.
* Logs information on success or failure.
*/
WLEvent.onKey(0xE03B, function(event) {
var started = Device.bluetoothPairDevice("00:11:22:AA:BB:CC", true, function (result) {
if(result.status == 0) {
Logger.debug("Successfully connected to Bluetooth device: " + JSON.stringify(result.info));
} else {
Logger.error("Failed to pair " + result.status);
}
});
if(!started) {
Logger.error("Cannot start pairing");
}
event.eventHandled = true;
});