Bluetooth Serial Plugin for PhoneGap

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.

Supported Platforms

• Android
• iOS with RedBearLab BLE hardware, Adafruit Bluefruit LE, Laird BL600, BlueGiga, or HC-02
• Windows Phone 8
• Browser (Testing only. See comments.)

Supporting other Bluetooth Low Energy hardware

Limitations

• The phone must initiate the Bluetooth connection
• iOS Bluetooth Low Energy requires iPhone 4S, iPhone5, iPod 5, or iPad3+
• Will not connect Android to Android*
• Will not connect iOS to iOS*

Installing

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.

Examples

There are some sample projects included with the plugin.

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_or_uuid, 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.

Android

For Android, connect takes a MAC address of the remote device.

iOS

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.

Windows Phone

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)

Parameters

• 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.

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.

Android

For Android, connectInsecure takes a macAddress of the remote device.

iOS

connectInsecure is not supported on iOS.

Windows Phone

connectInsecure is not supported on Windows Phone.

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 invoke