Protocol reference

OWS implements the waveform part of the Winston Wave Server protocol and the Earthworm wave server commands that Winston clients use. This page is for people writing their own clients; Swarm, Earthworm and ObsPy need none of it.

Connection

  • TCP, port 16032 by default (LISTEN_PORT). No login.

  • Each request is one line of text ending with a newline. The answer starts with a line of text; some answers continue with binary data.

  • <REQ_ID> is any word you choose. OWS repeats it at the start of the answer, so you can match answers to requests.

  • One connection can carry many requests, one after the other.

Commands

Command

Request

Answer

VERSION

VERSION

PROTOCOL_VERSION: 3

MENU

MENU: <REQ_ID> [SCNL]

The channel list with each channel’s start and end time (Unix time). With SCNL, a missing location code is shown as --.

GETCHANNELS

GETCHANNELS: <REQ_ID> [METADATA]

The channel list in Winston’s format; start and end times in J2K seconds.

GETSCNLRAW

GETSCNLRAW: <REQ_ID> <STA> <CHA> <NET> <LOC> <START> <END>

Raw samples as Earthworm TRACEBUF2 packets. Times in Unix seconds.

GETSCNL

GETSCNL: <REQ_ID> <STA> <CHA> <NET> <LOC> <START> <END> <FILL>

Samples as text. Times in Unix seconds.

GETWAVERAW

GETWAVERAW: <REQ_ID> <STA> <CHA> <NET> <LOC> <START> <END> <COMPRESS>

One binary wave record (big-endian), zlib-compressed if <COMPRESS> is 1. Times in J2K seconds. Swarm uses it for wave views.

GETSCNLHELIRAW

GETSCNLHELIRAW: <REQ_ID> <STA> <CHA> <NET> <LOC> <START> <END> <COMPRESS>

Minimum and maximum per second, for helicorders (big-endian doubles), zlib-compressed if <COMPRESS> is 1. Times in J2K seconds.

Times

  • Unix seconds: seconds since 1970-01-01 00:00:00 UTC, with decimals.

  • J2K seconds: seconds since 2000-01-01 12:00:00 UTC, with decimals. J2K = Unix − 946728000.

Not supported

STATUS, GETSCNLRSAMRAW (server-side resampling), GETSCNRAW, GETSCN, GETPIN, MENUPIN and MENUSCNL. OWS answers unknown commands by closing the connection. OWS only serves waveforms: it doesn’t store data sent to it, and it has no instrument response, event or metadata services.