-
Notifications
You must be signed in to change notification settings - Fork 3
/
windows-streaming-server-commands.html
438 lines (344 loc) · 20.5 KB
/
windows-streaming-server-commands.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<title>Message Protocol</title>
<meta name="description" content="E4 streaming server allows to receive realtime data from multiple Empatica E4 devices.">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="highlight/styles/github.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/github-dark.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print">
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<!-- Favicon -->
<link rel="icon" href="//static-content1.empatica.com/YaJqf/img/favicon.png" type="image/png">
<link rel="apple-touch-icon" href="//static-content1.empatica.com/YaJqf/img/favicon.png">
<link href="//static-content1.empatica.com/YaJqf/img/favicon.png" rel="shortcut icon" type="image/x-icon">
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-25632719-2', 'auto');
ga('require', 'linkid', 'linkid.js');
ga('require', 'displayfeatures');
ga('send', 'pageview');
</script>
<script src="highlight/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
</head>
<body>
<div id="container">
<div class="inner">
<header>
<p><a href="/">E4 for Developers</a> > <a href="windows-streaming-server.html">E4 streaming server</a> > Message Protocol</p>
<h1>Message Protocol</h1>
<h2>and Command Structure</h2>
<h6>Updated January, 2019</h6>
</header>
<section id="main_content">
<h3>
General Message Structure
</h3>
<p>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.</p>
<p>Client requests are in the following format</p>
<p><code><COMMAND> <ARGUMENT_LIST></code></p>
<div class="example">
Example:<br/>
<code class="shell">device_subscribe gsr ON</code>
</div>
<p></p>
<p>Messages from server containing <strong>responses to commands</strong> are in the following format</p>
<p><code><COMMAND> <ARGUMENT_LIST></code></p>
<div class="example">
Example:<br/>
<code class="shell">R device_subscribe acc ON</code>
</div>
<p></p>
<p>Messages from server containing data from device are in the following format</p>
<p><code><STREAM_TYPE> <TIMESTAMP> <DATA></code></p>
<div class="example">
Example:<br/>
<code class="shell">G 123345627891.123 3.129</code>
</div>
<p></p>
<h3>
Commands and Responses Details
</h3>
<h4>
List of Discovered BTLE Devices (Manual BTLE)
</h4>
<p></p>
<p>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 <strong>Manual BTLE</strong> is not set, this command is not needed since discovery and connection over BTLE are handled automatically.</p>
Client Request:
<p><code>device_discover_list</code></p>
Server Response:
<p><code>R device_discover_list <NUMBER_OF_DEVICES> | <DEVICE_INFO_1> | <DEVICE_INFO_2> | ...</code></p>
<div class="example">
Example:<br/>
<code class="shell">R device_discover_list 2 | 9ff167 Empatica_E4 allowed | 740163 Empatica_E4 not_allowed</code>
</div>
<p></p>
<p>The format of the device info is the following:</p>
<p><code><DEVICE_ID> <DEVICE_NAME> <API_KEY_PERMISSION></code></p>
<div class="example">
Example:<br/>
<code class="shell">9ff167 Empatica_E4 allowed</code>
</div>
<p></p>
<p>The strings <strong>allowed</strong> and <strong>not_allowed</strong> indicate if the devices are allowed to be used with the given API key.</p>
<h4>
Connect Device over BTLE (Manual BTLE)
</h4>
<p></p>
<p>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 <strong>Manual BTLE</strong> is not set, this command is not needed since discovery and connection over BTLE are handled automatically.</p>
<p>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 <strong>Autoreconnect BTLE</strong> is set, otherwise there will be no timeout.</p>
<p>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.</p>
Client Request:
<p><code>device_connect_btle <DEVICE_ID> [<TIMEOUT>]</code></p>
<div class="example">
Example:<br/>
<code class="shell">device_connect_btle 9ff167 208</code>
</div>
<p></p>
Server Response:
<p>
<code>R device_connect_btle OK</code><br/>
<code>R device_connect_btle ERR <reason></code>
</p>
<div class="example">
Example:<br/>
<code class="shell">R device_connect_btle ERR The device has not been discovered yet</code>
</div>
<p></p>
<h4>
Disconnect Device from BTLE
</h4>
<p></p>
<p>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.</p>
Client Request:
<p><code>device_disconnect_btle <DEVICE_ID></code></p>
<div class="example">
Example:<br/>
<code class="shell">device_disconnect_btle 9ff167</code>
</div>
<p></p>
Server Response:
<p>
<code>R device_disconnect_btle OK</code><br/>
<code>R device_disconnect_btle ERR <reason></code>
</p>
<div class="example">
Example:<br/>
<code class="shell">R device_disconnect_btle ERR The device is not connected over btle</code>
</div>
<p></p>
<h4>
List of Devices Connected over BTLE
</h4>
<p></p>
<p>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.</p>
Client Request:
<p><code>device_list</code></p>
Server Response:
<p><code>R device_list <NUMBER_OF_DEVICES> | <DEVICE_INFO_1> | <DEVICE_INFO_2></code></p>
<div class="example">
Example:<br/>
<code class="shell">R device_list 2 | 9ff167 Empatica_E4 | 740163 Empatica_E4</code>
</div>
<p></p>
<p>The format of the device info is the following:</p>
<p><code><DEVICE_ID> <DEVICE_NAME></code></p>
<div class="example">
Example:<br/>
<code class="shell">9ff167 Empatica_E4</code>
</div>
<p></p>
<h4 id="connect-device">
Connect to a Device
</h4>
<p></p>
<p>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 <a href="#subscribe-receive-data">device_subscribe</a> command in order to start receiving data.</p>
<p>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.</p>
Client Request:
<p><code>device_connect <DEVICE_ID></code></p>
<div class="example">
Example:<br/>
<code class="shell">device_connect 9ff167</code>
</div>
<p></p>
Server Response:
<p>
<code>R device_connect OK</code><br/>
<code>R device_connect ERR <reason></code>
</p>
<div class="example">
Example:<br/>
<code class="shell">R device_connect ERR The device requested for connection is not available.</code>
</div>
<p></p>
<h4>
Disconnect from a Device
</h4>
<p></p>
<p>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.</p>
Client Request:
<p><code>device_disconnect</code></p>
Server Response:
<p>
<code>R device_disconnect OK</code><br/>
<code>R device_disconnect ERR <reason></code>
</p>
<div class="example">
Example:<br/>
<code class="shell">R device_disconnect ERR No connected device.</code>
</div>
<p></p>
<h4 id="subscribe-receive-data">
Subscribe and Unsubscribe to Data Stream
</h4>
<p></p>
<p>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 <a href="#connect-device">device_connect</a> command.</p>
<p>Subscriptions persist independent of the BTLE connection status of the device.</p>
Client Request:
<p><code>device_subscribe <STREAM> <STATUS></code></p>
<div class="example">
Example:<br/>
<code class="shell">device_subscribe gsr ON</code>
</div>
<p></p>
Server Response:
<p>
<code>R device_subscribe <STREAM> <STATUS></code><br/>
<code>R device_subscribe <STREAM> ERR <REASON></code>
</p>
<div class="example">
Example:<br/>
<code class="shell">R device_subscribe gsr OK</code>
</div>
<p></p>
<p>To subscribe to a stream specify <strong>ON</strong> and to unsubscribe <strong>OFF</strong>.</p>
<strong>STREAM SUBSCRIPTIONS</strong>
<p>The available stream subscriptions are:</p>
<ul>
<li>acc - 3-axis acceleration</li>
<li>bvp - Blood Volume Pulse</li>
<li>gsr - Galvanic Skin Response</li>
<li>ibi - Interbeat Interval and Heartbeat</li>
<li>tmp - Skin Temperature</li>
<li>bat - Device Battery</li>
<li>tag - Tag taken from the device (by pressing the button)</li>
</ul>
<p></p>
<h4>
Suspend and Resume Data Streaming
</h4>
<p></p>
<p>To temporarily suspend and resume the data streaming (without disconnecting or turning off the device), the client sends a pause requests</p>
Client Request:
<p><code>pause <STATUS></code></p>
<div class="example">
Example:<br/>
<code class="shell">pause ON</code>
</div>
<p></p>
Server Response:
<p><code>R pause <STATUS></code><br/>
<code>R pause ERR <REASON></code></p>
<div class="example">
Example:<br/>
<code class="shell">R pause ERR You are not connected to any device</code>
</div>
<p></p>
<p>To pause the stream specify <strong>ON</strong> and to resume <strong>OFF</strong>.</p>
<h3>System Messages</h3>
<p></p>
<p>In certain events the E4 streaming server sends an informative system message to the TCP connections.</p>
<h4>
BTLE Connection Lost
</h4>
<p></p>
<p>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.</p>
Server Message:
<p><code>R connection lost to device <DEVICE_ID></code></p>
<div class="example">
Example:<br/>
<code class="shell">R connection lost to device 9ff167</code>
</div>
<p></p>
<h4>
BTLE Connection Re-Established
</h4>
<p></p>
<p>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 <strong>Autoreconnect BTLE</strong> and of how the BTLE connection to the device was dropped.</p>
Server Message:
<p><code>R connection re-established to device <DEVICE_ID></code></p>
<div class="example">
Example:<br/>
<code class="shell">R connection re-established to device 9ff167</code>
</div>
<p></p>
<h4>
Device Turned Off
</h4>
<p></p>
<p>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.</p>
Server Message:
<p><code>R device <DEVICE_ID> turned off via button</code></p>
<div class="example">
Example:<br/>
<code class="shell">R device 9ff167 turned off via button</code>
</div>
<p></p>
<h3 id="protocol-example">Protocol Example (no Manual BTLE)</h3>
<p></p>
<pre>[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]</pre><p></p>
<h3>Protocol Example (Manual BTLE)</h3>
<p></p>
<pre>[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]</pre>
<footer>
<p>Having trouble with Empatica E4 software for Developers? <a href="mailto:[email protected]">Contact Support</a> and we’ll help you sort it out.</p>
</footer>
</section>
</div>
</div>
</body>
</html>