cordova-plugin-empatica-device v1.0.0

cordova-plugin-empatica-device

This plugin helps cordova/ionic/phonegap projects to communicate with Empatica device (especially E4).

This plugin implements Empatica mobile SDK and needs SDK library (empalink) and API-KEY provided by Empatica. These should be available for you if you have empatica devices and an Empatica Connect account. Both of them are available from Empatica developer page.

Supported function list:

• initialize
• connect
• disconnect
• subscribe
• unsubscribe

The details about these functions will be explained in Methods section. All these functions will be available after deviceready event.

// ionic
$ionicPlatform.ready(function() {
  // Empatica-plugin calls
});

// cordova
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
  // Empatica-plugin calls
});

Supported Platform

• iOS (8.0 or greater)
• Android (4.4 or greater) as Empatica Android SDK has minSdkVersion = 19 value in it.

Note You should also change the minSdkVersion value on your project to 19 or greater. Please check whether your android platform has already supported this SDK version. Furthermore, please check also your build-tools version on your Android SDK if you have problems using this plugin.

Installation

• From outside your project directory, clone this repo

git clone -v https://github.com/mjohan/cordova-plugin-empatica-device.git

• Copy Empatica android framework file (empalink-2.1.aar) into src/android/ directory
• Copy Empatica ios framework file (EmpaLink-ios-0.7-full.framework) into src/ios/ directory
• Go to your project directory
• Add the plugin from the repo directory in your computer

cordova plugin add <path_to_the_cloned_repo>

Methods and Constants

initialize

Initializes the plugin with provided API-Key to bind the device. This method must be called before other method calls.

Empatica.initialize('<API_KEY>', success, failure);

Parameters

• <API_KEY>: String value of API_KEY provided by Empatica
• success: Callback function when the initialization process is proceeded
• failure: Callback function when the initialization process is failed

connect

Connects to the Empatica device.

Empatica.connect(success, failure);

Parameters

• success: Callback function when the Empatica device is succesfully connected
• failure: Callback function when the connection is failed

disconnect

Disconnects to the Empatica device.

Empatica.disconnect(success, failure);

Parameters

• success: Callback function when the Empatica device is succesfully disconnected
• failure: Callback function when the disconnection is failed

subscribe

Subscribes to any sensor's update value. This method needs the third param which indicates the sensor type. This param should be assigned with one of Empatica.SENSORS constants.

Empatica.subscribe(success, failure, sensor);

Warning The device is in streaming mode when the connection has been made. This subscribe method is only an interface to get the streamed values. In fact, all sensors values are synched by the device to your app.

Parameters

• success: Callback function if the plugin successfully subscribed to the sensor value
• failure: Callback function if the subscription process is failed
• sensor: Sensor type provided by Empatica.SENSORS constants

unsubscribe

Stops subscribing to a certain sensor type.

Empatica.unsubscribe(success, failure, sensor);

Parameters

• success: Callback function if the plugin successfully unsubscribed to the sensor value
• failure: Callback function if the unsubscription process is failed
• sensor: Sensor type provided by Empatica.SENSORS constants

Constants

These are the supported sensors by Empatica E4 device:

• Empatica.SENSORS.BVP_SENSOR : Blood Volume Pulse
• Empatica.SENSORS.IBI_SENSOR : Inter-Beat Interval
• Empatica.SENSORS.GSR_SENSOR : Galvanic Skin Response
• Empatica.SENSORS.ACC_SENSOR : Accelerometer
• Empatica.SENSORS.TEMP_SENSOR : Temperature
• Empatica.SENSORS.BATTERY_SENSOR : Battery level

Sample

This sample shows how we could subscribe to BVP sensor. After initialization and connect process are succeeded, the progam tries to listen for any BVP update value. The program then stop listening to it after 5 seconds and disconnects the device after 15 seconds.

if (typeof Empatica !== 'undefined') {
  Empatica.initialize('<API_KEY>', function(initializeResult) {
    console.log(JSON.stringify(initializeResult));
    
    Empatica.connect(function(connectResult) {
      console.log(JSON.stringify(connectResult));
      
      // subscribes to BVP sensor
      Empatica.subscribe(function(data) {
        console.log(JSON.stringify(data)); // {"bvp": double_value, "timestamp": double_value}
      }, function (error) {
        console.log(JSON.stringify(error));
      }, Empatica.SENSORS.BVP_SENSOR);
      
      // unsubscribes after 5000 ms
      $interval(function () {
        Empatica.unsubscribe(function(data) {
          console.log(JSON.stringify(data));
        }, function (error) {
          console.log(JSON.stringify(error));
        }, Empatica.SENSORS.BVP_SENSOR);
      }, 5000, 1);
      
      // disconnects after 15000 ms
      $interval(function () {
        Empatica.disconnect(function() {
          console.log("Success disconnect");
        }, function(error) {
          console.log(JSON.stringify(error));
        });
      }, 15000, 1);
    }, function (error) {
      console.log(JSON.stringify(error));
    });
  }, function(error) {
    console.log(JSON.stringify(error));
  });
}

Note subscribe and unsubscribe methods do not need to be put inside connect success-callback.

License

MIT

Feedback

If you find any problems with this plugin, please create an issue or create a pull request.

Credits

• Empatica Android sample project which provides an example for building this plugin.
• Alberto Guarino who gives an iOS project example for connecting a single Empatica device
• cordova-plugin-empatica which indicates that we have to include other frameworks for iOS platform to work
• cordova-plugin-ble-central which gives information about NSBluetoothPeripheralUsageDescription and UIBackgroundModes for iOS platform
• cordova-plugin-msband which gives me an idea to use setKeepCallback method