Commit 8f508b3f authored by Andres Heinloo's avatar Andres Heinloo

Update protocol.rst

parent 861bf1a0
......@@ -20,8 +20,8 @@ Therefore the core protocol is kept very small and a number of optional
"capabilities" are defined.
A SeedLink session starts with opening the TCP/IP connection and ends with
closing the TCP/IP connection. During the session the following steps are
performed in order:
closing the TCP/IP connection. During the session, the following steps are
performed:
* Opening the connection
* Handshaking
......@@ -30,7 +30,8 @@ performed in order:
.. |4| unicode:: 0x2463
New features of SeedLink v4 are marked with |4| in the following text.
Features related to a certain capability are marked with {CAP:*capability*}.
Features related to a certain capability (other than SLPROTO:4.0) are marked
with {CAP:*capability*}.
Handshaking
-----------
......@@ -90,7 +91,7 @@ Example v3 handshaking
::
> HELLO\r\n
< SeedLink v3.0\r\n
< MySeedLink v1.0\r\n
< GEOFON\r\n
> BATCH\r\n
< ERROR\r\n
......@@ -108,25 +109,25 @@ Example v3 handshaking
< OK\r\n
> END\r\n
Example v4 handshaking
^^^^^^^^^^^^^^^^^^^^^^
Example v4 handshaking (async)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
> HELLO\r\n
< SeedLink v4.0 :: SLPROTO:4.0 WEBSOCKET:13 MULTISTATION TIME EXTTIME EXTSEQ EXTDATA INFO:ID INFO:CAPABILITIES INFO:STATIONS INFO:STREAMS\r\n
< MySeedLink v1.0 :: SLPROTO:4.0 WEBSOCKET:13 ASYNC MULTISTATION TIME INFO:ID INFO:CAPABILITIES INFO:STATIONS INFO:STREAMS\r\n
< GEOFON\r\n
> ACCEPT 3 2\r\n
< OK\r\n
> STATION APE GE\r\n
< OK\r\n
> SELECT 00:BH?.D\r\n
< OK\r\n
< OK\r\n
> DATA 0000000016FF890D\r\n
> STATION WLF GE\r\n
> SELECT 00:HH?.D\r\n
< OK\r\n
> SATION WLF GE\r\n
< OK\r\n
> SELECT 00:HH?.D\r\n
< OK\r\n
> DATA 000000001551B73D\r\n
< OK\r\n
......@@ -140,10 +141,10 @@ legacy data mode, each packet consists of 8-byte SeedLink header followed by a
512-byte miniSEED record. The SeedLink header is an ASCII string consisting of
the letters "SL" followed by a six-digit hexadecimal packet sequence number.
In extended data mode {CAP:EXTDATA} |4|, enabled by the ACCEPT command, each
packet consists of 11-byte SeedLink header, followed by variable length data.
The SeedLink header consists of the letters "SE" followed by data format code
(1 byte) and binary, 64-bit, little-endian sequence number (8 bytes).
In extended data mode |4|, enabled by the ACCEPT command, each packet consists
of 11-byte SeedLink header, followed by variable length data. The SeedLink
header consists of the letters "SE" followed by data format code (1 byte) and
binary, 64-bit, little-endian sequence number (8 bytes).
A SeedLink server that receives data from another SeedLink server may re-assign
sequence numbers for technical reasons. It is generally not possible to use the
......@@ -161,19 +162,6 @@ packet and waits for the client to close connection ("dial-up mode"). Due to
signature "SL" or "SE", A SeedLink packet can never start with "END", so there
is no ambiguity.
Capabilities
------------
Supporting the complete SeedLink protocol is not mandatory -- different
SeedLink implementations may have different capabilities. There are two ways to
determine which features the server supports:
* Looking at the capabilities list returned by HELLO or INFO CAPABILITIES
commands.
* Trial and error -- if the server responds with ERROR, then the client can
assume that the particular command/mode is not supported.
.. _seedlink_commands:
Commands
......@@ -194,7 +182,7 @@ USER name password {CAP:USER} |4|
AUTH token {CAP:AUTH} |4|
reserved for token authentication.
ACCEPT format_list {CAP:EXTDATA} |4|
ACCEPT format_list |4|
enables extended data mode. format_list is a space separated list of formats accepted by the client. Each element of the list is a number from 0 to 255. Some data may be available in multiple alternative formats; in this case, format_list should be interpreted as having decreasing priority and only data in the highest priority format should be sent to client.
ENABLE capability_list {CAP:CAP} |4|
......@@ -223,11 +211,11 @@ SELECT [pattern]
SELECT responds with "OK" on success, "ERROR" otherwise.
DATA [seq [begin_time [end_time]]]
enables real-time mode and optionally sets the sequence number and time window {CAP:TIME}. In uni-station mode, data transfer is started immediately, in multi-station mode, the response is "OK" or "ERROR". If sequence number is -1 |4| or omitted, then transfer starts from the next available packet. If time window is specified, any packets that are outside of the window are filtered out. end_time {CAP:EXTTIME} |4| may not be supported by older servers.
enables real-time mode and optionally sets the sequence number and time window {CAP:TIME}. In uni-station mode, data transfer is started immediately, in multi-station mode, the response is "OK" or "ERROR". If sequence number is -1 |4| or omitted, then transfer starts from the next available packet. If time window is specified, any packets that are outside of the window are filtered out. end_time |4| may not be supported by older servers.
Apart from the special value -1 {CAP:EXTSEQ} |4|, sequence number can be 64-bit (16 hexadecimal numbers) {CAP:EXTSEQ} |4| or 24-bit (6 hexadecimal numbers). The latter is equivalent to largest available 64-bit sequence number with matching 24 least significant bits.
Apart from the special value -1 |4|, sequence number can be 64-bit (16 hexadecimal numbers) |4| or 24-bit (6 hexadecimal numbers). The latter is equivalent to largest available 64-bit sequence number with matching 24 least significant bits.
Time should be in the form of 6 or 7 {CAP:EXTTIME} |4| decimal numbers separated by commas: year,month,day,hour,minute,second,nanosecond. Nanoseconds {CAP:EXTTIME} |4| may not be supported by older servers.
Time should be in the form of 6 or 7 |4| decimal numbers separated by commas: year,month,day,hour,minute,second,nanosecond. Nanoseconds |4| may not be supported by older servers.
FETCH [seq [begin_time [end_time]]]
works like DATA but enables dial-up mode instead of real-time mode.
......@@ -241,30 +229,8 @@ INFO level {CAP:INFO}
GET arg {CAP:WEBSOCKET}
HTTP GET, when used as the very first command, switches to WebSocket encapsulation. Argument is ignored.
Compatibility
-------------
The following commands/features are proposed and mostly not yet supported by
current SeedLink implementations.
* USER |4|
* ACCEPT |4|
* STATION: wildcard
* SELECT: "-" and ":" |4|
* DATA, FETCH: 64-bit sequence numbers |4|, nanosconds |4|, optional end time |4|
* TIME: nanoseconds |4|
* Asynchronous handshaking |4|
* WebSocket (GET)
List of capabilities
--------------------
Capabilities
------------
SeedLink 3.x defined 2 sets of capabilities. The original GFZ version defined
"dialup", "multistation", "window-extraction", "info\:id", "info\:capabilities",
......@@ -278,8 +244,12 @@ In SeedLink 4, both INFO CAPABILITIES and HELLO should return the same set of
unified capabilities, except that INFO CAPABILITIES (if supported) should add
the legacy (lower-case) capabilities for compatibility reasons.
Proposed unified capabilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A client may determine supported capabilities by trial and error -- if the
server responds with ERROR, then it can be assumed that the particular
command/mode is not supported. This method works with all protocol versions.
V4 capabilities
^^^^^^^^^^^^^^^
SLPROTO:#.#
SeedLink protocol version.
......@@ -320,20 +290,21 @@ TIME
TIME and start_time of DATA/FETCH (1 second resolution). Same as
"window-extraction" in SeedLink 3.x.
EXTTIME |4|
Nanosecond time resolution and optional end_time of DATA/FETCH.
EXTSEQ |4|
64-bit sequence numbers and "-1" special value.
EXTDATA |4|
Extended data mode (ACCEPT) and long network, station, localtion and channel
identifiers (incl. ":" and "-" special characters with SELECT).
INFO\:level
INFO level, where level is "ID", "CAPABILITIES", "STATIONS", "STREAMS",
"GAPS", "CONNECTIONS", "ALL".
The following additional features are supported if the server implements
{CAP:SLPROTO:4.0}:
* ACCEPT
* SELECT: ":"
* DATA, FETCH: 64-bit sequence numbers, nanosconds, optional end time.
* TIME: nanoseconds
Legacy capabilities
^^^^^^^^^^^^^^^^^^^
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment