This plugin enables serial communication over Bluetooth. It was originally written for communicating between Android or iOS and an Arduino.
It can be used to communicate with Bluetooth barcode scanners in SPP mode.
Android uses Classic Bluetooth. iOS support has been disabled at this point.
Under Android 12 (API 31), Android support targets the lowest permission profiles, so only the BLUETOOTH_CONNECT permission is used, meaning that this plugin no longer manages discoverability.
- Android
- Browser (Testing only. See comments.)
Supporting other Bluetooth Low Energy hardware
- The phone must initiate the Bluetooth connection
- Will not connect Android to Android*
Install with Cordova cli
$ cordova plugin add cordova-plugin-bluetooth-serial
Note that this plugin's id changed from com.megster.cordova.bluetoothserial to cordova-plugin-bluetooth-serial as part of the migration from the Cordova plugin repo to npm.
There are some sample projects included with the plugin.
- bluetoothSerial.connect
- bluetoothSerial.connectInsecure
- bluetoothSerial.disconnect
- bluetoothSerial.write
- bluetoothSerial.subscribeRawData
- bluetoothSerial.unsubscribeRawData
- bluetoothSerial.list
- bluetoothSerial.isEnabled
- bluetoothSerial.isConnected
- bluetoothSerial.showBluetoothSettings
- bluetoothSerial.enable
Connect to a Bluetooth device.
bluetoothSerial.connect(macAddress_or_uuid, connectSuccess, connectFailure);
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.
For Android, connect takes a MAC address of the remote device.
- macAddress_or_uuid: Identifier of the remote device.
- connectSuccess: Success callback function that is invoked when the connection is successful.
- connectFailure: Error callback function, invoked when error occurs or the connection disconnects.
Connect insecurely to a Bluetooth device.
bluetoothSerial.connectInsecure(macAddress, connectSuccess, connectFailure);
Function connectInsecure works like connect, but creates an insecure connection to a Bluetooth device. See the Android docs for more information.
For Android, connectInsecure takes a macAddress of the remote device.
- macAddress: Identifier of the remote device.
- 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.
bluetoothSerial.disconnect([success], [failure]);
Function disconnect disconnects the current connection.
- success: Success callback function that is invoked after the connection is disconnected. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
Writes data to the serial port.
bluetoothSerial.write(data, success, failure);
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.
- 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]
// string
bluetoothSerial.write("hello, world", success, failure);
// array of int (or bytes)
bluetoothSerial.write([186, 220, 222], success, failure);
// Typed Array
var data = new Uint8Array(4);
data[0] = 0x41;
data[1] = 0x42;
data[2] = 0x43;
data[3] = 0x44;
bluetoothSerial.write(data, success, failure);
// Array Buffer
bluetoothSerial.write(data.buffer, success, failure);
Subscribe to be notified when data is received.
bluetoothSerial.subscribeRawData(success, failure);
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.
- success: Success callback function that is invoked with the data.
- failure: Error callback function, invoked when error occurs. [optional]
// the success callback is called whenever data is received
bluetoothSerial.subscribeRawData(function (data) {
var bytes = new Uint8Array(data);
console.log(bytes);
}, failure);
Unsubscribe from a subscription.
bluetoothSerial.unsubscribeRawData(success, failure);
Function unsubscribeRawData removes any notification added by subscribeRawData and kills the callback.
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
bluetoothSerial.unsubscribeRawData();
Lists bonded devices
bluetoothSerial.list(success, failure);
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"
}]
- success: Success callback function that is invoked with a list of bonded devices.
- failure: Error callback function, invoked when error occurs. [optional]
bluetoothSerial.list(function(devices) {
devices.forEach(function(device) {
console.log(device.id);
})
}, failure);
Reports the connection status.
bluetoothSerial.isConnected(success, failure);
Function isConnected calls the success callback when connected to a peer and the failure callback when not connected.
- success: Success callback function, invoked when device connected.
- failure: Error callback function, invoked when device is NOT connected.
bluetoothSerial.isConnected(
function() {
console.log("Bluetooth is connected");
},
function() {
console.log("Bluetooth is *not* connected");
}
);
Reports if bluetooth is enabled.
bluetoothSerial.isEnabled(success, failure);
Function isEnabled calls the success callback when bluetooth is enabled and the failure callback when bluetooth is not enabled.
- success: Success callback function, invoked when Bluetooth is enabled.
- failure: Error callback function, invoked when Bluetooth is NOT enabled.
bluetoothSerial.isEnabled(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("Bluetooth is *not* enabled");
}
);
Show the Bluetooth settings on the device.
bluetoothSerial.showBluetoothSettings(success, failure);
Function showBluetoothSettings opens the Bluetooth settings on the operating systems.
- success: Success callback function [optional]
- failure: Error callback function, invoked when error occurs. [optional]
bluetoothSerial.showBluetoothSettings();
Enable Bluetooth on the device.
bluetoothSerial.enable(success, failure);
Function enable prompts the user to enable Bluetooth.
enable is only supported on Android.
If enable is called when Bluetooth is already enabled, the user will not prompted and the success callback will be invoked.
- success: Success callback function, invoked if the user enabled Bluetooth.
- failure: Error callback function, invoked if the user does not enabled Bluetooth.
bluetoothSerial.enable(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("The user did *not* enable Bluetooth");
}
);
Current development is done with Cordova 4.2 on Android 5. Theoretically this code runs on PhoneGap 2.9 and greater. It should support Android-10 (2.3.2) and greater, but I only test with Android 4.x+.
Development Devices include
- Nexus 5 with Android 5
- Samsung Galaxy Tab 10.1 (GT-P7510) with Android 4.0.4 (see Issue #8)
- Google Nexus S with Android 4.1.2
- Nexus 4 with Android 5
- Samsung Galaxy S4 with Android 4.3
On the Arduino side I test with Sparkfun Mate Silver and the Seeed Studio Bluetooth Shield. The code should be generic and work with most hardware.
I highly recommend Adafruit's Bluefruit EZ-Link.
For Bluetooth Low Energy, this plugin supports some hardware running known UART-like services, but can support any Bluetooth Low Energy hardware with a "serial like" service. This means a transmit characteristic that is writable and a receive characteristic that supports notification.
Edit BLEdefines.h and adjust the UUIDs for your service.
See Issue 141 for details on how to add support for Amp'ed RF Technology BT43H.
Most of the Bluetooth implementation was borrowed from the Bluetooth Chat example in the Android SDK.
If you don't need serial over Bluetooth, try the PhoneGap Bluetooth Plugin for Android or perhaps phonegap-plugin-bluetooth.
If you need generic Bluetooth Low Energy support checkout my Cordova BLE Plugin.
If you need BLE for RFduino checkout my RFduino Plugin.
An example a properly formatted mac address is AA:BB:CC:DD:EE:FF
Try the code. If you find an problem or missing feature, file an issue or create a pull request.