Bluetooth Low Energy (BLE) for IoTize devices Plugin for Apache Cordova

This plugin enables communication between a mobile and a BLE enabled IOTIZE device.

The plugin provides a simple JavaScript API for iOS, Android and Windows.

• Scan for ble iotize devices
• Connect to a device
• Send a Request and returns the reponse from the device

Supported Platforms

• iOS
• Android ()
• Windows (10)

Installing

Cordova

$ cordova plugin add @iotize/device-com-ble.cordova
$ ionic cordova plugin add @iotize/device-com-ble.cordova
for iOS since the plugin is in swift language, before using iotize-ble plugin , cordova-plugin-add-swift-support:https://github.com/akofman/cordova-plugin-add-swift-support should be installed.

API

Methods

• iotize-ble.checkAvailable
• iotize-ble.startScan
• iotize-ble.stopScan
• iotize-ble.connect
• iotize-ble.disConnect
• iotize-ble.isConnected
• iotize-ble.send

checkAvailable

Check availability of BLE.

iotize-ble.checkAvailable(success, failure);

Description

Function checkAvailable returns true or false upon the availability of BLE on device.

For Android, BLE is available from version 4.3.
iOS platform has had support for BLE since iPhone 4s and iOs 5. For Windows, BLE GATT and GAP roles have been introduced in Windows 10 version 1703.

startScan

Start scanning for Iotize BLE devices.

iotize-ble.startScan(success, failure);

Description

Function startScan scans for IoTize BLE devices. Scanning will continue until stopScan is called or a connection is established. The success callback is called each time a new peripheral is discovered.

Advertising information is different depending on your platform. For Android and Windows, the device is identified with its MAC address and for iOS the device is identified with a unique UUID. The success callback is called at each discovery with returning an object containing the following information:

• name: name of the peripheral.
• address: UUID or MAC address of the peripheral.
• rssi: the threshold RSSI in dBm.

Parameters

• success: Success callback function that is invoked upon each discovery. The callback is called with the device information as parameter.
• failure: Error callback function, invoked when error occurs. The error string is passed as a parameter.

stopScan

Stop scanning for BLE peripherals.

iotize-ble.stopScan(success, failure);

Description

Function stopScan stops scanning for BLE devices.

Parameters

• success: Success callback function, invoked when scanning is stopped.
• failure: Error callback function, invoked when error occurs.

Quick Example

iotize-ble.startScan([], function(device) {
    console.log(device);
}, failure);

setTimeout(function() {
    iotize-ble.stopScan(
        function() { console.log("Scan complete"); },
        function() { console.log("stopScan failed"); }
    );
}, 2000);

connect

Connect to a peripheral.

iotize-ble.connect(device_id, connectCallback, connectionErrorCallback);

Description

Function connect connects to an iotize BLE peripheral. The connectCallback callback will be called when the connection is successful.

The connectionErrorCallback callback is called if the connection fails, or later if the peripheral disconnects for any reason. The connectionErrorCallback callback is only called when the peripheral initates the disconnection.

Scanning before connecting

Devices should be scanned before connection. Please note that for this version only one device at a time could be connected.

Parameters

• device_id: Mac address or UUID of the ble device.
• connectCallback: Connect callback function that is invoked when the connection is successful.
• connectionErrorCallback: Disconnect callback function, invoked when the peripheral disconnects or an error occurs.

disconnect

Disconnect.

iotize-ble.disConnect(device_id, success, failure);

Description

Function disConnect disconnects the selected device.

Parameters

• device_id: Mac address or UUID of the device.
• success: Success callback function that is invoked when the connection is successful.
• failure: Error callback function, invoked when error occurs.

send

sends a frame of byte to ioTize device using SPP characteristic.

iotize-ble.send(device_id, __data__, success, failure);

Parameters

• device_id: Mac address or UUID of the device.
• data: binary data as a string ex:"A2CA000007010003FFFF0002"
• success: Success callback function that is invoked when the connection is successful. The result parameter is the response as a string :"45496F547A50723030343130303030313039429000"
• failure: Error callback function, invoked when error occurs.

Quick Example

// read data from a characteristic, do something with received data
iotize-ble.send(
           name,
           data,
           function successHandler(result) {
               console.log("received result " + result);
               observer.complete();
           },
           function errorHandler(err) {
               observer.error(err);
           });
   });

Testing the Plugin

License

MIT

Feedback

Try the code. If you find an problem or missing feature pluease contact Iotize support team .