don/BluetoothSerial don/BluetoothSerial

  • Stars
    star
    1,069
  • Rank 43,234 (Top 0.9 %)
  • Language
    Objective-C
  • License
    Other
  • Created over 11 years ago
  • Updated 7 months ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
don/BluetoothSerial
github

don

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Cordova (PhoneGap) Plugin for Serial Communication over Bluetooth

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

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

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

Android

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"
}]

iOS

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.

Windows Phone

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"
}]

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.

iOS

showBluetoothSettings is not supported on iOS.

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.

iOS

discoverUnpaired is not supported on iOS. iOS uses Bluetooth Low Energy and list discovers devices without pairing.

Windows Phone

discoverUnpaired is not supported on Windows Phone.

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"
}

iOS & Windows Phone

See discoverUnpaired.

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.

iOS

Not currently implemented.

Windows Phone

Not currently implemented.

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.

iOS

Not currently implemented.

Windows Phone

Not currently implemented.

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.

iOS

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.

Supporting other BLE hardware

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.

Props

Android

Most of the Bluetooth implementation was borrowed from the Bluetooth Chat example in the Android SDK.

iOS

The iOS code uses RedBearLab's BLE_Framework.

API

The API for available, read, readUntil was influenced by the BtSerial Library for Processing for Arduino

Wrong Bluetooth Plugin?

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.

What format should the Mac Address be in?

An example a properly formatted mac address is AA:BB:CC:DD:EE:FF

Feedback

Try the code. If you find an problem or missing feature, file an issue or create a pull request.

More Repositories

1

cordova-plugin-ble-central

Bluetooth Low Energy (BLE) Central plugin for Apache Cordova (aka PhoneGap)
Java
950
star
2

node-eddystone-beacon

Create an Eddystone Beacon using Node.js https://github.com/google/eddystone
JavaScript
315
star
3

NDEF

NDEF Library for Arduino. Read and Write NDEF Messages to NFC tags with Arduino.
C++
282
star
4

cordova-plugin-hello

Sample Hello World Cordova Plugin
Objective-C
192
star
5

ionic-ble-examples

Ionic Framework Bluetooth Low Energy Examples
TypeScript
102
star
6

phonegap-nfc-reader

PhoneGap NFC reader demo
JavaScript
101
star
7

cordova-filechooser

Cordova Plugin that supplies a File Chooser
Java
96
star
8

ionic-nfc-reader

NFC Reader using Cordova, Ionic Framework and phonegap-nfc plugin
JavaScript
78
star
9

KeyboardToolbarRemover

Cordova Plugin to remove the Previous, Next and Done buttons from above the iOS Keyboard
Objective-C
57
star
10

cordova-plugin-rfduino

Cordova (PhoneGap) plugin for RFduino
Objective-C
46
star
11

ionic-ble

JavaScript
34
star
12

html-cam

Use Device API and File API to take and display a photo using the Android browser
JavaScript
30
star
13

cordova-plugin-ble-peripheral

Apache Cordova plugin for implementing BLE (Bluetooth Low Energy) peripherals.
Java
30
star
14

cordova-plugin-hce

Cordova plugin for Host Card Emulation (HCE)
Java
28
star
15

phonegap-p2p

PhoneGap NFC peer to peer demo
JavaScript
22
star
16

ndef-js

Library to create and parse NDEF messages
JavaScript
21
star
17

mifare-classic-js

Read and write NDEF bytes to Mifare Classic Tags
JavaScript
21
star
18

Arduino101BluetoothMIDI

Bluetooth MIDI controller built with the Arduino 101
Arduino
16
star
19

ITP-BluetoothLE

Code for ITP Bluetooth LE class at NYU
JavaScript
15
star
20

ble-background

Use cordova-plugin-ble-central to scan, connect, & receive notifications while app is in background
JavaScript
14
star
21

locus

Parser for LOCUS log files
Python
14
star
22

ITP-DeviceToDatabase

C++
13
star
23

phonegap-nfc-writer

PhoneGap NFC writer demo
JavaScript
13
star
24

cordova-hce-demo

Demo project for Cordova Host Card Emulation (HCE) plugin
JavaScript
11
star
25

rockpaperscissors

PhoneGap NFC demo - writes peer to peer and reads tags
JavaScript
10
star
26

sencha-exercise

JavaScript
10
star
27

rfduino-js

JavaScript
9
star
28

BluetoothLock

Arduino
9
star
29

MKR1000-Azure

MKR1000 with DHT22 to Azure
Arduino
7
star
30

ninja-thing

Send temperature and humidity data from Ninja Blocks to The Thing System via TSRP
JavaScript
7
star
31

nfc-launch

Demo - launch a Cordova app when scanning a NFC tag
Java
7
star
32

phonegap-nfc-ios

JavaScript
5
star
33

iotdevfest

Arduino Workshop for IoT DevFest www.iotdevfest.com
C++
5
star
34

slides

JavaScript
5
star
35

sencha-datastore

Simple Sencha Touch Data Store Example
JavaScript
5
star
36

nfc-acr122

Java
5
star
37

cordova-bluetooth-midi

JavaScript
5
star
38

apachecon-nfc-demos

Java
3
star
39

rfduino-logreader

JavaScript
3
star
40

ArduinoByteStream

Read-only Stream from a byte array for Ardunio
Arduino
3
star
41

phonegap-ble-workshop

PhoneGap Day 2016 & 2017 Hands on Bluetooth Low Energy Wokshop
JavaScript
3
star
42

mfba2016-arduino-ble

Maker Faire Bay Area 2016 - Creating Bluetooth Low Energy peripherals with Arduino http://don.github.io/slides/2016-05-21-arduino-ble
Arduino
3
star
43

ble-scan

Simple demo using cordova-plugin-ble-central to scan for Bluetooth low energy peripherals
HTML
3
star
44

mfny2016-arduino-ble

Arduino
2
star
45

respeaker-lights

Python
2
star
46

sencha-virtual-model-field

Sencha Touch Virtual Model Field Example
JavaScript
2
star
47

mfny2015-rpi-ble

Examples from Maker Faire 2015 Raspberry PI BLE presentation
JavaScript
2
star
48

itp-conndev

JavaScript
2
star
49

ninja-nfc

NFC driver for Ninja Blocks
JavaScript
2
star
50

cocoaheadsnyc

Sample code for 2016-06-09 CocoaHeadsNYC presentation
Objective-C
1
star
51

nfc-test

JavaScript
1
star
52

mfba2016-wireless-sensors

Maker Faire Bay Area 2016 - Building Wireless Sensors http://don.github.io/slides/2016-05-22-wireless-sensors
HTML
1
star
53

phonegap-nfc-issue-247

JavaScript
1
star
54

techcast-mobile

Experimenting with JQuery Mobile
Ruby
1
star
55

solidcon-hands-on-ble

JavaScript
1
star
56

nfc-share

Test project for phonegap-nfc share
CSS
1
star
57

ble-issue196

JavaScript
1
star
58

BluetoothSerialApiDev

JavaScript
1
star
59

sencha-drilldown

iPhone drill down example using Sencha Touch
JavaScript
1
star
60

incubator-cordova-tizen

Mirror of Apache Cordova Tizen
JavaScript
1
star
61

pg-beam

android beam phonegap experiment
JavaScript
1
star
62

chariot-iot-workshop

Chariot Solutions IoT Workshop Philly Tech Week 2019
C++
1
star
63

mfny2018-lora

Sample code from Maker Faire NY 2018 presentation https://makerfaire.com/maker/entry/68112/
C++
1
star
64

sencha-localstore

Sencha Touch Local Storage Example
JavaScript
1
star
65

sencha-xpn

JavaScript
1
star
66

weinre-offline

1
star
67

MemoryFree

Arduino Available Memory http://playground.arduino.cc/Code/AvailableMemory
C++
1
star
68

many-ble-notifications

JavaScript
1
star
69

iot-workshop

JavaScript
1
star
70

ibeacon-demo

iBeacon Scanner demo
Objective-C
1
star
71

phonegap-nfc-issue-190

nfc test code
CSS
1
star
72

phonegap-nfc-issue144

JavaScript
1
star
73

phonegap-plugins

Slides for PhoneGap Day 2012 presentation
JavaScript
1
star
74

cordova-filetransfer

Server for Cordova FileTransfer Jasmine tests
JavaScript
1
star