cordova-plugin-ia-bluetooth-serial
v1.0.2
Published
Bluetooth Serial plugin for Cordova Android
Downloads
2
Readme
This is an Android-only fork of github.com/don/BluetoothSerial
Bluetooth Serial Plugin for Cordova
This plugin enables serial communication over Bluetooth. It was written for communicating between Android and BLClassis serial devices.
Limitations
- The phone must initiate the Bluetooth connection
- Will not connect Android to Android*
Installing
Install with Cordova CLI:
cordova plugin add cordova-plugin-ia-bluetooth-serial
Install with Ionic CLI:
ionic cordova plugin add cordova-plugin-ia-bluetooth-serial
API
Methods
- bluetoothSerial.connect
- bluetoothSerial.connectInsecure
- bluetoothSerial.disconnect
- bluetoothSerial.write
- bluetoothSerial.available
- bluetoothSerial.read
- bluetoothSerial.readUntil
- bluetoothSerial.subscribe
- bluetoothSerial.unsubscribe
- bluetoothSerial.subscribeRawData
- bluetoothSerial.unsubscribeRawData
- bluetoothSerial.clear
- bluetoothSerial.list
- bluetoothSerial.isEnabled
- bluetoothSerial.isConnected
- bluetoothSerial.readRSSI
- bluetoothSerial.showBluetoothSettings
- bluetoothSerial.enable
- bluetoothSerial.discoverUnpaired
- bluetoothSerial.setDeviceDiscoveredListener
- bluetoothSerial.clearDeviceDiscoveredListener
- bluetoothSerial.setName
- bluetoothSerial.setDiscoverable
connect
Connect to a Bluetooth device.
bluetoothSerial.connect(macAddress, connectSuccess, connectFailure);
Description
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.
Parameters
- 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.
connectInsecure
Connect insecurely to a Bluetooth device.
bluetoothSerial.connectInsecure(macAddress, connectSuccess, connectFailure);
Description
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.
Parameters
- 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
Disconnect.
bluetoothSerial.disconnect([success], [failure]);
Description
Function disconnect
disconnects the current connection.
Parameters
- success: Success callback function that is invoked after the connection is disconnected. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
write
Writes data to the serial port.
bluetoothSerial.write(data, success, failure);
Description
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.
Parameters
- 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]
Quick Example
// 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);
available
Gets the number of bytes of data available.
bluetoothSerial.available(success, failure);
Description
Function available
gets the number of bytes of data available. The bytes are passed as a parameter to the success callback.
Parameters
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.available(function (numBytes) {
console.log("There are " + numBytes + " available to read.");
}, failure);
read
Reads data from the buffer.
bluetoothSerial.read(success, failure);
Description
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.
Parameters
- 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]
Quick Example
bluetoothSerial.read(function (data) {
console.log(data);
}, failure);
readUntil
Reads data from the buffer until it reaches a delimiter.
bluetoothSerial.readUntil('\n', success, failure);
Description
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.
Parameters
- delimiter: delimiter
- success: Success callback function that is invoked with the data.
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.readUntil('\n', function (data) {
console.log(data);
}, failure);
subscribe
Subscribe to be notified when data is received.
bluetoothSerial.subscribe('\n', success, failure);
Description
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.
Parameters
- delimiter: delimiter
- success: Success callback function that is invoked with the data.
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
// the success callback is called whenever data is received
bluetoothSerial.subscribe('\n', function (data) {
console.log(data);
}, failure);
unsubscribe
Unsubscribe from a subscription.
bluetoothSerial.unsubscribe(success, failure);
Description
Function unsubscribe
removes any notification added by subscribe
and kills the callback.
Parameters
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.unsubscribe();
subscribeRawData
Subscribe to be notified when data is received.
bluetoothSerial.subscribeRawData(success, failure);
Description
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.
Parameters
- success: Success callback function that is invoked with the data.
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
// the success callback is called whenever data is received
bluetoothSerial.subscribeRawData(function (data) {
var bytes = new Uint8Array(data);
console.log(bytes);
}, failure);
unsubscribeRawData
Unsubscribe from a subscription.
bluetoothSerial.unsubscribeRawData(success, failure);
Description
Function unsubscribeRawData
removes any notification added by subscribeRawData
and kills the callback.
Parameters
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.unsubscribeRawData();
clear
Clears data in the buffer.
bluetoothSerial.clear(success, failure);
Description
Function clear
removes any data from the receive buffer.
Parameters
- 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
bluetoothSerial.list(success, failure);
Description
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"
}]
Note
id
is the generic name for uuid
or [mac]address
so that code can be platform independent.
Parameters
- success: Success callback function that is invoked with a list of bonded devices.
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.list(function(devices) {
devices.forEach(function(device) {
console.log(device.id);
})
}, failure);
isConnected
Reports the connection status.
bluetoothSerial.isConnected(success, failure);
Description
Function isConnected
calls the success callback when connected to a peer and the failure callback when not connected.
Parameters
- success: Success callback function, invoked when device connected.
- failure: Error callback function, invoked when device is NOT connected.
Quick Example
bluetoothSerial.isConnected(
function() {
console.log("Bluetooth is connected");
},
function() {
console.log("Bluetooth is *not* connected");
}
);
isEnabled
Reports if bluetooth is enabled.
bluetoothSerial.isEnabled(success, failure);
Description
Function isEnabled
calls the success callback when bluetooth is enabled and the failure callback when bluetooth is not enabled.
Parameters
- success: Success callback function, invoked when Bluetooth is enabled.
- failure: Error callback function, invoked when Bluetooth is NOT enabled.
Quick Example
bluetoothSerial.isEnabled(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("Bluetooth is *not* enabled");
}
);
readRSSI
Reads the RSSI from the connected peripheral.
bluetoothSerial.readRSSI(success, failure);
Description
Function readRSSI
calls the success callback with the rssi.
BLE only This function is experimental and the API may change
Parameters
- success: Success callback function that is invoked with the rssi value.
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.readRSSI(
function(rssi) {
console.log(rssi);
}
);
showBluetoothSettings
Show the Bluetooth settings on the device.
bluetoothSerial.showBluetoothSettings(success, failure);
Description
Function showBluetoothSettings
opens the Bluetooth settings on the operating systems.
Parameters
- success: Success callback function [optional]
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.showBluetoothSettings();
enable
Enable Bluetooth on the device.
bluetoothSerial.enable(success, failure);
Description
Function enable
prompts the user to enable Bluetooth.
Android
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.
Parameters
- success: Success callback function, invoked if the user enabled Bluetooth.
- failure: Error callback function, invoked if the user does not enabled Bluetooth.
Quick Example
bluetoothSerial.enable(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("The user did *not* enable Bluetooth");
}
);
discoverUnpaired
Discover unpaired devices
bluetoothSerial.discoverUnpaired(success, failure);
Description
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 proces to finish, and the sucess callback to be invoked.
Calling connect
on an unpaired Bluetooth device should begin the Android pairing process.
Parameters
- success: Success callback function that is invoked with a list of unpaired devices.
- failure: Error callback function, invoked when error occurs. [optional]
Quick Example
bluetoothSerial.discoverUnpaired(function(devices) {
devices.forEach(function(device) {
console.log(device.id);
})
}, failure);
setDeviceDiscoveredListener
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"
}
Parameters
- notify: Notify callback function that is invoked when device is discovered during discovery process.
Quick Example
bluetoothSerial.setDeviceDiscoveredListener(function(device) {
console.log('Found: '+device.id);
});
clearDeviceDiscoveredListener
Clears notify callback function registered with setDeviceDiscoveredListener.
Quick Example
bluetoothSerial.clearDeviceDiscoveredListener();
setName
Sets the human readable device name that is broadcasted to other devices.
bluetoothSerial.setName(newName);
Android
For Android, setName
takes a String for the new name.
Parameters
- newName: Desired name of device.
Quick Example
bluetoothSerial.setName("Really cool name");
setDiscoverable
Makes the device discoverable by other devices.
bluetoothSerial.setDiscoverable(discoverableDuration);
Android
For Android, setDiscoverable
takes an int for the number of seconds device should be discoverable. A time of 0 will make it permanently discoverable.
Parameters
- discoverableDuration: Desired number of seconds device should be discoverable for.
Quick Example
bluetoothSerial.setDiscoverable(0);
Misc
Where does this work?
Android
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.
API
The API for available, read, readUntil was influenced by the BtSerial Library for Processing for Arduino
What format should the Mac Address be in?
An example a properly formatted mac address is AA:BB:CC:DD:EE:FF