172 lines
5.8 KiB
ReStructuredText
172 lines
5.8 KiB
ReStructuredText
.. _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 <user> <password>`` - 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 <NET.STA.LOC.CHA>`` - adds/removes a stream from the
|
||
request, may be repeated in one request block
|
||
- ``TIME [<starttime>]:[endtime]`` - defines start and end time of the
|
||
request, open boundaries are allowed
|
||
- ``HELI ADD|REMOVE <NET.STA.LOC.CHA>`` - 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
|
||
<20>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 <sec-caps-web>`.
|
||
* **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.
|