SeedLink protocol details

Hi!

I recently started looking into making the obspy.seedlink module compatible with Python 3.

I have searched the web for in-depth information about the SeedLink protocol for quite some time. So far I found client usage documentation (slinktool, SeisComp 2.1, SeisComp3) and open source implementations of the protocol layer (libslink, Ringserver).

A formal specification of the protocol would be especially helpful.

I am hoping someone here can hint me at the resource I have been missing so far.

Best regards,
Bernhard Morgenstern

Hi Bernhard:

This is a good resource:
http://www.seiscomp3.org/doc/seattle/current/apps/seedlink.html

Otherwise the 2.1 manual is all that I know exists.

I do not know of a formal specification of the protocol.

Kind Regards from Panama,

Hi Brendan,

This is a good resource:
seedlink — SeisComP3 Seattle documentation

Otherwise the 2.1 manual is all that I know exists.

Thank you for your response. Unfortunately I have already worked through those two.

They leave a few lower-level questions unanswered:

  - At what version did which feature become available?
  - Does a server need to advertise its version number? How should a
    version of 0.0 be handled?
  - What are the allowed contents of the 8 bit SeedLink header?
  - What wildcards are allowed in a selector? (E.g. the docs above don't
    mention '*' which is implemented in Ringserver.)
  - What are the allowed encodings for XML payloads in INFO responses?
  - What is the EXTREPLY feature?
  - Are begin_time and end_time time zone dependent or UTC?
  - ...

Best,
Bernhard

This is a good resource:
seedlink — SeisComP3 Seattle documentation

Otherwise the 2.1 manual is all that I know exists.

Thank you for your response. Unfortunately I have already worked through those two.

Hi Bernhard,

The given sources are the only documentation that I know of and as far as I know are accurate representations of the seedlink server maintained by GEOFON as a component of SeisComP. Extensions of the protocol were mostly done by me for IRIS needs and are reflected in libslink and ringserver. Care was taken to ensure that clients based on libslink and ringserver were compatible with GEOFON’s implementation.

I will try to help with some of the questions below (mostly by reading the libslink source code):

They leave a few lower-level questions unanswered:

- At what version did which feature become available?

Notable changes (based on sl_checkversion() usage in libslink):

version >= 2.5 support multi-station capability in addition to uni-station mode. I do uni-station mode servers are common any more.

version >= 2.92 supports the INFO command

version >= 2.92 supports TIME command for time window selection.

version >= 2.93 supports adding the packet time stamp to the FETCH and DATA commands

version >= 3.1 supports the BATCH command

As far as I know only ringserver & libslink support the CAPABILITY client reporting feature and the capability flag for the server.

- Does a server need to advertise its version number?

Not strictly, but it is useful for libslink (and maybe other client libraries) for identification of features. For libslink, the identification returned for the HELLO command should be of the form:

"SeedLink v#.# <optional text> <:: capability flags>”

where the capability flags are:

          SLPROTO:#.# == SeedLink protocol version
          CAP == Supports CAPABILITY command
          EXTREPLY == Extended reply messages supported
          NSWILDCARD == Network & station code wildcarding

So the version should definitely be in the “v#.#” part of the identification string. If the optional capabilities part of the identifier is to be supported the version can also be reported using the SLPROTO flag. Again, this is how libslink deals with a server, not sure how many other clients do so.

How should a
  version of 0.0 be handled?

In libslink this translates to version unknown, in which case the server is treated as 3.0 capability. For a long time 3.0 version servers were prevalent, older ones are probably not around much more.

- What are the allowed contents of the 8 bit SeedLink header?

I am not sure to what 8-bit header you are referring to, each miniSEED record is prefixed by an 8-byte header, which I presume you mean. This is documented at seedlink — SeisComP3 Seattle documentation as:

'The SeedLink header is an ASCII string consisting of the letters "SL" followed by a six-digit hexadecimal packet sequence number.’

The exception to this is when first 6 characters of a packet are “SLINFO", in which case it is an INFO packet. In this case, the 8th byte of the header, the so-called termination flag, indicates when the packet is the last of a potential series of INFO packets. When the termination flag is a ‘*’ character more INFO packets are expected, when it is not an ‘*’ character (e.g. a space) it is the last INFO packet for a given request.

- What wildcards are allowed in a selector? (E.g. the docs above don't
  mention '*' which is implemented in Ringserver.)

For clarity: in SeedLink a selector refers to a pattern used to match location IDs and channels for a given network-station pair. The STATION command is given by a client and includes the network and station code desired, subsequent SELECT commands can be given with selectors to subset the location IDs and channel codes desired for the network-station specified in the most recent STATION command.

I believe the GEOFON server supports only ‘?’ for a single character wildcard in selectors (see the description of the SELECT command in the protocol doc on seiscomp3.org). Also, I do not believe the GEFON server allows any wildcards in the station and network values passed with the STATION command.

ringserver also accepts ‘?’ for a single character in selectors, it does NOT accept ‘*’ as you imply above. ringserver does accept ‘*’ and ‘?’ in the network and station values passed with the STATION command, this is an extension added by IRIS.

- What are the allowed encodings for XML payloads in INFO responses?

Undefined as far as I know. I don’t think the protocol cares and it only matters what the client is able to parse usefully. For widest compatibility I would recommend keeping it UTF-8.

- What is the EXTREPLY feature?

That allows the server to report extra information (“EXTended REply”) back to the client. In the case of ringserver, the client must report that it supports EXTREPLY in the capabilities information or such extra content is not sent. This extra information contains details of WHY a command failed, the original protocol only allows “OK” or “ERROR”.

I believe this extension is only implemented in ringserver and libslink, but I’m not certain.

- Are begin_time and end_time time zone dependent or UTC?

I’m pretty sure all date-times in the protocol are UTC to match the time base of data, SEED records are always expected to be in UTC.

cheers,
Chad

Hi Chad,

thank you so much for taking the time to provide such a detailed explanation! It really helped a lot in clearing things up and is very much appreciated!

I will have to see how I can best make use of this.

Best,
Bernhard