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