BITalino Java Application Programming Interface. Documentation Android API

Transcription

1 BITalino Java Application Programming Interface Documentation Android API

2 Contents Contents General Information Introduction Main Objects Class BITalinoDescription Class BITalinoFrame Class BITalinoState Main Classes Class BITalinoCommunicationFactory Class BITalinoCommunication Data Asynchronous Communication Implementation Example [BLE] Implementation Example [BTH] Contents PLUX java API for Android

3 1. General Information Interface Specification Document BITalino Java Application Programming Interface Date Current Revision 1 Author Gonçalo Telo Revision Number Change History Author Date Change 1 Gonçalo Telo Initial Document for API BLE BTH Glossary Bluetooth Low Energy Bluetooth BITalino Java API for Android General Information 3

4 2. Introduction The BITalino Java Application Programming Interface (API) brings to java android applications all the functionalities of BITalino devices. The API is implemented based on the utilization of the factory design pattern which provides the developer with a simple way to choose between the different types of communication available. The class BITalinoCommunication contains the methods required to communicate with a BITalino device, as well as receiving information on their state. This device can be accessed through a classic Bluetooth connection or using Bluetooth Low Energy. The class BITalinoException implements the exception which is thrown by the API when an error condition is met while calling any of the API functions or class methods. The API consists of a jar file (pluxapi jar, where is the code version name) containing the API object code. 4 Introduction BITalino Java API for Android

5 3. Main Objects There are four types of objects that are important to make a proper use of the PLUX s API: 3.1. Class BITalinoDescription Object that has the event data received from the bluetooth device. There are two types of events: the battery event and the onbody event Methods: isbitalino2() [boolean] isbitalino2 - returns true if the device is a BITalino 2, otherwise returns false getfwversion() [float] fwversion - returns the device's firmware version 3.2. Class BITalinoFrame Object that has the data received from the bluetooth device Methods: getidentifier() [String] identifier returns the MAC address of the device that sent the frame getsequence() [int] sequence returns the sequence number of the frame BITalino Java API for Android Main Objects 5

6 getanalog() [int[]] analogdata returns an array with all the channel values of the frame getdigital() [int[]] digitalinput returns an array with all the digital channel value 3.3. Class BITalinoState Object that has the current state returned by the bluetooth device Methods: getidentifier() [String] identifier returns the MAC address of the device that sent the frame getanalog() [int[]] analogdata returns an array with all the channel values of the frame getbattery() [int] battery returns current battery value getbatthreshold() 6 Main Objects BITalino Java API for Android

7 [int] batthreshold returns current battery threhold getdigital() [int[]] digitalinput returns an array with all the digital channel value BITalino Java API for Android Main Objects 7

8 4. Main Classes 4.1. Class BITalinoCommunicationFactory Overview This class allows the user to select from the possible types of communication Methods getcommunication ( Communication type, Context context) [in] type type of communication selected (BTH or BLE) context application s activity bitalinocommunication BITalinoCommunication object, with the selected type of communication associated to it. Returns the object with the chosen type of communication. getcommunication ( Communication type, Context context, OnBITalinoDataAvailable callback) [in] type type of communication selected (BTH or BLE) context application s activity callback callback that receives the BITalino frames (BTH only) bitalinocommunication BITalinoCommunication object, with the selected type of communication associated to it. Returns the object with the chosen type of communication. 8 Main Classes BITalino Java API for Android

9 4.2. Class BITalinoCommunication Overview This class includes all the methods that compose the communication channel with the BITalino device. It is through this object that the developer can call the methods to set the acquisition parameters or start and stop an acquisition using a BITalino device. The communication between the android device and the bitalino device is asynchronous, using a local broadcast or a callback to send the received data from a lower level to the higher level (like an activity of the app) Methods void scan() Scans for PLUX s devices in the near area. This method has an asynchronous response that returns an object (BluetoothDevice) with the device s name and MAC address. boolean connect(string address) [in] address Media Access Control (MAC) address, the unique identifier of the device. [boolean] true if the connection to the device is successful, false otherwise Tries to connect to the device with the given MAC address. void disconnect() [boolean] true if the device is disconnected successfully, false otherwise BITalino Java API for Android Main Classes 9

10 Disconnects the device and closes the connection channel created. boolean start(int[] analogchannels, int samplerate) [in] analogchannels an array with the active analog channels samplerate the sampling frequency value [boolean] true if the command is sent successfully to the bluetooth device, false otherwise Starts the acquisition mode of the device. An exception is thrown if the device is already acquiring. The samplerate parameter must be 1 Hz, 10 Hz, 100 Hz or 1000 Hz. On acquisition mode, the frames sent by the bluetooth device are received by the phone and then sent to the local broadcast receiver in the BLE case, or to the OnBITalinoDataAvailable callback in the BTH case, using the BiopluxFrame object. boolean stop() [boolean] true if the command is sent successfully, false otherwise Stops the acquisition mode in the device. An exception is throw if the acquisition mode is not active. boolean getversion() [boolean] true if the command is sent successfully, false otherwise 10 Main Classes BITalino Java API for Android

11 Get the connected device s firmware version. boolean battery(int value) [in] value the new battery threshold value [boolean] true if the command is sent successfully, false otherwise Sets a new battery threshols for the low-battery LED. boolean trigger(int[] digitalchannels) [in] digitalchannels an array with the digital channels to enable set as 1, and the digital channels to disable set as 0. [boolean] true if the command is sent successfully, false otherwise Assigns the digital output states. boolean state() [boolean] true if the command is sent successfully, false otherwise BITalino Java API for Android Main Classes 11

12 Asks for the device's current state. (BITalino 2 only) boolean pwm(int pwmoutput) [in] digitalchannels an array with the digital channels to enable set as 1, and the digital channels to disable set as 0. [boolean] true if the command is sent successfully, false otherwise Assigns the analog (PWM) output value. (BITalino 2 only) 12 Main Classes BITalino Java API for Android

13 5. Data Asynchronous Communication All the information needed on the client side can be received by the user with a Broadcast Receiver as follows: private final BroadcastReceiver updatereceiver = new BroadcastReceiver() public void onreceive(context context, Intent intent) { final String action = intent.getaction(); if (Constants.ACTION_STATE_CHANGED.equals(action)) { String identifier = intent.getstringextra(constants.identifier); Constants.States state = Constants.States.getStates(intent.getIntExtra(Constants.EXTRA_STATE_CHANGED,0); Log.i(TAG, "Device " + identifier + ": " + state.name()); } else if (Constants.ACTION_DATA_AVAILABLE.equals(action)) { BITalinoFrame frame = intent.getparcelableextra(constants.extra_data); Log.d(TAG, "BITalinoFrame: " + frame.tostring()); } else if (Constants.ACTION_COMMAND_REPLY.equals(action)) { String identifier = intent.getstringextra(constants.identifier); Parcelable parcelable = intent.getparcelableextra(constants.extra_command_reply); if(parcelable.getclass().equals(bitalinostate.class)){ Log.d(TAG, "BITalinoState: " + parcelable.tostring()); } else if(parcelable.getclass().equals(bitalinodescription.class)){ Log.d(TAG, "BITalinoDescription: isbitalino2: " + ((BITalinoDescription)parcelable).isBITalino2() + ; FwVersion: String.valueOf(((BITalinoDescription)parcelable).getFwVersion()) ); } } else if (Constants.ACTION_MESSAGE_SCAN.equals(action)){ BluetoothDevice device = intent.getparcelableextra(constants.extra_device_scan); } } }; protected static IntentFilter updateintentfilter() { final IntentFilter intentfilter = new IntentFilter(); intentfilter.addaction(constants.action_state_changed); intentfilter.addaction(constants.action_data_available); intentfilter.addaction(constants.action_command_reply); intentfilter.addaction(constants.action_message_scan); return intentfilter; } The following table contains the descriptions of all the intents regarding the data and event BITalino Java API for Android Data Asynchronous Communication 13

14 communication, as well as their occurring scenarios. Intent Action Constants.ACTION_STATE_CHANGED Constants.ACTION_DATA_AVAILABLE Constants.ACTION_COMMAND_REPLY Constants.ACTION_MESSAGE_SCAN Scenario Bluetooth connection state changed, this intent has the MAC Address of the device as an extra. EXTRAS: [String] Constants.IDENTIFIER [Constants.States] Constants.EXTRA_STATE_CHANGED This intent is sent when the android device receives the acquired data from the bluetooth device and then the API decodes it and sends an object (BITalinoFrame) as an extra. This object has also the device's MAC Address. (BLE only) EXTRAS: [Parcelable] Constants.EXTRA_DATA This intent is sent when the android device receives a reply from the BITalino device commands through the API. This intent has two extras, the device's MAC Address and an object (Parcelable) that can be a BITalinoState object or a BITalinoDescription object. EXTRAS: [String] Constants.IDENTIFIER [Parcelable] Constants.EXTRA_COMMAND_REPLY After the call of the API method scan, the available PLUX's devices will be sent with this intent. This intent has an object as an extra (BluetoothDevice). EXTRAS: [BluetoothDevice] Constants.EXTRA_DEVICE_SCAN 14 Data Asynchronous Communication BITalino Java API for Android

15 6. Implementation Example [BLE] 1. Initialize the bitalino API: BITalinoCommunication bitalino = new BITalinoCommunicationFactory ().getcommunication(communication.ble, getbasecontext()); 2. Register your broadcast receiver: registerreceiver(updatereceiver, updateintentfilter()); 3. Connect to the selected device: bitalino.connect(aa:bb:cc:dd:ee:ff); 4. After the device version is received on the broadcast receiver, you can call the other API methods. There is an example below: //Begin acquisition with a base frequency of 100 Hz for one channel due the BLE communication limitations int[] analogchannels = new int[]{0}; int samplerate = 100; bitalino.start(analogchannels, samplerate); try { Thread.sleep(10000); } catch (Exception e){ e.printstacktrace(); } bitalino.stop(); bitalino.disconnect(); BITalino Java API for Android Implementation Example [BLE] 15

16 7. Implementation Example [BTH] 1. Initialize the bitalino API: BITalinoCommunication bitalino = new BITalinoCommunicationFactory ().getcommunication(communication.bth, getbasecontext(), new public void onbitalinodataavailable(bitalinoframe bitalinoframe) { Log.d(TAG, "BITalinoFrame: " + bitalinoframe.tostring()); } }); 2. Register your broadcast receiver: registerreceiver(updatereceiver, updateintentfilter()); 3. Connect to the selected device: bitalino.connect(aa:bb:cc:dd:ee:ff); 4. After the ready event is received on the broadcast receiver, you can call the other API methods. There is an example below: //Begin acquisition with a base frequency of 1000 Hz for all analog channels int[] analogchannels = new int[]{0,1,2,3,4,5}; int samplerate = 1000; bitalino.start(analogchannels, samplerate); try { Thread.sleep(10000); } catch (Exception e){ e.printstacktrace(); } bitalino.stop(); bitalino.disconnect(); 16 Implementation Example [BTH] BITalino Java API for Android