Messages are ASCII strings terminated with a newline (in Windows '\r\n') character. Some commands have parameters, which are separated by spaces.
+Messages are ASCII strings terminated with a newline (in Windows '\r\n') character and encoded with UTF-8. Some commands have parameters, which are separated by spaces.
Client requests are in the following format
@@ -95,7 +95,7 @@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.
+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 Manual BTLE is not set, this command is not needed since discovery and connection over BTLE are handled automatically.
Client Request:device_discover_list
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.
+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 if allowed by the API key. If Manual BTLE is not set, this command is not needed since discovery and connection over BTLE are handled automatically.
+ +An optional parameter can be specified, that defines a timeout for BTLE discovery after an accidental disconnection (e.g. device out of range). The device will stay on and be discoverable over BTLE for the specified amount of time. The timeout is an integer number defined in minutes and can be in the range 0-254, where 0 specifies an infinite timeout. If the optional parameter is left out there will be an infinite timeout if Autoreconnect BTLE is set, otherwise there will be no timeout.
+The optional timeout parameter only takes effect for devices with a firmware version higher than 1.2.4.x. Devices with lower firmware versions will automatically turn off after an accidental disconnection.
Client Request: -device_connect_btle
device_connect_btle <DEVICE_ID> [<TIMEOUT>]
device_connect_btle 9ff167
+ device_connect_btle 9ff167 208
R device_connect_btle ERR The device has not been discovered yet
The client sends a BTLE disconnection request for a specific device. The server will disconnect the device from BTLE. This command terminates active connections as well as stops reconnection attempts to devices that have temporarily lost BTLE connection.
+ + Client Request: +device_disconnect_btle <DEVICE_ID>
device_disconnect_btle 9ff167
+
+ R device_disconnect_btle OK
+ R device_disconnect_btle ERR <reason>
+
R device_disconnect_btle ERR The device is not connected over btle
+ The client sends a connection request to a specific device. The E4 streaming server binds the client connected by TCP to the device connected over BTLE. The bound client needs to subscribe to channels with the device_subscribe command in order to start receiving data.
+Each TCP connection is allowed to connect to one Empatica Device at a time. To receive data from multiple devices, multiple TCP connections are required. The TCP connection remains bound to the device regardless of the status of the BTLE connection. However, if the device has lost BTLE connectivity, only then TCP connection has the possibility to bind to another E4 using the "device_connect" connection request. In this case the previous device will be unbound and subscriptions will be cleared.
Client Request:device_connect <DEVICE_ID>
The client sends a device disconnection request. It will be disconnected from the currently connected device and close the TCP connection.
+The client sends a device disconnection request. The client will be disconnected from the currently connected device and close the TCP connection to the E4 streaming server. The device will remain connected to the E4 streaming server over BTLE.
Client Request:device_disconnect
To start or stop receiving data from a given stream, the client sends a data subscription requests specifying the desired stream.
+To start or stop receiving data from a given stream, the client sends a data subscription requests specifying the desired stream. The client needs to be first bound to a device with the device_connect command.
+Subscriptions persist independent of the BTLE connection status of the device.
Client Request:device_subscribe <STREAM> <STATUS>
To temporarily suspend and resume the data streaming (without disconnecting or switching off the device), the client sends a pause requests
+To temporarily suspend and resume the data streaming (without disconnecting or turning off the device), the client sends a pause requests
Client Request:pause <STATUS>
To pause the stream specify ON and to resume OFF.
+ + +In certain events the E4 streaming server sends an informative system message to the TCP connections.
+ +When the E4 streaming server loses connection to a device over BTLE, a disconnection message is sent to all TCP connections that are bound to the device.
+ + Server Message: +R connection lost to device <DEVICE_ID>
R connection lost to device 9ff167
+ When a previously connected device is connected again over BTLE to the E4 streaming server, a connection re-established message is sent to all TCP connections that are bound to the device. This message is sent independent of the setting Autoreconnect BTLE and of how the BTLE connection to the device was dropped.
+ + Server Message: +R connection re-established to device <DEVICE_ID>
R connection re-established to device 9ff167
+ When a device is turned off by pressing the button, a device turned off message is sent to all TCP connections that are bound to the device. This message is only sent for devices with a firmware version higher than 1.2.4.x.
+ + Server Message: +R device <DEVICE_ID> turned off via button
R device 9ff167 turned off via button
+ It is strongly advised to upgrade the Bluegiga Bluetooth Smart Dongle with the newest firmware 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.
+You will see the default view of the server, click the "Start" button.
If the dongle is not connected or there is a problem with communication, (i.e. missing drivers), the discovery won't start and the message "Dongle not connected" is displayed at the bottom.
@@ -104,16 +109,36 @@A text below the button tells you that the app is discovering E4s. Follow these steps to connect an E4:
The following steps need to be taken in order to start receiving data:
+ +The TCP client will now start receiving the data in the format specified in Data Streaming Packets.
+ +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.
+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.
+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.
+ +
+ 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.
+
Bluetooth Smart Software and SDK (download from here, registration required).example/dkble112/usbcdc) to bin/bin/ and run blegui2.exewith the .bgproj file as argument to build a new firmware .hex fileblegui2.exe, flash the modified firmware or the firmware from the usbcd example project (version 1.6.0: example/dkble112/usbcdc)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.
diff --git a/windows-streaming-server.html b/windows-streaming-server.html index 434f53e..e715e07 100644 --- a/windows-streaming-server.html +++ b/windows-streaming-server.html @@ -71,7 +71,8 @@To find out how a connected TCP client communicates with the E4 streaming server, please refer to the page Message Protocol. There you will also find a protocol example.
The message structure of the live data is described on the page Data Streaming Packets.
- + +Sample client C# code can be found in this github repository.