Commit 52fa0196 authored by Andres Heinloo's avatar Andres Heinloo

Update protocol.rst

parent fe4acde7
......@@ -9,6 +9,9 @@ performed in order:
* Handshaking
* Transferring SeedLink packets
New features of SeedLink version 4 protocol are marked with ④ in the following
text.
Handshaking
-----------
......@@ -51,16 +54,14 @@ If a network error or timeout occurs the client should close the connection and
start a new session. Data transmission is started when the server receives the
commands DATA, FETCH, TIME or END as described in section
:ref:`seedlink-commands`. Once the data transfer has been started, no more
commands, except INFO, should be sent to the server. Flow diagram of
handshaking, illustrating different modes, is shown in
:ref:`seedlink-handshaking`.
commands, except INFO, should be sent to the server. Flowchart of
handshaking is shown in :ref:`seedlink-handshaking`.
.. _seedlink-handshaking:
.. figure:: media/seedlink/Handshaking_flowchart.*
:width: 10cm
TODO: Handshaking flow diagram.
.. figure:: Handshaking_flowchart.svg
Handshaking flowchart
Data Transfer
-------------
......@@ -70,7 +71,7 @@ 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, each packet consists of 11-byte SeedLink header,
In extended data mode, 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).
......@@ -98,11 +99,11 @@ 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.
* 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.
* Trial and error -- if the server responds with ERROR, then the client can
assume that the particular command/mode is not supported.
.. _seedlink_commands:
......@@ -118,12 +119,18 @@ CAT
BYE
closes the connection. Used mainly for testing a SeedLink server with "telnet".
USER name password
USER name password
simple authentication as an alternative to IP-based ACL. Successful authentication un-hides restricted stations/streams that the user is authorized to access. Responds with "OK" if authentication was successful, "ERROR" if authentication failed or command not supported. In any case, access to non-restricted stations is guaranteed. For security reasons, USER should be used with encrypted (SSL) connections only.
ACCEPT format_list
ACCEPT format_list
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 ④
enables additional capabilities of the server
CAPABILITIES capability_list
same as ENABLE
STATION station_code [network_code]
enables multi-station mode, which is used to transfer data of multiple stations over a single TCP connection. The STATION command, followed by SELECT (optional) and FETCH, DATA or TIME commands is repeated for each station and the handshaking is finished with END. STATION responds with "OK" on success, "ERROR" otherwise (eg., if the station is not found or multi-station mode is not supported by the server).
......@@ -139,22 +146,22 @@ END
SELECT [pattern]
when used without pattern, all selectors are canceled. Otherwise, the pattern is a positive selector to enable matching miniSEED stream transfer. The pattern can be used as well as a negative selector with a leading "!" to prevent the transfer of some miniSEED streams. Only one selector can be used in a single SELECT request. A SeedLink packet is sent to the client if it matches any positive selector and doesn’t match any negative selectors.
Format of the pattern is LL:CCC.T, where LL is location, CCC is channel, and T is type (one of DECOTL for data, event, calibration, blockette, timing, and log records). "LL", ".T", and "LL:CCC." can be omitted, meaning "any". If the location code is exactly 2 characters and channel code is exactly 3 characters, then ":" should be omitted, because it may not be supported by all servers. Supported wildcard is "?". "-" stands for space (eg., "--" can be used to denote empty location code), but may not be supported by all servers.
Format of the pattern is LL:CCC.T, where LL is location, CCC is channel, and T is type (one of DECOTL for data, event, calibration, blockette, timing, and log records). "LL", ".T", and "LL:CCC." can be omitted, meaning "any". If the location code is exactly 2 characters and channel code is exactly 3 characters, then ":" should be omitted, because it may not be supported by all servers. Supported wildcard is "?". "-" stands for space (eg., "--" can be used to denote empty location code), but may not be supported by all servers.
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. In uni-station mode, data transfer is started immediately, in multi-station mode, the response is "OK" or "ERROR". If sequence number is -1 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 may not be supported by older servers.
enables real-time mode and optionally sets the sequence number and time window. In uni-station mode, data transfer is started immediately, in multi-station mode, the response is "OK" or "ERROR". If sequence number is -1 ④ 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 ④ may not be supported by older servers.
Apart from the special value -1, sequence number can be 64-bit (16 hexadecimal numbers) 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 ④, sequence number can be 64-bit (16 hexadecimal numbers) ④ 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 decimal numbers separated by commas: year,month,day,hour,minute,second,nanosecond. Nanoseconds may not be supported by older servers.
Time should be in the form of 6 or 7 ④ decimal numbers separated by commas: year,month,day,hour,minute,second,nanosecond. Nanoseconds ④ 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.
TIME [begin_time [end_time]]
equivalent of "DATA -1 begin_time end_time"
equivalent of "DATA -1 begin_time end_time".
INFO level
requests an INFO packet containing XML data embedded in a miniSEED log record. level should be one of the following: ID, CAPABILITIES, STATIONS, STREAMS, GAPS, CONNECTIONS, ALL. The XML document conforms to the Document Type Definition (DTD) shown in section ???. The amount of info available depends on the configuration of the SeedLink server.
......@@ -165,20 +172,55 @@ Compatibility
The following commands/features are proposed and mostly not yet supported by
current SeedLink implementations.
* USER
* USER ④
* ACCEPT
* ACCEPT ④
* STATION: wildcard
* STATION: wildcard
* SELECT: "-" and ":"
* SELECT: "-" and ":" ④
* DATA, FETCH: 64-bit sequence numbers, nanosconds, optional end time
* DATA, FETCH: 64-bit sequence numbers ④, nanosconds ④, optional end time ④
* TIME: nanoseconds
* TIME: nanoseconds ④
* Asynchronous handshaking
* Asynchronous handshaking ④
Capabilities
------------
List of capabilities (provisional)
----------------------------------
SLPROTO:#.#
SeedLink protocol version.
CAP
Supports ENABLE/CAPABILITIES command.
EXTREPLY
Extended reply messages supported. Must be enabled with the ENABLE
(CAPABILITIES) command to take effect.
NSWILDCARD
Network & station code wildcarding.
NSWILDCARDSEQ ④
Support sequence numbers in combination with wildcards.
BATCH
Batch handshaking supported.
ASYNC ④
Asynchronous handshaking supported.
USER ④
User authentication (USER) supported.
EXTTIME ④
Nanosecond time resolution supported and optional end_time of DATA/FETCH
supported.
EXTSEQ ④
64-bit sequence numbers supported and "-1" special value supported.
EXTDATA ④
Extended data mode (ACCEPT) and long network, station, localtion and channel
identifiers supported (incl. ":" and "-" special characters with SELECT).
\ No newline at end of file
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