From af792ec82339b40dc4167c6c1a203954ad6087ac Mon Sep 17 00:00:00 2001 From: Johann Wolf Date: Fri, 25 May 2018 12:14:41 +0200 Subject: [PATCH 01/10] extend documentation with Autoreconnect BTLE, disconnect command and further explanations --- windows-streaming-server-commands.html | 35 ++++++++++++++++++++++---- windows-streaming-server-usage.html | 25 ++++++++++++++++-- 2 files changed, 53 insertions(+), 7 deletions(-) diff --git a/windows-streaming-server-commands.html b/windows-streaming-server-commands.html index 5ce16af..05dbc6e 100644 --- a/windows-streaming-server-commands.html +++ b/windows-streaming-server-commands.html @@ -143,6 +143,31 @@

R device_connect_btle ERR The device has not been discovered yet

+ +

+ Disconnect Device from BTLE +

+

+ +

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

+
+ Example:
+ device_disconnect_btle 9ff167 +
+

+ Server Response: +

+ R device_disconnect_btle OK
+ R device_disconnect_btle ERR <reason> +

+
+ Example:
+ R device_disconnect_btle ERR The device is not connected over btle +
+

List of Devices Connected over BTLE @@ -175,9 +200,8 @@

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

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 client remains bound to the device regardless of the status of the BTLE connection.

Client Request:

device_connect <DEVICE_ID>

@@ -202,7 +226,7 @@

-

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. It 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

@@ -222,7 +246,8 @@

-

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>

diff --git a/windows-streaming-server-usage.html b/windows-streaming-server-usage.html index 8423817..767fd52 100644 --- a/windows-streaming-server-usage.html +++ b/windows-streaming-server-usage.html @@ -81,6 +81,7 @@

  • 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

    • @@ -89,7 +90,9 @@

    Using the server

    - + +

    Connecting an E4

    +

    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.

    @@ -113,7 +116,25 @@

  • When you want to stop streaming from a device, simply switch 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. +
    2. The TCP client binds to a device connected over BTLE through the device_connect command.
      3. +
    3. The bound TCP client subscribes to a channel with the device_subscribe command.
      4. +
    + +

    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.

    +

    Running the Server from Other Code or Scripts

    @@ -126,7 +147,7 @@

    -

    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.

    Troubleshooting From a9b39319ef7e0eac9dcc5f5ff2eb3a679625757b Mon Sep 17 00:00:00 2001 From: Johann Wolf Date: Fri, 25 May 2018 17:47:54 +0200 Subject: [PATCH 02/10] add information on system messages (device connection lost, device reconnected) --- windows-streaming-server-commands.html | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/windows-streaming-server-commands.html b/windows-streaming-server-commands.html index 05dbc6e..127373d 100644 --- a/windows-streaming-server-commands.html +++ b/windows-streaming-server-commands.html @@ -310,6 +310,44 @@

    To pause the stream specify ON and to resume OFF.

    + + +

    System Messages

    +

    + +

    In certain events the E4 streaming server sends an informative system message to the TCP clients.

    + +

    + BTLE Connection Lost +

    +

    + +

    When the E4 streaming server loses connection to a device over BTLE, a disconnection message is sent to all TCP clients that are bound to the device.

    + + Server Message: +

    R connection lost to device <DEVICE_ID>

    +
    + Example:
    + R connection lost to device 9ff167 +
    +

    + + +

    + BTLE Connection Re-Established +

    +

    + +

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

    +
    + Example:
    + R connection re-established to device 9ff167 +
    +

    +

    Protocol Example (no Manual BTLE)

    From 4dfc04b82389760da5f078ddf0dc17117a43d871 Mon Sep 17 00:00:00 2001 From: Johann Wolf Date: Fri, 8 Jun 2018 10:49:23 +0200 Subject: [PATCH 03/10] add information on changing device binding when BTLE connection lost --- windows-streaming-server-commands.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/windows-streaming-server-commands.html b/windows-streaming-server-commands.html index 127373d..9e51104 100644 --- a/windows-streaming-server-commands.html +++ b/windows-streaming-server-commands.html @@ -201,7 +201,7 @@

    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 client remains bound to the device regardless of the status of the BTLE connection.

    +

    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 client remains bound to the device regardless of the status of the BTLE connection. However, if the device has lost BTLE connectivity, only then TCP client 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>

    From b3775696c7af07608b1e98b969a0cb70e531627c Mon Sep 17 00:00:00 2001 From: Johann Wolf Date: Fri, 8 Jun 2018 10:52:31 +0200 Subject: [PATCH 04/10] use "TCP connection" instead of "TCP client" to for a better understanding of 1 device per TCP connection --- windows-streaming-server-commands.html | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/windows-streaming-server-commands.html b/windows-streaming-server-commands.html index 9e51104..ee65d02 100644 --- a/windows-streaming-server-commands.html +++ b/windows-streaming-server-commands.html @@ -201,7 +201,7 @@

    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 client remains bound to the device regardless of the status of the BTLE connection. However, if the device has lost BTLE connectivity, only then TCP client 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.

    +

    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>

    @@ -315,14 +315,14 @@

    System Messages

    -

    In certain events the E4 streaming server sends an informative system message to the TCP clients.

    +

    In certain events the E4 streaming server sends an informative system message to the TCP connections.

    BTLE Connection Lost

    -

    When the E4 streaming server loses connection to a device over BTLE, a disconnection message is sent to all TCP clients that are bound to the device.

    +

    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>

    @@ -338,7 +338,7 @@

    -

    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 clients 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.

    +

    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>

    From 84d0f4fdb3c7a20f4fff5c88a6851c25f0bf6a0e Mon Sep 17 00:00:00 2001 From: Johann Wolf Date: Fri, 8 Jun 2018 17:07:10 +0200 Subject: [PATCH 05/10] add link to sample code --- windows-streaming-server.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/windows-streaming-server.html b/windows-streaming-server.html index 57a13be..43f9e26 100644 --- a/windows-streaming-server.html +++ b/windows-streaming-server.html @@ -66,7 +66,8 @@

    Getting Started

    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.