wiki:nmxptool

Version 4 (modified by branden, 9 years ago) (diff)

--

Earthworm Module: nmxptool

Contributed by: Matteo Quintiliani. nmxptool is open-source and actively supported by the Istituto Nazionale di Geofisica e Vulcanologia.

Function

nmxptool is an IMPROVED interface through which waveform data collected by the Nanometrics data acquisition software, NaqsServer, can be fed into an Earthworm system in near-real-time. (New in V7.2, contributed by INGV)

Details

The Nanometrics servers NaqsServer and DataServer can provide on-line access to seismic data and state-of-health information accepting TCP/IP connections and forwarding the requested data to each client program. NaqsServer collates and stores in near-real-time incoming data in ringbuffers whereas DataServer provides data of the past stored in NaqsServer ringbuffers. In order to implement the Nanometrics subscription protocols, the author developed a software consisting of a library called libnmxp and a tool called nmxptool. The library exposes a set of documented APIs which allow to communicate with the Nanometrics servers. The tool, based on libnmxp, allows to retrieve or monitor real-time data and data of the past.

nmxptool can be used in three different ways:

  • stand-alone to monitor data or save retrieved data in mini-seed records
  • launched as an Earthworm module to redirect data into the EW-rings
  • like a Seed-Link plug-in to feed the SL-server

The main contribute, as regards other similar software, is the capability to manage Raw Stream connections by buffering and sorting all received packets, included the retransmitted ones, guaranteeing a good compromise between data continuity and low latency. Besides, nmxptool allows to retrieve Data-On-Demand with minimum delay after request. Software is open-source and released under GNU Library General Public License. It has been written in C language using the GNU Build Tools (automake, autoconf and configure script) and taking in account the cross-platform compilation aspects, in fact, it can run on almost all the Unix-like operating systems, Mac OS X, Windows and either 32-bit or 64-bit architectures.

Why a new software client for Nanometrics Server?

When we connect to a NaqsServer by a Short-term data stream connection we get a gap for each retransmitted packet. Unfortunately, previous available software were not able to reorder retransmitted packets. nmxptool is capable to manage a buffer of packets and order them chronologically when is needed, that is when a retransmission occurs. The management of this buffer reduce number of gaps in spite of the increment of latency. However, some tests showed that almost all packets are retrivied maximum within 60 seconds.

Main parameter to set for Raw Stream is the max tolerable latency you can accept, a sort of short-term-completion but managed by the client and not by the server.

Moreover, nmxptool is capable of:

  • allowing data continuity when disconnections to NaqsServer occur
  • retrieving "Data On Demand" with minimum delay

The maximum size of the TRACEBUF messages created by nmxptool is limited to the maximum number of samples that can fit into a Nanometrics compressed packet (17 * N, where N is any odd integer from 1 to 59, that is 17 * 59 = 1003 samples = 4012 bytes), plus the size of the TRACEBUF header (64 bytes). So 4076 bytes is a good estimate of the maximum size of TRACEBUF messages created by nmxptool.

nmxptool supports the creation of either TRACEBUF or TRACEBUF2 messages depending on which version of Earthworm the module was built for. By default the module will create TRACEBUF2 messages if the system supports them and TRACEBUF messages otherwise. Additionally there is an optional command !ForceTraceBuf1 that will force the use of TRACEBUF messages on systems that support TRACEBUF2.

Configuration File Commands

On startup, nmxptool reads the configuration file named on the command line. Commands in this file set all the parameters used for configuring the Earthworm Nanometrics client module nmxptool (Nanometrics). In the control file, lines may begin with a valid nmxptool command (listed below) or with one of 2 special characters:

#  marks the line as a comment (example: # This is a comment).
   
@  allows control files to be nested; one control file can be 
   accessed from another with the command "@" followed by 
   a string representing the path name of the next control file 
   (example: @model.d).

Command names must be typed in the control file exactly as shown in this document (commands are case sensative). Blank lines are also permitted in the control file.

Functional Command Listing

Below are the commands recognized by nmxptool, grouped by the function they influence. Most of the commands are required; they may be specified in any order in the control file.

        Earthworm system setup:

MyModuleId              required

RingName                required

HeartBeatInterval       required

Verbosity		optional



Nanometrics server and connection parameters:

NmxpHost                required

NmxpPortPDS		optional

NmxpPortDAP		optional

UserDAP			optional

PassDAP			optional

ForceTraceBuf1		optional

MaxTolerableLatency	optional

ShortTermCompletion	optional

MaxDataToRetrieve	optional

TimeoutRecv		optional

mschan			optional

DefaultNetworkCode	optional

ChannelFile		required	Xor Channel

Channel			required	Xor ChannelFile




Output control:

LogFile			required

Helpful Hints

The following list is organized by:

command [argument here]