.. highlight:: rst

.. _rs2caps:

#######
rs2caps
#######

**Recordstream data acquisition plugin**


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

*rs2caps* uses the |scname| :cite:t:`recordstream` to feed data into :ref:`CAPS`
of to stdout.


Examples
========

* Inject data into the CAPS server:

  .. code-block:: sh

     seiscomp start caps
     rs2caps -I data.mseed --passthrough

  Read the :ref:`examples section<sec-caps_example_offline>` to learn how to
  use *rs2caps* to input data into the CAPS server.

* Read data from the file *data.mseed* resample to 10 Hz sample rate by the
  RecordStream and write the resulting data to stdout:

  .. code-block:: bash

     rs2caps -I resample://file?rate=10/data.mseed --passthrough --dump-packets --mseed > test.mseed


  You may join the command with :cite:t:`capstool` and :cite:t:`scmssort`:

  .. code-block:: bash

     echo "2024,01,01,00,00,00 2024,01,01,00,10,00 * * * *" | capstool -H localhost |\
     rs2caps -I resample://file?rate=10/- --passthrough --dump-packets --mseed |\
     scmssort -E > test.mseed

  .. note::

     A similar action with additional data processing may be executed using
     :ref:`sproc2caps`.



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

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

rs2caps 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



.. _output:


.. confval:: output.address

   Default: ``localhost:18003``

   Type: *string*

   Data output URL [[caps\|capss]:\/\/][user:pass\@]host[:port]. This parameter
   superseds the host and port parameter of previous versions and takes precedence.


.. confval:: output.host

   Default: ``localhost``

   Type: *string*

   Data output host. Deprecated: Use output.address instead.


.. confval:: output.port

   Default: ``18003``

   Type: *int*

   Data output port. Deprecated: Use output.address instead.


.. confval:: output.timeout

   Default: ``60``

   Unit: *s*

   Type: *int*

   Timeout when sending a packet. If the timeout expires
   the connection will be closed and re\-established.


.. confval:: output.maxFutureEndTime

   Default: ``120``

   Unit: *s*

   Type: *int*

   Maximum allowed relative end time for packets. If the packet
   end time is greater than the current time plus this value,
   the packet will be discarded. By default this value is set
   to 120 seconds.


.. confval:: output.bufferSize

   Default: ``1048576``

   Unit: *bytes*

   Type: *uint*

   Size \(bytes\) of the packet buffer.


.. confval:: output.backFillingBufferSize

   Default: ``0``

   Unit: *s*

   Type: *int*

   Length of backfilling buffer. Whenever a gap is detected, records
   will be held in a buffer and not sent out. Records are flushed from
   front to back if the buffer size is exceeded.


.. _output.mseed:


.. confval:: output.mseed.enable

   Default: ``false``

   Type: *boolean*

   Enable on\-the\-fly miniSEED
   encoding. If the encoder does not support the input
   type of a packet it will be forwarded. Re\-encoding of
   miniSEED packets is not supported.


.. confval:: output.mseed.encoding

   Default: ``Steim2``

   Type: *string*

   miniSEED encoding to use. \(Uncompressed, Steim1 or Steim2\)


.. _streams:


.. confval:: streams.begin

   Type: *string*

   Start time of data time window, default 'GMT'


.. confval:: streams.end

   Type: *string*

   End time of data time window


.. confval:: streams.days

   Default: ``-1``

   Unit: *day*

   Type: *int*

   Use to set the start time of data time window n days before the current time.


.. confval:: streams.daysBefore

   Default: ``-1``

   Unit: *day*

   Type: *int*

   Use to set the end time of data time window n days before the current time.


.. confval:: streams.passthrough

   Default: ``false``

   Type: *boolean*

   Do not subscribe to any stream and
   accept everything a record source is
   passing. This is useful in combination
   with files.


.. _journal:


.. confval:: journal.file

   Default: ``@ROOTDIR@/var/run/rs2caps/journal``

   Type: *string*

   File to store stream states


.. confval:: journal.flush

   Default: ``10``

   Unit: *s*

   Type: *uint*

   Flush stream states to disk every n seconds


.. confval:: journal.waitForAck

   Default: ``60``

   Unit: *s*

   Type: *uint*

   Wait when a sync has been forced, up to n seconds


.. confval:: journal.waitForLastAck

   Default: ``5``

   Unit: *s*

   Type: *uint*

   Wait on shutdown to receive acknownledgement messages, up to n seconds


.. confval:: journal.syncWithBindings

   Default: ``false``

   Type: *boolean*

   Whether to synchronize the journal file with bindings.
   If enabled then each time update\-config is called, the
   bound stations will be synchronized with the current
   journal file. Unbound stations will be removed from
   the journal. Synchronizing with bindings will disable
   reading the inventory.


.. _statusLog:


.. confval:: statusLog.enable

   Default: ``false``

   Type: *boolean*

   Log information status information e.g.
   max bytes buffered


.. confval:: statusLog.flush

   Default: ``10``

   Type: *uint*

   Flush status every n seconds to disk



Bindings Parameters
===================


.. confval:: selectors

   Type: *list:string*

   List of stream selectors in format LOC.CHA.
   If left empty all available streams will be requested.





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


.. _Generic:


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. 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:: -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.


.. _Records:


Records
-------

.. option:: --record-driver-list

   List all supported record stream drivers.

.. option:: -I, --record-url arg

   The recordstream source URL, format:
   [service:\/\/]location[#type].
   \"service\" is the name of the recordstream driver
   which can be queried with \"\-\-record\-driver\-list\".
   If \"service\" is not given, \"file:\/\/\" is
   used.

.. option:: --record-file arg

   Specify a file as record source.

.. option:: --record-type arg

   Specify a type for the records being read.


.. _Output:


Output
------

.. option:: -O, --output arg

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

   This is the CAPS server which shall receive the data.

.. option:: --agent arg

   Sets the agent string. Allows the server to identify the
   application that sends data.

.. option:: -b, --buffer-size arg

   Size \(bytes\) of the journal buffer. If the value ist
   exceeded, a synchronization of the journal is forced.

.. option:: --backfilling arg

   Default: ``0``

   Buffer size in seconds for backfilling gaps.

.. option:: --mseed

   Enable on\-the\-fly miniSEED encoding. If the encoder does not
   support the input type of a packet, it will be forwarded.
   Re\-encoding of miniSEED packets is not supported.

.. option:: --encoding arg

   miniSEED encoding to use: Uncompressed, Steim1 or Steim2.

.. option:: --rec-len arg

   miniSEED record length expressed as a power of
   2. A 512 byte record would be 9.

.. option:: --max-future-endtime arg

   Maximum allowed relative end time for packets. If the packet
   end time is greater than the current time plus this value,
   the packet will be discarded. By default this value is set
   to 120 seconds.

.. option:: --dump-packets

   Dump packets to stdout.

.. option:: --test

   Disable socket communication.

.. option:: --dump

   Dump all received data to stdout and don't use the input
   port.


.. _Journal:


Journal
-------

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

   File to store stream states. Use an empty string to log to
   stdout.

.. option:: -f, --flush arg

   Flush stream states to disk every n seconds.

.. option:: --wait-for-ack arg arg

   Wait when a sync has been forced, up to n seconds.

.. option:: -w, --wait-for-last-ack arg

   Wait on shutdown to receive acknownledgement messages, up to
   the given number of seconds.


.. _Status:


Status
------

.. option:: --status-log

   Log information status information, e.g., max bytes buffered.

.. option:: --status-flush arg

   Flush status every n seconds to disk.


.. _Streams:


Streams
-------

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

   StreamID [net.sta.loc.cha] to add.

.. option:: --id-file arg

   File to read stream IDs from.

.. option:: --passthrough

   Do not subscribe to any stream and  accept everything a
   record source is passing. This is useful in combination with
   files.

.. option:: --begin arg

   Start time of data time window.

.. option:: --end arg

   End time of data time window.

.. option:: --days arg

   Unit: *day*

   Begin of data request time window given as days before current time.
   Applied only on streams not found in the journal.

.. option:: --days-before arg

   Unit: *day*

   End of data request time window given as number of days
   before current time.


.. _Polling:


Polling
-------

.. option:: --poll

   For non\-streaming inputs polling can be
   used to simulate real\-time streaming.

.. option:: --poll-window arg

   Time window in seconds to be used with polling.

.. option:: --poll-interval arg

   Time interval in seconds used for polling.

.. option:: --poll-serial

   Will request each channel seperately rather all channels in
   one request.


