Using E4 streaming server

Requirements

• Windows 7 or higher with Visual C++ Redistributable Package installed (download from here)
• The E4 streaming server is currently working only with Bluegiga Bluetooth Smart Dongle.
  A driver/installation guide can be downloaded here (registration required)
• Empatica E4 with firmware build 0.0.1.505+ installed (present if E4 bought after May 2015)

Empatica E4s must be registered to the API key owner to be accessible via the E4 streaming server

It is strongly advised to upgrade the Bluegiga Bluetooth Smart Dongle to version 1.6 (1.7 exhibits issues) in order to avoid connection issues. Additionally, the firmware can be modified to allow for a simultaneous connection of up to 7 E4s instead of only 3. For more information see BLE Dongle Firmware Upgrade.

Installation

Download the latest release of the E4 streaming server for Windows from here

Configuration

The first time you start the E4 streaming server the settings need to be adjusted. These are reachable through the button in the upper right corner and contains the following configurations:

• Your Empatica API Key (you can find yours here, if you don't have one check this support article
• The IP address the server bind to and clients have to connect to, e.g. 127.0.0.1
• The port the server is listening on
• Manual BTLE: BTLE connections are established manually
• Autoreconnect BTLE: automatic reconnection of lost BTLE connections

Click the "Apply" button after the configurations are made.

Using the server

Connecting an E4

If the dongle is connected and ready to use, the E4 streaming server will automatically discover and connect to E4 devices within Bluetooth range.

If the dongle is not connected or there is a problem with communication (e.g. missing drivers), the discovery won't start and an indication is given to connect the BLE dongle.

Once the E4 streaming server is discovering, follow these steps to connect an E4:

1. Make sure to keep the E4s not too close to each other and the dongle. The radios can saturate when the antennas are too close, resulting in communication problems.
2. Turn on your E4. The led starts to blink green.
3. After few seconds the E4 is visible in the list, showing the device ID and, once bound, the associated TCP connections.
4. If manual BTLE is disabled, the E4 is automatically connected. Otherwise a button is shown in the "Actions" row to allow for selective connection over BTLE.
5. While the connection is being established, the E4 led turns light blue. Finally, the led turns blue upon successful connection.
6. After around 40 seconds, the led will be turned off in order to save battery.
7. If you want to connect another E4 after the connection is established, then press the "Discover other E4 devices" button and start again from step 1.
8. When you want to stop streaming from a device, simply turn off your E4 and it will be disconnected.

Connecting a TCP Client and Start Receiving Data

The following steps need to be taken in order to start receiving data:

1. A TCP client establishes a connection to the E4 streaming server, using the configured connection parameters.
2. The TCP client binds to a device connected over BTLE through the device_connect command.
3. The bound TCP client subscribes to a channel with the device_subscribe command.

The TCP client will now start receiving the data in the format specified in Data Streaming Packets.

Autoreconnect BTLE

When the Autoreconnect BTLE option is checked, the E4 streaming server will attempt to reconnect to devices that lost BTLE connection. Reasons for connection loss may be obstructions or too long distances between the device and the BTLE dongle, but also devices being turned off through the button. TCP clients that were bound to the reconnected device will continue to receive data according to their subscriptions after reconnection.

Additionally with Autoreconnect BTLE set, devices with a firmware version higher than 1.2.4.x will not turn off after BTLE connection is lost but instead will remain discoverable.

Running the Server from Other Code or Scripts

The E4 streaming server can be run without GUI, passing the connection information and API key as startup arguments:

EmpaticaBLEServer.exe <API_KEY> <SERVER_ADRESS> <SERVER_PORT>

When running the E4 streaming server without GUI, the settings won't be saved and are only active during this execution. Also, BTLE connections have to be handled manually through the commands and automatic reconnection is disabled.

BLE Dongle Firmware Upgrade

The following steps only serve as an outline to upgrade the BLE dongle firmware.
Please refer to this guide to learn about the risks associated with a firmware upgrade and more details of the process.

1. Download and install Bluetooth Smart Software and SDK version 1.6 (download from here, registration required).
2. OPTIONAL: create a modified firmware to allow for simultaneous connection of up to 7 E4s
   1. in the installation folder copy the contents of the usbcd example project (example/dkble112/usbcdc) to bin/
   2. in the file config.xml change connections value field to 7
   3. open a cmd prompt in bin/ and run blegui2.exewith the .bgproj file as argument to build a new firmware .hex file
3. running blegui2.exe, flash the modified firmware or the firmware from the usbcd example project (example/dkble112/usbcdc)

Troubleshooting

Please try to insert again your API Key (you can find your API key here).
If you have still the issue, please contact our support

Try to follow these steps in order to get your E4 connected:

• Launch the E4 streaming server
• Check that the dongle is connected (you should see a "Dongle connected" text) at the bottom of the app's window
• Click the "Start" button
• Turn on your E4

If the E4 streaming server can't connect to your E4 before memory mode starts and the led turns red, please contact our support writing us your Api key and the serial number of the device you're using. You can find the serial number on the E4 close to sensor's led.