Earthworm Wave Server Protocol

 

This appendix is taken straight from the wave_serverV.c code comments, as there was no formal description of the protocol for clients to use to get waveforms from an Earthworm Wave Server (either wave_serverV or Winston). ISTI made modifications and amendments to the protocol, as some items were not described at all, or well, in the code comments.

Last modified April 19, 2010, Paul Friberg

Notes:

• <s><c><n><l> is short-hand for site code, channel code, network and location id.
• <flags> :: F | F<letter> ... <letter>

Currently Supported Flags:

-      R - All requested data is right of the tank (after the tank).

-      L - All requested data is left of the tank (before the tank).

-      G - All requested data is in a gap in the tank.

-      B - The Client's request was bad. It contained incorrect syntax.

-      C - The tank from which the client requested data is corrupt. (Data may or may not be available for other time intervals in the tank. WARNING! This flag indicates that the tank is corrupt, this means data from other time intervals may be inaccurate)

-      N - The requested channel(tank) was not found in this wave_server.

-      U - An unknown error occurred.

• <datatype> is two character code ala CSS. Only supports i2, i4, s2, and s4. i for Intel; s for Sparc. 2 meaning two-bytes per integer, 4 ...
• Replies are ASCII, including trace data.
• <starttime> and <endtime> are double precision unix epochs since Jan 1,1970, including any fractions of seconds desired.
• The <request id> was added later to permit the wave viewer client to keep track of which reply belongs to which query. The idea is that the client sends this as part of its request. To us it's an arbitrary ASCII string. We simply echo this string as the first thing in our reply. We don't care what it is. The motivation is that the wave viewer would occasionally get confused as to which reply belonged to which of it's requests, and it would sit there, listening for a reply which never came. The request id is echoed as a fixed length 12-character string, null padded on the right if required.
• <sampling-rate> is in samples per second.
• Spaces are used between request arguments.

Description of Requests and Responses

 

MENU: <request id>

Returns one line for each tank it has:

<request id>

pin# <s><c><n><l> <starttime> <endtime> <datatype>

. . . . .

pin# <s><c><n><l> <starttime> <endtime> <datatype>

\n

 

MENUPIN: <request id> <pin#>

Returns as above, but only for specified pin number:

<request id> <pin#> <s><c><n><l> <starttime> <endtime> <datatype> <\n>

 

MENUSCNL: <request id> <s><c><n><l>

Returns as above, but for specified <s><c><n><l> name:

<request id> <pin#> <s><c><n><l> <starttime> <endtime> <datatype> <\n>

 

GETPIN: <request id> <pin#> <starttime> <endtime> <fill-value>

Returns trace data for specified pin and time interval. Gaps filled with <fill-value>.

<request id> <pin#> <s><c><n><l> F <datatype>

<starttime> <sampling rate> sample(1) sample(2)... sample(nsamples)

<\n> {the samples are ASCII}

 

If the requested time is older than anything in the tank, the reply is: <request id> <pin#> <s><c><n><l> FL <datatype> <oldest time in tank> <sampling rate> \n for the case when the requested interval is younger than anything in the tank, the reply is <request id> <pin#> <s><c><n><l>

FR <datatype> <youngest time in tank> <sampling rate> \n

 

NOTE: the GETPIN request has never worked in wave_serverV. As pin numbers fade into the distance, it is unlikely that this request will ever be supported.

GETSCNL: <request id> <s><c><n><l> <starttime> <endtime> <fill-value>

Returns as above, but for specified scnl name.

<request id> <pin#> <s><c><n><l> F <datatype> <starttime> <sampling-rate >

sample(1) sample(2)... sample(nsamples) <\n>

 

 

GETSCNLRAW: <request id> <s><c><n><l> <starttime> <endtime>

Returns trace data in the original binary form in which it was put into the tank (as a TRACEBUF2 packet). Whole messages will be supplied, so that the actual starttime may be older than requested, and the end time may be younger than requested. The reply is part ASCII, terminated by a "\n", followed by binary messages:

 

<request id> <pin#> <s><c><n><l> F <datatype> <starttime> <endtime>

<bytes of binary data to follow> <\n>. The line above is all in . All below is binary, byte order as found in the tank:

<trace_buf msg> ... <trace_buf msg>

 

If the requested time is older than anything in the tank, the reply is:

<request id> <pin#> <s><c><n><l> FL <datatype> <oldest time in tank> <\n>

 

For the case when the requested interval is younger than anything in the tank, the reply is:

<request id> <pin#> <s><c><n><l> FR <datatype> <youngest time in tank> <\n>

 

For the case when the requested interval falls completely in a gap, the reply is:

<request id> <pin#> <s><c><n><l> FG <datatype> <\n>