Bluetooth Serial Communication Plugin
npm install cordova-plugin-bluetoothClassic-serialxml
first.device.protocol.string
second.device.protocol.string
`
#### Phonegap Build config.xml entry for Supported Accessories
`xml
first.device.protocol.string
second.device.protocol.string
`
Examples
API
Methods
- bluetoothClassicSerial.connect
- bluetoothClassicSerial.connectInsecure
- bluetoothClassicSerial.disconnect
- bluetoothClassicSerial.write
- bluetoothClassicSerial.available
- bluetoothClassicSerial.read
- bluetoothClassicSerial.readUntil
- bluetoothClassicSerial.subscribe
- bluetoothClassicSerial.unsubscribe
- bluetoothClassicSerial.subscribeRawData
- bluetoothClassicSerial.unsubscribeRawData
- bluetoothClassicSerial.clear
- bluetoothClassicSerial.list
- bluetoothClassicSerial.isEnabled
- bluetoothClassicSerial.isConnected
- bluetoothClassicSerial.showBluetoothSettings
- bluetoothClassicSerial.enable
- bluetoothClassicSerial.discoverUnpaired
- bluetoothClassicSerial.setDeviceDiscoveredListener
- bluetoothClassicSerial.clearDeviceDiscoveredListener
connect
Connect to a Bluetooth device.
bluetoothClassicSerial.connect(deviceId, interfaceIdArray, connectSuccess, connectFailure);
$3
Function connect connects to a Bluetooth device. The callback is long running. Success will be called when the connection is successful. Failure is called if the connection fails, or later if the connection disconnects. An error message is passed to the failure callback. If a device has multiple interfaces then you can connect to them by providind the inteface Ids.
$3
- __connectSuccess__: Success callback function that is invoked when the connection is successful.
- __connectFailure__: Error callback function, invoked when error occurs or the connection disconnects.
#### Android
- __deviceId__: Identifier of the remote device. For Android this is the MAC address.
- __interfaceIdArray__: This identifies the serial port to connect to. For Android this is the SPP_UUID. A common SPP_UUID string is "00001101-0000-1000-8000-00805F9B34FB". The device doumentation should provide the SPP_UUID.
#### iOS
- __deviceId__: For iOS this is the connection ID
- __interfaceIdArray__: This identifies the serial port to connect to. For iOS the interfaceId is the Protocol String. The Protocol String must be one of those specified in your config.xml.
For iOS, connect takes the ConnectionID as the deviceID, and the Protocol String as the interfaceId.
connectInsecure
Connect insecurely to a Bluetooth device.
`
bluetoothClassicSerial.connectInsecure(deviceId, interfaceIdArray, connectSuccess, connectFailure);
`
$3
Function connectInsecure works like connect, but creates an insecure connection to a Bluetooth device. See the Android docs for more information.
#### Android
For Android, see connect.
#### iOS
connectInsecure is not supported.
$3
- __deviceId__: Identifier of the remote device. For Android this is the MAC address.
- __interfaceIdArray__: This identifies the serial port to connect to. For Android this is the SPP_UUID. A common SPP_UUID string is "00001101-0000-1000-8000-00805F9B34FB". The device documentation should provide the SPP_UUID.
- __connectSuccess__: Success callback function that is invoked when the connection is successful.
- __connectFailure__: Error callback function, invoked when error occurs or the connection disconnects.
disconnect
`
bluetoothClassicSerial.disconnect(success, failure);
`
$3
Function disconnect disconnects the current connection.
$3
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]
write
Writes data to the serial port.
`
bluetoothClassicSerial.write(interfaceId, data, success, failure);
`
$3
Function write data to the serial port. Data can be an ArrayBuffer, string, array of integers, or a Uint8Array.
Internally string, integer array, and Uint8Array are converted to an ArrayBuffer. String conversion assume 8bit characters.
$3
- __interfaceId__: The interface to send the data to
- __data__: ArrayBuffer of data
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
// string
bluetoothClassicSerial.write("00001101-0000-1000-8000-00805F9B34FB", "hello, world", success, failure);
// array of int (or bytes)
bluetoothClassicSerial.write("00001101-0000-1000-8000-00805F9B34FB", [186, 220, 222], success, failure);
// Typed Array
var data = new Uint8Array(4);
data[0] = 0x41;
data[1] = 0x42;
data[2] = 0x43;
data[3] = 0x44;
bluetoothClassicSerial.write(interfaceId, data, success, failure);
// Array Buffer
bluetoothClassicSerial.write(interfaceId, data.buffer, success, failure);
`
available
Gets the number of bytes of data available.
`
bluetoothClassicSerial.available(interfaceId, success, failure);
`
$3
Function available gets the number of bytes of data available. The bytes are passed as a parameter to the success callback.
#### iOS
available is not supported.
$3
- __interfaceId__: The interface to check
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
bluetoothClassicSerial.available("00001101-0000-1000-8000-00805F9B34FB", function (numBytes) { console.log("There are " + numBytes + " available to read."); }, failure);
`
read
Reads data from the buffer.
`
bluetoothClassicSerial.read(interfaceId, success, failure);
`
$3
Function read reads the data from the buffer. The data is passed to the success callback as a String. Calling read when no data is available will pass an empty String to the callback.
$3
- __interfaceId__: The interface to read
- __success__: Success callback function that is invoked with the number of bytes available to be read.
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
bluetoothClassicSerial.read("00001101-0000-1000-8000-00805F9B34FB", function (data) { console.log(data);}, failure);
`
readUntil
Reads data from the buffer until it reaches a delimiter.
bluetoothClassicSerial.readUntil(interfaceId, '\n', success, failure);
$3
Function readUntil reads the data from the buffer until it reaches a delimiter. The data is passed to the success callback as a String. If the buffer does not contain the delimiter, an empty String is passed to the callback. Calling read when no data is available will pass an empty String to the callback.
$3
- __interfaceId__: The interface to read
- __delimiter__: delimiter
- __success__: Success callback function that is invoked with the data.
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
bluetoothClassicSerial.readUntil("00001101-0000-1000-8000-00805F9B34FB", '\n', function (data) {console.log(data);}, failure);
`
subscribe
Subscribe to be notified when data is received.
bluetoothClassicSerial.subscribe(interfaceId, '\n', success, failure);
$3
Function subscribe registers a callback that is called when data is received. A delimiter must be specified. The callback is called with the data as soon as the delimiter string is read. The callback is a long running callback and will exist until unsubscribe is called.
$3
- __interfaceId__: The interface to subscribe to
- __delimiter__: delimiter
- __success__: Success callback function that is invoked with the data.
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
// the success callback is called whenever data is received
bluetoothClassicSerial.subscribe("00001101-0000-1000-8000-00805F9B34FB", '\n', function (data) {
console.log(data);
}, failure);
`
unsubscribe
Unsubscribe from a subscription.
bluetoothClassicSerial.unsubscribe(interfaceId, success, failure);
$3
Function unsubscribe removes any notification added by subscribe and kills the callback.
$3
- __interfaceId__: The interface to unsubscribe from
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
bluetoothClassicSerial.unsubscribe();
subscribeRawData
Subscribe to be notified when data is received.
bluetoothClassicSerial.subscribeRawData(interfaceId, success, failure);
$3
Function subscribeRawData registers a callback that is called when data is received. The callback is called immediately when data is received. The data is sent to callback as an ArrayBuffer. The callback is a long running callback and will exist until unsubscribeRawData is called.
$3
- __interfaceId__: The interface to subscribe to
- __success__: Success callback function that is invoked with the data.
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
// the success callback is called whenever data is received
bluetoothClassicSerial.subscribeRawData(function (data) {
var bytes = new Uint8Array(data);
console.log(bytes);
}, failure);
`
unsubscribeRawData
Unsubscribe from a subscription.
bluetoothClassicSerial.unsubscribeRawData(interfaceId, success, failure);
$3
Function unsubscribeRawData removes any notification added by subscribeRawData and kills the callback.
$3
- __interfaceId__: The interface to unsubscribe from
- __success__: Success callback function that is invoked when the unsubscribe is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
bluetoothClassicSerial.unsubscribeRawData("00001101-0000-1000-8000-00805F9B34FB");
`
clear
Clears data in the buffer.
bluetoothClassicSerial.clear(interfaceId, success, failure);
$3
Function clear removes any data from the receive buffer.
$3
- __success__: Success callback function that is invoked when the connection is successful. [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]
list
Lists bonded devices
bluetoothClassicSerial.list(success, failure);
$3
#### Android
Function list lists the paired Bluetooth devices. The success callback is called with a list of objects.
Example list passed to success callback. See BluetoothDevice) and BluetoothClass#getDeviceClass).
[{
"class": 276,
"id": "10:BF:48:CB:00:00",
"address": "10:BF:48:CB:00:00",
"name": "Nexus 7"
}, {
"class": 7936,
"id": "00:06:66:4D:00:00",
"address": "00:06:66:4D:00:00",
"name": "RN42"
}]
#### iOS
Function list lists the paired Bluetooth devices. The success callback is called with a list of objects.
Example list passed to success callback for iOS.
TBC
$3
id is the generic name for connection Id or [mac]address so that code can be platform independent.
$3
- __success__: Success callback function that is invoked with a list of bonded devices.
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
bluetoothClassicSerial.list(function(devices) {
devices.forEach(function(device) {
console.log(device.id);
})
}, failure);
`
isConnected
Reports the connection status. If all interfaces are connected then the success callback is called. If one interface is not connected then the failure callback is called. The connect method does not allow the status of a single interface to be determined (unless you have only specified a single interfaceId in the prior connect method).
bluetoothClassicSerial.isConnected(success, failure);
$3
Function isConnected calls the success callback when connected to a peer and the failure callback when not connected.
$3
- __success__: Success callback function, invoked when device connected.
- __failure__: Error callback function, invoked when device is NOT connected.
$3
`
bluetoothClassicSerial.isConnected(
function() {
console.log("Bluetooth is connected");
},
function() {
console.log("Bluetooth is not connected");
}
);
`
isEnabled
Reports if bluetooth is enabled.
bluetoothClassicSerial.isEnabled(success, failure);
$3
Function isEnabled calls the success callback when bluetooth is enabled and the failure callback when bluetooth is not enabled.
$3
- __success__: Success callback function, invoked when Bluetooth is enabled.
- __failure__: Error callback function, invoked when Bluetooth is NOT enabled.
$3
`
bluetoothClassicSerial.isEnabled(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("Bluetooth is not enabled");
}
);
`
showBluetoothSettings
Show the Bluetooth settings on the device.
bluetoothClassicSerial.showBluetoothSettings(success, failure);
$3
Function showBluetoothSettings opens the Bluetooth settings on the operating systems.
#### iOS
showBluetoothSettings is not supported.
$3
- __success__: Success callback function [optional]
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
bluetoothClassicSerial.showBluetoothSettings();
`
enable
Enable Bluetooth on the device.
bluetoothClassicSerial.enable(success, failure);
$3
Function enable prompts the user to enable Bluetooth. If enable is called when Bluetooth is already enabled, the user will not prompted and the success callback will be invoked.
#### iOS
enable is not supported.
enable is only supported on Android and does not work on iOS.
If enable is called when Bluetooth is already enabled, the user will not prompted and the success callback will be invoked.
$3
- __success__: Success callback function, invoked if the user enabled Bluetooth.
- __failure__: Error callback function, invoked if the user does not enabled Bluetooth.
$3
`
bluetoothClassicSerial.enable(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("The user did not enable Bluetooth");
}
);
`
discoverUnpaired
Discover unpaired devices
bluetoothClassicSerial.discoverUnpaired(success, failure);
$3
The behaviour of this method varies between Android and iOS.
#### Android
Function discoverUnpaired discovers unpaired Bluetooth devices. The success callback is called with a list of objects similar to list, or an empty list if no unpaired devices are found.
Example list passed to success callback.
`
[{
"class": 276,
"id": "10:BF:48:CB:00:00",
"address": "10:BF:48:CB:00:00",
"name": "Nexus 7"
}, {
"class": 7936,
"id": "00:06:66:4D:00:00",
"address": "00:06:66:4D:00:00",
"name": "RN42"
}]
`
The discovery process takes a while to happen. You can register notify callback with setDeviceDiscoveredListener.
You may also want to show a progress indicator while waiting for the discover process to finish, and the success callback to be invoked.
Calling connect on an unpaired Bluetooth device should begin the Android pairing process.
#### iOS
Function discoverUnpaired will launch a native iOS window showing all devices which match the protocol string defined in the application's cordova config.xml file. Choosing a device from the list will initiate pairing and the details of that device will not trigger the success callback function. The device discovered listener must be used. Once paired the device is available for connection.
$3
- __success__: Success callback function that is invoked with a list of unpaired devices.
- __failure__: Error callback function, invoked when error occurs. [optional]
$3
`
bluetoothClassicSerial.discoverUnpaired(function(devices) {
devices.forEach(function(device) {
console.log(device.id);
})
}, failure);
`
setDeviceDiscoveredListener
$3
Register a notify callback function to be called during bluetooth device discovery.
#### Android
Register a notify callback function to be called during bluetooth device discovery. For callback to work, discovery process must
be started with discoverUnpaired.
There can be only one registered callback.
Example object passed to notify callback.
`
{
"class": 276,
"id": "10:BF:48:CB:00:00",
"address": "10:BF:48:CB:00:00",
"name": "Nexus 7"
}
`
#### iOS
When a device is paired from the discoverUnpaired function it's details will be passed to the callback function. Unlike Android this will only be fired once for the selected device, not for all the available devices.
$3
- __notify__: Notify callback function that is invoked when device is discovered during discovery process.
$3
`
bluetoothClassicSerial.setDeviceDiscoveredListener(function(device) {
console.log('Found: ',device.id);
});
`
clearDeviceDiscoveredListener
Clears notify callback function registered with setDeviceDiscoveredListener.
$3
`
bluetoothClassicSerial.clearDeviceDiscoveredListener();
``