cordova-plugin-bitalino v0.0.5
BITalino Plugin for Apache Cordova
This plugin enables the communication between an Android device and BITalino. It supports Classic Bluetooth and Bluetooth Low Energy.
Supported Platforms
- Android
Limitations
- BITalino BLE does not allow a high sampling rate.
Installing
Install with Cordova cli
$ cordova plugin add cordova-plugin-bitalinoExamples
There is a sample project included with the plugin.
API
Methods
- bitalino.enableScan
- bitalino.scanForDevice
- bitalino.connect
- bitalino.disconnect
- bitalino.start
- bitalino.stop
- bitalino.getVersion
- bitalino.setBatteryThreshold
- bitalino.trigger
- bitalino.getState
- bitalino.setPwm
enableScan
Enables the scan to start or stop the discovery of BITalino devices.
bitalino.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).
scanForDevice
Enables the scan of a specific BITalino device.
bitalino.scanForDevice(onSuccess, onError, address, timeOut);Description
Function scanForDevice enables the scan for a specific Bluetooth device for a certain period. Success will be called if the device was found. Failure is called otherwise.
Parameters
- onSuccess: Success callback function that is invoked if the device was found.
- onError: Error callback function, invoked when the device was not found, or some error has occurred.
- address: Device’s identifier (MAC Address).
- timeOut: Duration of the scan (in milliseconds).
connect
Connect to a BITalino Device.
bitalino.connect(onSuccess, onError, address);Description
Function connect tries to establish a connection with the BITalino 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.
- address: Device’s identifier (MAC Address).
disconnect
Disconnect from the BITalino Device.
bitalino.disconnect(onSuccess, onError);Description
Function disconnect allows the disconnection from the BITalino 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.
start
Starts a real-time acquisition with the given parameters.
bitalino.start(onSuccess, onError, analogChannels, sampleRate);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.
- analogChannels: An array with the active channels.
- sampleRate: The acquisition’s sampling rate.
stop
Stops the acquisition.
bitalino.stop(onSuccess, onError);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.
getVersion
Gets the BITalino’s firmware version.
bitalino.getVersion(onSuccess, onError);Description
Function getVersion allows the user to retrieve the BITalino’s firmware version. Success will be called when the version information is received. Failure will be called if some error occurs.
Parameters
- onSuccess: Success callback function that is invoked, returning the device’s version.
- onError: Error callback function invoked when some error occurs.
setBatteryThreshold
Sets a new battery threshold for the low-battery LED.
bitalino.setBatteryThreshold(onSuccess, onError, value);Description
Function setBatteryThreshold allows the user to set a new battery’s threshold value for the BITalino device to show the low-battery LED indicator. Success will be called if the command can be given, failure will be called otherwise.
Parameters
- onSuccess: Success callback function that is invoked if the command could be given.
- onError: Error callback function invoked when some error occurs.
- value: new battery threshold value
trigger
Assigns the digital outputs states.
bitalino.trigger(onSuccess, onError, digitalChannels);Description
Function trigger sets a new state for the BITalino’s output digital channels. Success will be called if the command could be called, failure will be called otherwise.
Parameters
- onSuccess: Success callback function that is invoked if the command could be given.
- onError: Error callback function invoked when some error occurs.
- digitalChannels: an array with the digital channels states (if enabled it should be set as 1, otherwise it should be set as 0).
getState
Gets the device’s current state.
bitalino.getState(onSuccess, onError);Description
Function getState gets the current state of all BITalino’s featured components: digital channels, analog channels, battery, PWM (analog output) and battery threshold. Success will be called when the current state is returned. Failure will be called with some error occurs.
Parameters
- onSuccess: Success callback function that is invoked when the device returns its current state, returning a JSONObject that is described below.
- onError: Error callback function invoked when some error occurs.
JSONObject State
{“address”:“B0:B4:48:F0:C8:60",“digitalChannels”:[1,1,0,0],“analogChannels”:[499,621,522,0,516,512],“analogOutput”:0,“battery”:585,“batThreshold”:0}Elements:
- address: device’s MAC Address
- digitalChannels: current state of the digital channels
- analogChannels: current state of the analog channels
- analogOutput: current PWM value
- battery: current battery level
- batThreshold: current battery threshold
setPwm
Assigns the analog (PWM) output value.
bitalino.setPwm(onSuccess, onError, pwmOut);Description
Function setPWM enables setting a new PWM output value. Success will be called if the command can be given. Failure will be called if some error occurs.
Parameters
- onSuccess: Success callback function that is invoked if the command could be given.
- onError: Error callback function invoked when some error occurs.
- pwmOutput: PWM output
Android’s Auxiliary methods
askForPermission
Tests and asks for permission to use the Coarse Location functionality of the mobile device, needed to scan Bluetooth Devices.
bitalino.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
onDeviceFound
Callback that retrieves the Bluetooth Devices found during the scan.
bitalino.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 BITalino 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.
bitalino.onConnectionStateChanged(state, 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 BITalino 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.
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.
bitalino.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 (from 0 to 15)
- digitalChannels: digital channels current state
- analogChannels: analog channels received values
Feedback
Try the code. If you find an problem or missing feature file an issue.
Acknowledgments
This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement N°690367 (http://www.polycare-project.com/)