.. _sec-caps-interface: Server Interfaces ================= .. TODO Plugin Interface ---------------- buffer, acknowledgement of packet .. _sec-caps-client-interface: Client interface / telnet ------------------------- :term:`CAPS` provides a line based client interface for requesting data and showing available streams. The ``telnet`` command may be used to connect to the server: .. Using telnet application to connect to a local :term:`CAPS` server .. code-block:: sh telnet localhost 18002 The following commands are supported by the server: * ``HELLO`` - prints server name and version * ``HELP`` prints descriptive help * ``BYE`` - disconnects from server * ``AUTH `` - performs authentication * ``INFO STREAMS [stream id filter]`` - lists available streams and time spans, see section \ref{sec:ci_info_streams} * ``BEGIN REQUEST`` - starts a request block, followed by request parameters, see section \ref{sec:ci_request} - ``REALTIME ON|OFF`` - enables/disables real-time mode, if disabled the connection is closed if all archive data was sent - ``STREAM ADD|REMOVE `` - adds/removes a stream from the request, may be repeated in one request block - ``TIME []:[endtime]`` - defines start and end time of the request, open boundaries are allowed - ``HELI ADD|REMOVE `` - similar to STREAM but re-sample the data to 1Hz - ``META{@[version]} [ON|OFF]`` - request delivery of packet header information only - ``OUTOFORDER [ON|OFF]`` - delivers data in order of sampling or transmission time - ``SEGMENTS [ON|OFF]`` - request delivery of times of contiguous segments (API >= 4) - ``GAPS [ON|OFF]`` - request delivery of times of gaps (API >= 4) - ``TOLERANCE [value in us]`` - Define data segment continuation tolerance in microseconds (API >= 4) - ``RESOLUTION [value in d]`` - Resolution in days of the returned data segments or gaps (API >= 4) * ``END`` - finalizes a request and starts acquisition * ``PRINT REQUESTS`` - prints active request of current session * ``ABORT`` - aborts current data transmission Requests to server are separated by a new line. For the response data the server prepends the message length to the data. In this way non ASCII characters or binary content can be returned. .. _sec-ci-info-streams: List available streams ~~~~~~~~~~~~~~~~~~~~~~ The following example shows a telnet conversation of a request for available streams. The first line contains the request command. All other lines represent the server response. The response is 124 characters long. The length parameter is interpreted by telnet and converted to its ASCII representation, in this case: ``|``. .. code-block:: none :linenos: :emphasize-lines: 1 INFO STREAMS VZ.HILO.* |STREAMS VZ.HILO.WLS.CAM 2013-07-26T00:00:01 2013-08-02T09:28:17 VZ.HILO.WLS.SSH 2008-06-06T00:00:00 2013-08-02T09:04:00 END .. _sec-ci-request-data: Data requests ~~~~~~~~~~~~~ Data request are initiated by a request block which defines the stream and the time span to fetch. .. code-block:: none :linenos: :emphasize-lines: 1-5 BEGIN REQUEST REALTIME OFF STREAM ADD VZ.HILO.WLS.SSH TIME 2013,08,02,09,00,02: END DSTATUS OK SESSION_TABLE VERSION:1 PACKET_HEADER IDSIZE:2,DATASIZE:4 FREQUESTS ID:1,SID:VZ.HILO.WLS.SSH,SFREQ:1/60,UOM:mm,FMT:RAW/FLOAT END [unprintable data] 'REQUESTS ID:-1,SID:VZ.HILO.WLS.SSH END �EOD The listing above shows such a request block in lines 1-5. Line 2 disables the real-time mode which will close the session after all data was read. Line 3 adds the stream to the request set. More streams may be added in successive lines. Line 4 specifies a start time and an open end time. The first response chunk starts at line 6 and ends at line 11. I has a length of 68 byte (= ACCII ``D``) and contains version information and a session table. The table maps a 2 byte integer id to data stream meta information. In this way following data chunks can be distinguished by only 2 bytes and the header information has to be transmitted only once. Line 12 contains the data chunks. It is omitted here because it contains unprintable characters. A data chunk starts with the 2 id bytes followed by the 4 byte chunk size. After all data was transmitted the server reports the end of the stream (line 13-15) and the end of the session (line 16). .. _sec-caps-web-interface: Web interface ------------- :term:`CAPS` ships with a read-only web interface for viewing information and downloading data. The Web interface is disabled by default and may be enabled by configuring a valid port number under :confval:`AS.http.port`. It provides different tabs: * **Channels** (figure :num:`fig-web-streams`): View and filter available streams. For the RAW and miniSEED packets it is also possible to view the waveform data by clicking on an entry of the stream table. miniSEED data may be :ref:`downloaded interactively `. * **Server stats** (figure :num:`fig-web-overview`): View server traffic statistics. This tab is only accessible if the logged in user is member of the *admin* group as defined by :confval:`AS.auth.basic.users.passwd`. * **Settings** (figure :num:`fig-web-settings`): Set the login credentials and parameters of the other perspectives. .. _fig-web-streams: .. figure:: media/web_streams.png :width: 18cm Stream perspective of :term:`CAPS` Web interface allowing to filter availability streams and to view waveform data for RAW and minSEED records. .. _fig-web-overview: .. figure:: media/web_overview.png :width: 18cm Overview perspective of :term:`CAPS` Web interface showing traffic and file statistics. .. _fig-web-settings: .. figure:: media/web_settings.png :width: 18cm Settings perspective of :term:`CAPS` Web interface.