E4 for Developers > E4 streaming server > Message Protocol

Message Protocol

and Command Structure

Updated May, 2018

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

<COMMAND> <ARGUMENT_LIST>

Example:
device_subscribe gsr ON

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

<COMMAND> <ARGUMENT_LIST>

Example:
R device_subscribe acc ON

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

<STREAM_TYPE> <TIMESTAMP> <DATA>

Example:
G 123345627891.123 3.129

Commands and Responses Details

List of Discovered BTLE Devices (Manual BTLE)

The client requests the list of Empatica E4 devices, that are in range and not connected over BTLE. The server responds with the number of discovered devices and a list of device info. If the E4 streaming server is not configured with manual BTLE, this command is not needed since discovery and connection over BTLE are handled automatically.

Client Request:

device_discover_list

Server Response:

R device_discover_list <NUMBER_OF_DEVICES> | <DEVICE_INFO_1> | <DEVICE_INFO_2> | ...

Example:
R device_discover_list 2 | 9ff167 Empatica_E4 allowed | 740163 Empatica_E4 not_allowed

The format of the device info is the following:

<DEVICE_ID> <DEVICE_NAME> <API_KEY_PERMISSION>

Example:
9ff167 Empatica_E4 allowed

The strings allowed and not_allowed indicate if the devices are allowed to be used with the given API key.

Connect Device over BTLE (Manual BTLE)

The client sends a BTLE connection request for a specific device. The server will connect to the device over BTLE if it has been discovered and allowed by the API key. If the E4 streaming server is not configured with manual BTLE, this command is not needed since discovery and connection over BTLE are handled automatically.

Client Request:

device_connect_btle

Example:
device_connect_btle 9ff167

Server Response:

R device_connect_btle OK
R device_connect_btle ERR <reason>

Example:
R device_connect_btle ERR The device has not been discovered yet

List of Devices Connected over BTLE

The client requests the list of Empatica E4 devices that are in range and connected over BTLE. The server responds with the number of connected devices and a list of device 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 | 740163 Empatica_E4

The format of the device info is the following:

<DEVICE_ID> <DEVICE_NAME>

Example:
9ff167 Empatica_E4

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 a time.
  3. To connect to multiple devices, multiple TCP connections are required.
Client Request:

device_connect <DEVICE_ID>

Example:
device_connect 9ff167

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 and close the TCP connection.

Client Request:

device_disconnect

Server Response:

R device_disconnect OK
R device_disconnect ERR <reason>

Example:
R device_disconnect ERR No connected device.

Subscribe and Unsubscribe to Data Stream

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

Client Request:

device_subscribe <STREAM> <STATUS>

Example:
device_subscribe gsr ON

Server Response:

R device_subscribe <STREAM> <STATUS>
R device_subscribe <STREAM> ERR <REASON>

Example:
R device_subscribe gsr OK

To subscribe to a stream specify ON and to unsubscribe OFF.

STREAM

The available streams available are:

  • acc - 3-axis acceleration
  • bvp - Blood Volume Pulse
  • gsr - Galvanic Skin Response
  • ibi - Interbeat Interval and Heartbeat
  • tmp - Skin Temperature
  • bat - Device Battery
  • tag - Tag taken from the device (by pressing the button)

Suspend and Resume Data Streaming

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

Client Request:

pause <STATUS>

Example:
pause ON

Server Response:

R pause <STATUS>
R pause ERR <REASON>

Example:
R pause ERR You are not connected to any device

To pause the stream specify ON and to resume OFF.

Protocol Example (no Manual BTLE)

[OPEN TCP CONNECTION]

  ==>  device_list
  <==  R device_list 2 | 9ff167 Empatica_E4 | 7a3166 Empatica_E4

  ==>  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

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

  ==>  device_disconnect
  <==  R device_disconnect OK

[EOF]

Protocol Example (Manual BTLE)

[OPEN TCP CONNECTION]

  ==>  device_list
  <==  R device_list 0

  ==>  device_discover_list
  <==  R device_list 2 | 9ff167 Empatica_E4 allowed | 7a3166 Empatica_E4 not_allowed

  ==>  device_connect_btle 7a3166
  <==  R device_connect_btle ERR The device is not registered with the API key

  ==>  device_connect_btle 9ff167
  <==  R device_connect_btle OK

  ==>  device_list
  <==  R device_list 1 | 9ff167 Empatica_E4

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

  ==>  device_subscribe acc ON
  <==  R device_subscribe acc OK

  <==  E4_Acc 123345627891.123 51 -2 -10
  <==  E4_Acc 123345627891.327 60 -8 -12
  <==  E4_Acc 123345627891.472 55 -16 -1

  ==>  device_disconnect
  <==  R device_disconnect OK

[EOF]