Cordova-plugin-plux NPM

PLUX API Plugin for Apache Cordova

This plugin enables the communication between an Android device and PLUX's devices. It supports Classic Bluetooth and Bluetooth Low Energy.

Supported Platforms

Android

Limitations

Devices using BLE does not allow a high sampling rate.
Before connecting any device, the device must be found using the enableScan function.

Installing

Install with Cordova cli

$ cordova plugin add cordova-plugin-plux

Examples

There is a sample project included with the plugin.

API

enableScan

Enables the scan to start or stop the discovery of PLUX devices.

plux.enableScan(onSuccess, onError, enable, timeInMs);

Description

Function enableScan provides the capability to start or stop the scan of Bluetooth devices. If the enable argument is true the scan will start, otherwise if a scanning is occurring it will be stopped. The scan’s duration will be the value passed through the timeInMs parameter. Success will be called when the function is called with success. Failure is called when some parameter is wrongly passed, or if the function could not be called. The available devices are returned via onDeviceFound callback.

Parameters

onSuccess: Success callback function that is invoked when the scan starts successfully.
onError: Error callback function, invoked when error occurs.
enable: Enable flag.
timeInMs: Scan period (in milliseconds).

connect

Connect to a PLUX Device.

plux.connect(onSuccess, onError, identifier);

Description

Function connect tries to establish a connection with the PLUX device with the given identifier. Success will be called if the connection process can be started, failure will be called otherwise. The changes in the device’s connection state will be given using the onConnectionStateChanged callback.

Parameters

onSuccess: Success callback function that is invoked with the connection command was called with success.
onError: Error callback function, invoked when errors occur.
identifier: Device’s identifier (MAC Address).

disconnect

Disconnect from the OKUX Device.

plux.disconnect(onSuccess, onError, identifier);

Description

Function disconnect allows the disconnection from the PLUX device. Success will be called if the disconnection could be triggered. Failure is called if the device is not connected or if some error occurs.

Parameters

onSuccess: Success callback function that is invoked with the device can be disconnected.
onError: Error callback function, invoked when some error occurs or if the device is not connected.
identifier: Device’s identifier (MAC Address).

start

Starts a real-time acquisition with the given parameters.

plux.start(onSuccess, onError, identifier, sampleRate, sources);

Description

Function start will start an acquisition with the given parameters. Success will be called if the instruction can be given with success. Failure will be called with some error occurs.

Parameters

onSuccess: Success callback function that is invoked if the start command could be fired.
onError: Error callback function invoked when some error occurs.
identifier: Device’s identifier (MAC Address).
sampleRate: The acquisition’s sampling rate.
sources: An array with the active sources.

stop

Stops the acquisition.

plux.stop(onSuccess, onError, identifier);

Description

Function stop stops the acquisition occurring in the device. Success will be called if the command is given with success. Failure will be called if there is no acquisition occurring or if the device is disconnected.

Parameters

onSuccess: Success callback function that is invoked if the stop command could be given.
onError: Error callback function invoked when some error occurs.
identifier: Device’s identifier (MAC Address).

Android’s Auxiliary methods

plux.askForPermission

askForPermission

Tests and asks for permission to use the Coarse Location functionality of the mobile device, needed to scan Bluetooth Devices.

plux.askForPermission(onSuccess, onError);

Description

Function askForPermission allows the user to ensure if he has granted the application the possibility to use the needed permissions. If the user has not granted the permission yet, the plugin will ask for it. Success will be called if the permission is granted. Failure will be called otherwise or if some error occurs.

Parameters

onSuccess: Success callback function that is invoked when the asked permissions are granted.
onError: Error callback function invoked if the user did not grant the asked permission or when some error occurs.

Callbacks

plux.onDeviceFound
plux.onConnectionStateChanged
plux.onDataAvailable
plux.onDeviceReady

onDeviceFound

Callback that retrieves the Bluetooth Devices found during the scan.

plux.onDeviceFound(device, onError);

Description

Function onDeviceFound is a callback function that is set to be a channel of communication between the plugin and the application, sending the found devices during the scan. Success (device) will be called every time a new PLUX device is found by the mobile device, this data is structured in a JSON object as described below. Failure will be called if there was any error parsing the data.

Parameters

device: JSONObject that contains the current connection state
onError: Error callback function invoked when some parsing error occurs.

JSONObject data

{“address”:“B0:B4:48:F0:C8:60",“name”:“BITalino BLE”,“communication”:“BLE”,“rssi”:-32}

Elements:

address: device’s MAC Address
name: device’s name
communication: device’s type of communication (BTH, BLE or DUAL)
rssi: signal strength indicator

onConnectionStateChanged

Callback that retrieves the states of the connection from the plugin.

plux.onConnectionStateChanged(state, onError);

Description

Function onConnectionStateChanged is a callback function that is set to be a channel of communication between the plugin and the application, sending the current state of the connection every time it changes. Success (state) will be called every time the connection state changes, as this data is structured in a JSON object as described below. Failure will be called if there is any error parsing the data.

Parameters

state: JSONObject that contains the current connection state
onError: Error callback function invoked when some parsing error occurs.

JSONObject data

{“address”:“B0:B4:48:F0:C8:60",“state”:3}

Elements:

identifier: device’s MAC Address
state: current connection state ordinal -- 0: NO CONNECTION -- 1: LISTEN -- 2: CONNECTING -- 3: CONNECTED -- 4: ACQUISITION TRYING -- 5: ACQUISITION OK -- 6: ACQUISTIION STOPPING -- 7: DISCONNECTED -- 8: ENDED

onDataAvailable

Callback that retrieves the data from the plugin.

plux.onDataAvailable(data, onError);

Description

Function onDataAvailable is a callback function that is set to be a channel of communication between the plugin and the application, sending the acquired data through it. Success (data) will be called every time new data is available, as this data is structured in a JSON object as described below. Failure will be called if there is any error parsing the data.

Parameters

data: JSONObject that contains the data frame
onError: Error callback function invoked when some parsing error occurs.

JSONObject data

{“address”:“B0:B4:48:F0:C8:60",“sequence”:4,“digitalChannels”:[1,1,0,0],“analogChannels”:[495,514,0,521,39,0]}

Elements:

identifier: device’s MAC Address
sequence: frame’s sequence number
digitalChannels: digital channels current state
analogChannels: analog channels received values

onDeviceReady

Callback that retrieves the device's properties from the plugin.

plux.onDeviceReady(deviceProperties, onError);

Description

Function onDeviceReady is a callback function that is triggered when the connection with the device is successfully established, sending the connect device's properties through it. Success (deviceProperties) will be called once upon the device connection, as this data is structured in a JSON object as described below. Failure will be called if there is any error parsing the data.

Parameters

deviceProperties: JSONObject that contains the device's properties
onError: Error callback function invoked when some parsing error occurs.

JSONObject data

{"description":"Texboost MB Plux","fwVersion":1024,"hwVersion":515,"memorySize":-1,"path":"88:6B:0F:4D:F7:C4","productID":1282,"uid":"88:6B:0F:4D:F7:C4"}

Elements: