This plugin enables serial communication over Bluetooth. It was written for communicating between Android and an Arduino.
- Android
- The phone must initiate the Bluetooth connection
- Data sent over the connection is assumed to be Strings
Use plugman to add BluetoothSerial to your Android project. Plugman requires node.js and is installed through npm.
Install plugman
$ npm install -g plugman
Get the latest source code
$ git clone https://github.com/don/BluetoothSerial.git
Install the plugin
$ plugman --platform android --project /path/to/your/project --plugin /path/to/BluetoothSerial
Modify your HTML to include bluetoothSerial.js
<script type="text/javascript" src="cordova-2.7.0.js"></script>
<script type="text/javascript" src="js/bluetoothSerial.js"></script>
<script type="text/javascript" src="js/index.js"></script>
Require bluetoothSerial in your JavaScript
var bluetoothSerial = cordova.require('bluetoothSerial');
- bluetoothSerial.connect
- bluetoothSerial.disconnect
- bluetoothSerial.write
- bluetoothSerial.available
- bluetoothSerial.read
- bluetoothSerial.readUntil
- bluetoothSerial.subscribe
- bluetoothSerial.unsubscribe
- bluetoothSerial.clear
- bluetoothSerial.list
- bluetoothSerial.isEnabled
- bluetoothSerial.isConnected
Connect to a Bluetooth device.
bluetoothSerial.connect(macAddress, 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.
- 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 when the connection is successful. [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 must be a String.
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
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.
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
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.
- 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]
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.
- delimiter: delimiter
- success: Success callback function that is invoked with the data.
- failure: Error callback function, invoked when error occurs. [optional]
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.
- delimiter: delimiter
- 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.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.
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
bluetoothSerial.unsubscribe();
Clears data in the buffer.
bluetoothSerial.clear(success, failure);
Function clear
removes any data from the receive buffer.
- success: Success callback function that is invoked when the connection is successful. [optional]
- failure: Error callback function, invoked when error occurs. [optional]
Lists bonded devices
bluetoothSerial.list(success, failure);
Function list
lists and 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,
"address": "10:BF:48:CB:00:00",
"name": "Nexus 7"
}, {
"class": 7936,
"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.address);
})
}, failure);
Reports the connection status.
bluetoothSerial.isConnected(success, failure);
Function isConnected
passes true to the success callback when connected to another device.
- success: Success callback function that is invoked with a boolean for connected status.
- failure: Error callback function, invoked when error occurs. [optional]
bluetoothSerial.isConnected(function (connected) {
console.log(connected); // true or false
}, failure);
Reports if bluetooth is enabled.
bluetoothSerial.isEnabled(success, failure);
Function isEnabled
passes true to the success callback when bluetooth is enabled.
- success: Success callback function that is invoked with a boolean for connected status.
- failure: Error callback function, invoked when error occurs. [optional]
bluetoothSerial.isEnabled(function (enabled) {
console.log(enabled); // true or false
}, failure);
This plugin was developed with PhoneGap 2.7.0 using Android 4.2.2 on a Nexus 4 connecting to a Sparkfun Mate Silver. The code should be generic and work with most hardware.
Most of the Bluetooth implementation was borrows from the Bluetooth Chat example in the Android SDK.
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
Try the code. If you find an problem or missing feature, file an issue or create a pull request.