.. highlight:: rst

.. _gdi2caps:

########
gdi2caps
########

**CAPS import module for Guralp GDI server.**


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

The Güralp Data Interconnect plugin(GDI) requests data from one or multiple GDI
servers and sends it to a CAPS server. The communication between a GDI server
and the plugin itself is based on the GDI client library whereas outgoing
packets are send through the CAPS client library. Depending on the configuration
outgoing packets are converted on-the-fly into MSEED by the CAPS client library.
The plugin supports the following GDI sample formats:

* INT32
* INT16
* IEEE32FLOAT
* TEXT

Backfilling
===========
By default backfilling of unordered packets is enabled and the buffer size is
set to 180 seconds. With backfilling enabled The CAPS client library ensures
that all packets within this time window are send in order to the remote CAPS
server. The buffer size can be changed in the plugin configuration. A value of
zero disables the backfilling.

Connection handling
===================

CAPS Connection
---------------
All packets forwarded to the CAPS client library are stored in a local packet
buffer and are removed when they have been acknowledged by the remote CAPS
server. If a packet could not be send the plugin closes the connection and
tries to reconnect in a certain interval. If the packet buffer is exceeded the
packet is droped and the client library returns with an error.

GDI Connection
--------------

For each configured GDI connection the plugin opens a connection to the remote
GDI server. The plugin requests real time data only, the retrievel of "historic"
data is not supported yet. Every second the plugin checks the connection state.
If the state is GDI_State_Out_Of_Sync it closes the connection and tries to
reconnect in a certain interval.



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

.. note::

   * gdi2caps is a standalone module and does not inherit
     :ref:`global options <global-configuration>`.
   * Modules/plugins may require a license file. The default path to license
     files is :file:`@DATADIR@/licenses/` which can be overridden by module
     configuration of the parameter :confval:`gempa.licensePath`. Example: ::

        gempa.licensePath = @CONFIGDIR@/licenses

| :file:`etc/defaults/gdi2caps.cfg`
| :file:`etc/gdi2caps.cfg`
| :file:`~/.seiscomp/gdi2caps.cfg`




.. confval:: mapping

   Type: *strings*

   List of station name mappings separated by comma. Each list
   entry has the format [name]:[alias]


.. confval:: mseed

   Default: ``false``

   Type: *boolean*

   Enable MSEED encoding.


.. confval:: selectors

   Type: *list:string*

   Format: [loc.cha, ...]. Wildcards are supported.


.. confval:: caps.address

   Type: *string*

   CAPS server address. Format is [address[:port]].


.. confval:: caps.backFillingBufferSize

   Default: ``180``

   Unit: *s*

   Type: *int*

   Length of backfilling buffer. Whenever a hole 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.


.. note::

   **profiles.$name.\***
   $name is a placeholder for the name to be used.


.. confval:: profiles.$name.source

   Type: *string*

   GDI server address in format [host]:[port]. If port
   is omitted, 1565 is assumed.


.. confval:: profiles.$name.identifier

   Type: *string*

   GDI connection identifying name. If two connections
   using the same name the first connection will be
   closed from the server.
   If omitted, the hostname is used.


.. confval:: profiles.$name.mapping

   Type: *strings*

   List of station name mappings separated by comma. Each
   entry has the format [name]:[alias]


.. confval:: profiles.$name.selectors

   Type: *list:string*

   List of selectors separated by comma. Each entry
   has the format [loc.cha]. Wildcards are supported.



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


.. confval:: address

   Type: *string*

   GDI server address in format [host]:[port]. If port
   is omitted, 1565 is assumed.


.. confval:: identifier

   Type: *string*

   GDI connection identifying name. If two connections
   using the same name the first connection will be
   closed from the server.
   If omitted, the hostname is used.


.. confval:: mapping

   Type: *strings*

   List of station name mappings separated by comma. Each list
   entry has the format [name]:[alias]


.. confval:: selectors

   Type: *list:string*

   List of selectors separated by comma. Each entry
   has the format [loc.cha]. Wildcards are supported.