.. highlight:: rst

.. _caps_plugin:

###########
caps_plugin
###########

**Transfers data from CAPS to SeedLink server**


Description
===========

CAPS! server plugin that receives raw data via the CAPS! protocol and
sends raw or compressed data to Seedlink or to standard out.

Configuration
=============
The caps_plugin can be configured as any other Seedlink plugins, e.g.
via `scconfig <https://docs.gempa.de/seiscomp3/current/apps/scconfig.html>`_.
The configuration is shown using the SC250 station of the SW network as an example.
To start `scconfig` run:

.. code-block:: sh

   > seiscomp exec scconfig

Select 'Bindings' from the panel switch. The bindings panel shown in
figure :ref:`fig-scconfig-bindings-panel` configures a station for a module. It is separated into three main areas:

* the station tree (red + orange)
* the binding content (green)
* the module tree (blue)

.. _fig-scconfig-bindings-panel:

.. figure:: media/scconfig_bindings_panel.png
   :width: 17cm

   Bindings panel


Open the context menu of the view below the station tree and select
'Add network' to add a new network. Fill in the network name 'SW' into
the input form and press 'OK'. A double click on the network 'SW' shows
the associated stations. Add a new Station 'SC250' in the same way as
done before for the network.
Figure Figure :ref:`fig-scconfig-add-station` shows the current station tree.

.. _fig-scconfig-add-station:

.. figure:: media/scconfig_add_station.png
   :width: 17cm

   Station tree of the SW network



To complete the configuration open the station 'SC250' in the station
tree and use the context menu to add a new binding for Seedlink.
Go to the sources section of the binding content, select 'CAPS' and press
the button on left side of the selection box. Leave the upcoming input
form blank and press 'OK'. Subsequently click on the triangle besides
the CAPS label and set up the caps_plugin. Supported encodings are
'STEIM1' and 'STEIM2'. Use an empty encoding string to create raw
miniSEED packets.
Figure :ref:`fig-scconfig-binding-conf` shows an example configuration.

.. _fig-scconfig-binding-conf:

.. figure:: media/scconfig_binding_conf.png
   :width: 17cm

   CAPS Binding configuration


Press 'CTRL+S' to save all changes. Afterwards switch to the 'System panel',
select Seedlink in the module list and press 'Update configuration'.

Examples
========

The caps plugin can also be used as a command-line tool to request data.
The data will be sent to standard out.

Command-line help
-----------------

.. code-block:: sh

   > seiscomp exec bash
   > $SEISCOMP_ROOT/share/plugins/seedlink/caps_plugin -h

Data file request
-----------------

Submit the request to the CAPS server to download miniSEED data to a file,
e.g. data.mseed:

.. code-block:: sh


   seiscomp exec bash
   > $SEISCOMP_ROOT/share/plugins/seedlink/caps_plugin -I localhost:18002 -A SW.SC250..HH? \
   --encoding STEIM2 caps2sl.localhost.18002.state \
   --begin "2013-08-01 00:00:00" --end "2013-08-01 01:00:00" \
   --dump > data.mseed


Submit the request based on the request file to the CAPS server to
ownload miniSEED data to a file, e.g. data.mseed:

.. code-block:: sh


   seiscomp exec bash
   > $SEISCOMP_ROOT/share/plugins/seedlink/caps_plugin -I localhost:18002 -f streams_list \
   --encoding STEIM2 caps2sl.localhost.18002.state \
   --begin "2013-08-01 00:00:00" --end "2013-08-01 01:00:00" \
   --dump > data.mseed


Request file, e.g. streams_list:

.. code-block:: sh

   SW.SC254..*
   SW.SC250..HH?
   SW.*..HHZ



Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/caps_plugin.cfg`
| :file:`etc/global.cfg`
| :file:`etc/caps_plugin.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/caps_plugin.cfg`

caps_plugin inherits :ref:`global options<global-configuration>`.

.. note::

   Modules/plugins may require a license file. The default path to license
   files is :file:`@DATADIR@/licenses/` which can be overridden by global
   configuration of the parameter :confval:`gempa.licensePath`. Example: ::

      gempa.licensePath = @CONFIGDIR@/licenses



.. confval:: journal

   Type: *string*

   File to store stream states. Use an empty string to log to standard out.


.. confval:: archive

   Default: ``false``

   Type: *boolean*

   Disables realtime mode. Only archived data is fetched.


.. _input:


.. confval:: input.address

   Default: ``localhost:18002``

   Type: *string*

   CAPS URL to fetch data from, format: [[caps\|capss]:\/\/][user:pass\@]host[:port]




Command-Line Options
====================


.. _Generic:


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file arg

   Use alternative configuration file. When this option is
   used the loading of all stages is disabled. Only the
   given configuration file is parsed and used. To use
   another name for the configuration create a symbolic
   link of the application or copy it. Example:
   scautopick \-> scautopick2.

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself
   and doesn't need to be started with \&.


.. _Verbosity:


Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
   4:debug.

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

.. option:: --print-component arg

   For each log entry print the component right after the
   log level. By default the component output is enabled
   for file output but disabled for console output.

.. option:: --component arg

   Limit the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging backend. The output usually goes to
   \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Execute in debug mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 .

.. option:: --trace

   Execute in trace mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 \-\-print\-component\=1
   \-\-print\-context\=1 .

.. option:: --log-file arg

   Use alternative log file.


.. _Plugin:


Plugin
------

.. option:: -I, --input arg

   Overrides configuration parameter :confval:`input.address`.



.. _Streams:


Streams
-------

.. option:: -A, --add-stream arg

   List of stream IDs [net.sta.loc.cha] to add, wildcards are supported

.. option:: -f, --stream-file arg

   Path to stream\-file. The stream file may contain a list of streams IDs [net.sta.loc.cha]

.. option:: --begin arg

   Request start time

.. option:: --end arg

   Request end time


.. _Mode:


Mode
----

.. option:: --archive

   Overrides configuration parameter :confval:`archive`.



.. _Output:


Output
------

.. option:: --dump arg

   Dump all received data to stdout and don't push the data to SeedLink

.. option:: --encoding arg

   Preferred data output encoding

.. option:: -I, --input arg

   Data input host

.. option:: -j, --journal arg

   Overrides configuration parameter :confval:`journal`.



