Cordova (PhoneGap) Plugin for Serial Communication over Bluetooth
This plugin enables serial communication over Bluetooth. It was written for communicating between Android or iOS and an Arduino.
Android and Windows Phone use Classic Bluetooth. iOS uses Bluetooth Low Energy.
Supporting other Bluetooth Low Energy hardware
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.
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.
For iOS, connect takes the UUID of the remote device. Optionally, you can pass an empty string and the plugin will connect to the first BLE peripheral.
For Windows Phone, connect takes a MAC address of the remote device. The MAC address can optionally surrounded with parenthesis. e.g. (AA:BB:CC:DD:EE:FF)
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.
connectInsecure is not supported on iOS.
connectInsecure is not supported on Windows Phone.
Disconnect.
bluetoothSerial.disconnect([success], [failure]);
Function disconnect disconnects the current connection.
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.
// 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);
Gets the number of bytes of data available.
bluetoothSerial.available(success, failure);
Function available gets the number of bytes of data available. The bytes are passed as a parameter to the success callback.
bluetoothSerial.available(function (numBytes) {
console.log("There are " + numBytes + " available to read.");
}, failure);
Reads data from the buffer.
bluetoothSerial.read(success, failure);
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.
bluetoothSerial.read(function (data) {
console.log(data);
}, failure);
Reads data from the buffer until it reaches a delimiter.
bluetoothSerial.readUntil('\n', success, failure);
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.
bluetoothSerial.readUntil('\n', function (data) {
console.log(data);
}, failure);
Subscribe to be notified when data is received.
bluetoothSerial.subscribe('\n', success, failure);
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.
// the success callback is called whenever data is received
bluetoothSerial.subscribe('\n', function (data) {
console.log(data);
}, failure);
Unsubscribe from a subscription.
bluetoothSerial.unsubscribe(success, failure);
Function unsubscribe removes any notification added by subscribe and kills the callback.
bluetoothSerial.unsubscribe();
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.
// 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.
bluetoothSerial.unsubscribeRawData();
Clears data in the buffer.
bluetoothSerial.clear(success, failure);
Function clear removes any data from the receive buffer.
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"
}]
Function list lists the discovered Bluetooth Low Energy peripheral. The success callback is called with a list of objects.
Example list passed to success callback for iOS.
[{
"id": "CC410A23-2865-F03E-FC6A-4C17E858E11E",
"uuid": "CC410A23-2865-F03E-FC6A-4C17E858E11E",
"name": "Biscuit",
"rssi": -68
}]
The advertised RSSI may be included if available.
Function list lists the paired Bluetooth devices. The success callback is called with a list of objects.
Example list passed to success callback for Windows Phone.
[{
"id": "(10:BF:48:CB:00:00)",
"name": "Nexus 7"
}, {
"id": "(00:06:66:4D:00:00)",
"name": "RN42"
}]
id is the generic name for uuid or [mac]address so that code can be platform independent.
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.
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.
bluetoothSerial.isEnabled(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("Bluetooth is *not* enabled");
}
);
Reads the RSSI from the connected peripheral.
bluetoothSerial.readRSSI(success, failure);
Function readRSSI calls the success callback with the rssi.
BLE only This function is experimental and the API may change
bluetoothSerial.readRSSI(
function(rssi) {
console.log(rssi);
}
);
Show the Bluetooth settings on the device.
bluetoothSerial.showBluetoothSettings(success, failure);
Function showBluetoothSettings opens the Bluetooth settings on the operating systems.
showBluetoothSettings is not supported on iOS.
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 and does not work on iOS or Windows Phone.
If enable is called when Bluetooth is already enabled, the user will not prompted and the success callback will be invoked.
bluetoothSerial.enable(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("The user did *not* enable Bluetooth");
}
);
Discover unpaired devices
bluetoothSerial.discoverUnpaired(success, failure);
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 proces to finish, and the sucess callback to be invoked.
Calling connect on an unpaired Bluetooth device should begin the Android pairing process.
discoverUnpaired is not supported on iOS. iOS uses Bluetooth Low Energy and list discovers devices without pairing.
discoverUnpaired is not supported on Windows Phone.
bluetoothSerial.discoverUnpaired(function(devices) {
devices.forEach(function(device) {
console.log(device.id);
})
}, failure);
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"
}
See discoverUnpaired.
bluetoothSerial.setDeviceDiscoveredListener(function(device) {
console.log('Found: '+device.id);
});
Clears notify callback function registered with setDeviceDiscoveredListener.
bluetoothSerial.clearDeviceDiscoveredListener();
Sets the human readable device name that is broadcasted to other devices.
bluetoothSerial.setName(newName);
For Android, setName takes a String for the new name.
Not currently implemented.
Not currently implemented.
bluetoothSerial.setName("Really cool name");
Makes the device discoverable by other devices.
bluetoothSerial.setDiscoverable(discoverableDuration);
For Android, setDiscoverable takes an int for the number of seconds device should be discoverable. A time of 0 will make it permanently discoverable.
Not currently implemented.
Not currently implemented.
bluetoothSerial.setDiscoverable(0);
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
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.
NOTE: Currently iOS only works with RedBear Labs Hardware, Adafruit Bluefruit LE, Laird BL600, and BlueGiga UART services
This plugin was originally developed with Cordova 3.4 using iOS 7.x on an iPhone 5s connecting to a RedBearLab BLEMini. Ensure that you have update the BLE Mini firmware to at least Biscuit-UART_20130313.bin.
Most development is now done with iOS 8 with Cordova 4.2 using RedBear Lab BLE Shield or Adafruit Bluefruit LE Friend.
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.
The iOS code uses RedBearLab’s BLE_Framework.
The API for available, read, readUntil was influenced by the BtSerial Library for Processing for Arduino
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.