< back to Empatica for Developers

Empatica Android SDK

Introduction and requirements

The EmpaLink API allows you to build Android applications that can communicate with Empatica E4 and Empatica E3 devices.

First of all, you need to make sure your phone runs Android 4.4 KitKat (API level 19) or higher. Android 4.3 doesn't offer a stable enough connection, while previous versions don't support Bluetooth 4.0 (BLE) at all, and, therefore, are not compatible with the Empatica API.

This release is meant to be used with Android Studio 2.2 or later.

Once equipped with a supported phone, you need to navigate to Empatica Connect Developer Area and request to become a developer. You will find your API key and all the download links there.

Dependencies

EmpaLink has the following dependency:

  • Ok HTTP Client - version 2.5.0
  • Installation instructions

    1. Download the SDK from Empatica Connect Developer Area

    2. Open your project in Android Studio

    3. Open your main build.gradle (project root) and change the trailing lines to:

    4.   allprojects {
          repositories {
            jcenter()
            flatDir {
              dirs 'libs'
            }
          }
        }
      
    5. Copy empalink-2.1.aar in the folder libs in the app folder (or in the folder with the name of your app). If the folder doesn't exist, create it.

    6. Open your app build.gradle and, in the dependencies { ... } block, add the following line:

       compile 'com.squareup.okhttp:okhttp:2.5.0'
       compile 'com.empatica.empalink:empalink:2.1@aar'
      
    7. Make sure your build.gradle has a minSdkVersion 19 (or higher) line

    Usage

    First of all, you need to instantiate an EmpaDeviceManager, passing your application context, and references to classes implementing EmpaDataDelegate and EmpaStatusDelegate.

    Then, you must register your API Key using the Device Manager's authenticateWithAPIKey() method.

    Here's an example:

    public class MainActivity extends Activity implements EmpaDataDelegate, EmpaStatusDelegate {
    
              private EmpaDeviceManager deviceManager;
              protected void onCreate(Bundle savedInstanceState) {
                  [...]
                  deviceManager = new EmpaDeviceManager(getApplicationContext(), this, this);
                  deviceManager.authenticateWithAPIKey("YOUR API KEY");
              }
                [...]
            }

    When the Device Manager is ready for use, your EmpaStatusDelegate will receive the EmpaStatus.READY value via didUpdateStatus().

    The Device Manager is now ready to scan for Empatica Devices, using: deviceManager.startScanning().

    If any devices are in range, you will receive them through the EmpaStatusDelegate callback didDiscoverDevice(BluetoothDevice device, String deviceLabel, int rssi, boolean allowed).

    If allowed is true, you can then connect to the device as follows: deviceManager.connectDevice(device).

    If the connection request is successful, the device will start streaming data, which will be transferred to your EmpaDataDelegate by invoking its callback methods.

    Additional info

    Please check the Javadoc documentation for details about all the available methods.