The Sample APP contained inside this repository provides a practical and intuitive resource to explore the integration of some signal acquisition devices commercialized by PLUX (biosignalsplux, biosignalsplux Solo, muscleBAN and cardioBAN) in an Android application created through Unity environment.
Some questions can be enlightened, such as:
- How PLUX acquisition systems can be searched and found on the Android device?
- How to pair an Android tablet/mobile phone with a PLUX device?
- How to start a real-time acquisition?
- How to stop the real-time acquisition?
- SDK Platform 27 [Android 8.1]
- Unity 2022.1.16f1
- PLUX devices from BITalino product line are not currently supported.
- Graphical User Interface is optimized for tablets.
The provided project folder is a ready to use Unity solution, you simply need to access the cloned folder through Unity interface.
On the following animation we can quickly show the main functionalities of our Sample APP:
- Inside the Plugins folder of our Sample APP, copy the Android/hw-api.dll file to the Plugins folder of your Unity project. This .dll contains the PLUX API Plugin, acting as an interface between your application and PLUX hardware
- Copy Scripts/Utils folder to the Scripts directory of you Unity project. Classes contained inside this folder will be responsible for a high-level abstraction in the interaction between your C# scripts and PLUX API Plugin
After the previous two steps, you will be fully prepared to expand your Unity project and include some interesting functionalities through the use of PLUX signal acquisition devices.
In order to trigger the execution of a specific operation, such as a) PLUX Devices Scan, b) Android/PLUX Device Connection, c) Start/Stop of a Real-Time Acquisition or d) Android/PLUX Device Disconnection, it will only be necessary to call one of the available methods of the DeviceController class (Methods).
- DeviceController.Scan
- DeviceController.Connect
- DeviceController.Disconnect
- DeviceController.StartAcquisition
- DeviceController.Stop
- DeviceController.IsSensorConnected
- DeviceController.Close
Method that is used to trigger the start of a Bluetooth device scan, searching for PLUX data acquisition systems. This method is invoked when the "Scan" button of the Sample APP is pressed.
public void Scan(bool enable)The input argument defines if the scanning process will be executed with a timeout limit, i.e., if enable is true then the search for Bluetooth devices will be conducted during 10 seconds.
Otherwise, if this parameter is false, a previously started scan can be securely interrupted/stopped.
- enable
bool: A flag that defines if the scan should be started (true) or stopped (false) before the standard 10 seconds period ends.
This method is intended to establish a Bluetooth connection with a PLUX device identifiable through the respective MAC-Address.
public void Connect(string id)With Connect method it is possible to establish a Bluetooth connection between an Android system and a PLUX Device. To ensure a successful pairing, the user only needs to specify the device mac-address (attached to biosignalsplux, biosignalsplux Solo or MuscleBAN hub...).
This mac-address should be inserted in a string format with the following structure: "00:07:80:4D:2E:AD" (6 pairs of characters separated by ":").
- id
string: The mac-address of the PLUX device with which a Bluetooth connection will be established.
Opposing to Connect, this method is very useful when you want to safely cut the connection between PLUX devices and an Android system.
public void Disconnect(string id)Through Disconnect method the established connection between a PLUX device and an Android system can be securely closed. If a real-time acquisition is yet being executed, a stop command is automatically sent, ensuring the end of communication loop.
- id
string: The mac-address of the PLUX device whose connection will be broken.
Class method used to start a Real-Time acquisition at the PLUX device paired with the Android system through Connect method.
public void StartAcquisition(String id, int frequency, int nChannels, int freqDivisor)In order to communicate with a digital system (as an Android tablet or mobile phone) the PLUX device needs to execute an Analogical to Digital Conversion (ADC), through data sampling.
Taking ADC stage into consideration, while starting a real-time acquisition, selecting a specific sampling rate or downsampling ratio is extremely easy through the inputs of StartAcquisition.
- id
string: mac-address of a previously connected PLUX device, where the real-time acquisition should take place. - frequency
int: Desired sampling rate that will be used during the data acquisition stage. The used units are in Hz (samples/s). - numberOfChannels
int: Number of the active channels that will be used during data acquisition. With biosignalsplux it is possible to collect data from up to 8 channels (simultaneously). - freqDivisor
int: Frequency divisor, i.e., acquired data will be subsampled accordingly to this parameter. If freqDivisor = 10, it means that each set of 10 acquired samples will trigger the communication of a single sample (through the communication loop).
Class method used to interrupt the real-time communication loop triggered by StartAcquisition() method.
public void Stop(String id)After starting a real-time acquisition a communication loop between the PLUX device and the Android system starts running on a parallel thread.
With Stop function, first of all, the communication loop is interrupted, stopping securely the real-time acquisition.
- id
string: mac-address of a PLUX device where a real-time data acquisition is currently taking place.
A simple getter method that retrieves the state of an internal flag intended to identify when a connection between a PLUX device and an Android system is currently active or not.
public bool IsSensorConnected()This method is extremely useful to control the start of a real-time acquisition in a secure way, i.e., it is advisable to verify if a Bluetooth connection is active before triggering the start of a real-time data acquisition.
Method without input parameters
A Boolean flag is returned, stating that a Bluetooth connection between a PLUX device and an Android system is currently active (true) or inactive (false).
A quick but very reliable way to destroy in a securely the DeviceController instance.
public void Close()This method acts as a destroyer of a DeviceController instance unregistering the BroadcastReceivers used by PLUX API Plugin in the Android environment.
Method without input parameters
There are some relevant callbacks that should be taken into consideration for a solid and secure implementation of all API functionalities.
The following instructions must be included in the Start() and OnDisable() callbacks of Unity APPs:
void Start () {
// Link the callbacks to the DeviceController object.
DeviceController.OnDataEvent += OnNewDataEvent;
DeviceController.OnDeviceConnectionChange += OnDeviceConnection;
DeviceController.OnNewDeviceFound += OnNewDeviceFound;
}
void OnDisable(){
// Remove callbacks from the scope of DeviceController class.
DeviceController.OnDataEvent -= OnNewDataEvent;
DeviceController.OnDeviceConnectionChange -= OnDeviceConnection;
DeviceController.OnNewDeviceFound -= OnNewDeviceFound;
// Destroy the DeviceController instance.
DeviceController.Instance.Close();
}A practical example of application of each callback (a) OnNewDataEvent | b) OnDeviceConnection | c) OnNewDeviceSelected) is available on the Scripts/MainScreenManager.cs file of the Sample APP.
OnNewDataEvent is used to receive the data packages communicated by the PLUX device, while OnNewDeviceFound is useful to receive the mac-address of each device detected during the Bluetooth scan.
Regarding OnDeviceConnection, this callback is a powerful resource to understand if the PLUX device is connected/disconnected or if a real-time acquisition is under execution.
If you find any problem during your experience, please, feel free to create a new issue track on our repository. We will be very glad to guide you in this amazing journey and listen your suggestions!