Empatica BLE Server for Windows (Beta)

This is a reference guide for the communication protocol supported by the Empatica TCP Server.

Empatica TCP server allows to receive realtime data from multiple Empatica E4 devices.

Please note that for each TCP connection it is allowed to connect one Empatica Device at time. To connect to multiple devices, multiple TCP connections are required. The server accepts TCP sockets connections.

After a succesful connection from a client, the server waits for command messages.

The general message structure is described in the following section, while details on the client commands and server responses are described in the commands and data section.

To get a glance of the communication protocol, visit the protocol example section.

General message structure

Messages are ASCII strings terminated with a newline (in Windows '\r\n') character. Some commands have parameters, which are separated by spaces.

Client requests are in the following format:

	Client request format
		<COMMAND> <ARGUMENT_LIST>
	Example
		device_subscribe gsr ON
	

Messages from server containing responses to commands are in the following format:

	Server responses
		R <COMMAND> <ARGUMENT_LIST>
	Example
		R device_subscribe acc ON
	

Messages from server containing data from device are in the following format:

	Stream Data Format
		<STREAM_TYPE> <TIMESTAMP> <DATA>
	Example
		G 123345627891.123 3.129
	

Commands and Responses Details

Server status

The client requires the current status of the server. The server status is OK when the server is fully functional and ready to connect to Empatica E4 devices. The server status is ERR if something is wrong (often, problems are related to Bluetooth low energy adapter).

Possible server status:

Client Request
	server_status

Server Response
	R server_status OK
	R server_status ERR <reason>
Example:
	R server_status ERR Bluetooth low energy not available on server`

List of available devices

The client requires the list of Empatica E4 devices in range and available for connection. The server responds with the number of available devices and a list of devices info.

Client Request
	device_list

Server Response
	R device_list <NUMBER_OF_DEVICES> | <DEVICE_INFO_1> | <DEVICE_INFO_2>
Example
	R device_list 2 | 9ff167 Empatica_E4 available | 740163 Empatica_E4 available

The format of the device info is the following:

DEVICE_INFO format
	<DEVICE_ID> <DEVICE_NAME> <AVAILABILITY>
Example
	9ff167 Empatica E4 available

The device id is unique for every device. It is used by the client during a connect request.

The device name being used.

Availability parameter is always available. Other values are reserved for future implementation.

Connect to a Device

1. The client sends a connection request to a specific device.
2. Each TCP connection is allowed to connect to one Empatica Device at time.
3. To connect to multiple devices, multiple TCP connections are required.

Client Request
	device_connect <DEVICE_ID>
Example:
device_connect 9ff167

The device id is returned from the server after a device_list command.

Server Response
	R device_connect OK
	R device_connect ERR <reason>
Example:
	R device_connect ERR The device requested for connection is not available.

Disconnect from a Device

The client sends a device disconnection request. It will be disconnected from the currently connected device.

Client Request
	device_disconnect

Server Response
	R device_disconnect OK
	R device_disconnect ERR <reason>
Example:
	R device_disconnect ERR No connected device.

In case of device disconnection (e.g., the user switch off the device, or the battery runs out) the server sends the following packet

Device Disconnection
	X device_disconnect

Subscribe to Receive Data

To start receiving data from a given stream, the client sends a data subscription request specifying the desired stream.

Client Request
	device_subscribe <STREAM> ON
Example:
	device_subscribe gsr ON

Server Response
	R device_subscribe <STREAM> ON
	R device_subscribe <STREAM> ERR <REASON>
Example:
	R device_subscribe gsr OK

The streams available are the following:

Unsubscribe from Receive Data

To stop receiving data from a given stream, the client sends a data unsubscription request specifying the desired stream.

Client Request
	device_subscribe <STREAM> OFF
Example:
	device_subscribe gsr OFF`

Server Response
	R device_subscribe <STREAM> OFF
	R device_subscribe <STREAM> ERR <REASON>
Example:
	R device_subscribe gsr OFF

The streams available are the following:

Suspend data streaming

To temporarily suspend the data streaming (without disconnecting or switching off the device), the client sends a pause request

Client Request
	pause ON

Server Response
	R pause ON
	R pause ERR <REASON>
Example:
	R pause ERR You are not connected to any device`

Resume data streaming

To resume the data streaming, the client sends a resume request

Client Request
	pause OFF

Server Response
	R pause OFF
	R pause ERR <REASON>
Example:
	R pause ERR You are not connected to any device

Data Streaming Packets

After a succesful connection and stream subscription to an Empatica Device, the client starts receiving sensor's data from the server.

Stream Data Format
	<STREAM_TYPE> <TIMESTAMP> <DATA>
Example
	G 123345627891.123 3.129

The streams available are the following:

The timestamp for the sample in seconds defined as time interval between the sample received and the reference date, 1 January 1970, GMT.

Each stream type has different data format as described below:

Acceleration data
	E4_Acc 123345627891.123 51 -2 -10

Blood Volume Pulse data

The value of the BVP sample. The value is derived from the light absorbance of the arterial blood. The raw signal is filtered to remove movement artifacts.

Blood Volume Pulse data
	E4_Bvp 123345627891.123 31.128

Galvanic Skin Response data

The value of the GSR sample. The value is expressed in microsiemens.

Galvanic Skin Response data
	E4_Gsr 123345627891.123 3.129`

Temperature data

The value of the temperature sample in Celsius degrees. The value is derived from the optical temperature sensor placed on the wrist.

Temperature data
	E4_Temperature 123345627891.123 35.82`

Interbeat Interval data

The value of the IBI sample. The value is the distance from the previous detected heartbeat in seconds.

Interbeat Interval data
	E4_Ibi 123345627891.123 0.822

Battery level data

The battery level of the device. Values: [0.0 - 1.0]

Battery level data
E4_Battery 123345627891.123 0.2

Tag data

The tags taken from the device

Battery level data
E4_Tag 123345627891.123

Protocol Example

Please find below an example of messages exchange between client and server during a brief acquisition session.

[OPEN TCP CONNECTION]
==> server_status
<== R server_status OK

==> device_list
<== R device_list 2 | 9ff167 Empatica E4 available | 7a3166 Empatica E4 available

==> device_connect ffffff
<== R device_connect ERR the requested device is not available

==> device_connect 9ff167
<== R device_connect OK

==> device_subscribe bvp ON
<== R device_subscribe bvp OK

<== B 123345627891.123 3.212
<== B 123345627891.327 10.423
<== B 123345627891.472 12.665

==> device_disconnect
<== R device_disconnect OK
[EOF]

Using Empatica BLE Server for Windows (Beta)

NOTE: this part of the documentation is still under development

Requirements

Installation

Download the latest release of the Empatica BLE Server for Windows (Beta) from here

Configuration

The first time you start the server, you will see the settings panel that allows you to set:

After configuration set click the "Save" button.

Using the server

You will see the default view of the server, click the "Start" button.

If the dongle is not connected (or your PC can't communicate with it, i.e. because you didn't install the dongle's drivers), the discovery won't start and the message "Dongle not connected" is displayed at the bottom.

If the dongle was not connected, plug it to your PC and press the "Refresh" button placed in the bottom left corner of the app.

If the dongle is connected, the server will start:

1. Discovery and connection to the E4 device within Bluetooth range and will start listening to commands on the address and port specified in the settings panel.
2. You can see the label under the button that tells that the app is discovering for E4.
3. You can now switch on your E4 and the led will start to blink green.

After a while (around 40 seconds), the led will be switched off in order to save battery. When any device is connected, the device ID and the list of the current TCP connections are displayed.

When you want to stop streaming from a device, simply switch off your E4 and it will be disconnected from the app.

If you want to connect another E4 device, wait when the previous E4 is connected, then press the "Discover other E4 devices" button, the app will start to discover other devices.

Make sure to keep the devices not too close because the radios might saturate when the antennas are too close, resulting in lack of communication over-the-air.

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:

If the app can't connect to your E4 before the led becomes red (and memory mode starts) please contact our support writing us your Api key and the serial number of the device you're using (placed close to sensor's led)