README 13.6 KB
Newer Older
1

2 3
NMXPTOOL: OPEN-SOURCE AND CROSS-PLATFORM SOFTWARE
          FOR NANOMETRICS SEISMIC DATA ACQUISITION
4 5 6 7

  Matteo Quintiliani - Istituto Nazionale di Geofisica e Vulcanologia - Italy
  Mail bug reports and suggestions to <quintiliani@ingv.it> 

Matteo Quintiliani's avatar
Matteo Quintiliani committed
8 9
  Website: http://mednet.rm.ingv.it/nmxptool.php

10
  nmxptool and libnmxp have been developed for interacting
Matteo Quintiliani's avatar
Matteo Quintiliani committed
11
  with NaqsServer and DataServer of Nanometrics Inc.
12 13 14 15 16 17 18


CONTENTS
   INTRODUCTION
   DEPENDENCIES
   QUICK INSTALLATION
   INSTALLATION
19
   INSTALLATION BINARIES
20
   SUPPORTED PLATFORMS AND 64-Bit ISSUES
21
   NAQSSERVER CONFIGURATION
22
   DOCUMENTATION
Matteo Quintiliani's avatar
Matteo Quintiliani committed
23
   SIGNAL HANDLING
Matteo Quintiliani's avatar
Matteo Quintiliani committed
24
   HISTORY
25 26 27
   ACKNOWLEDGEMENT
   LICENSE

28 29 30

- INTRODUCTION

31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
  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
49 50
manage Raw Stream connections by buffering and sorting all received packets,
included the retransmitted ones, guaranteeing a good compromise between data
51 52 53 54 55 56 57 58 59
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.

	
60 61
- DEPENDENCIES

62
  Optional libraries:
63

Matteo Quintiliani's avatar
Matteo Quintiliani committed
64
    * libmseed-2.3 or later: http://www.iris.edu/software/libraries/
65 66 67
      The Mini-SEED library. A C library framework for manipulating and
      managing SEED data records.  Author: Chad Trabant, IRIS DMC

68 69 70 71 72
    * Earthworm 6.2 or later: http://www.isti2.com/ew/

    * Seedlink, SeisComP - http://www.gfz-potsdam.de/geofon/seiscomp/
      Seedlink is a system for near real time seismic data distribution.

73 74 75 76
    * POSIX Threads library (pthread)
      On Windows, nmxptool has been compiled with "Pthreads-w32 release 2.8.0"
      http://sourceware.org/pthreads-win32/

77 78
  Read section INSTALLATION below.

79 80

- QUICK INSTALLATION
81 82 83

     tar xvfz nmxptool-X.X.X.tar.gz

84
     cd nmxptool-X.X.X
85 86
     ./configure
     make
87
     src/nmxptool --version
88 89 90 91 92 93 94 95 96

     make install
         OR
     make install-ew-bin
     make install-ew-conf (ONLY THE FIRST TIME)
         OR
     make install-seiscomp-bin
     make install-seiscomp-templates (ONLY THE FIRST TIME)
         OR
97 98
     cp src/nmxptool <where_you_want>

Matteo Quintiliani's avatar
Matteo Quintiliani committed
99
     nmxptool --help
100

101 102
     For binary installation see section INSTALLATION BINARIES below.

103

104
- INSTALLATION
105

106 107 108 109 110
  nmxptool and libnmxp have been developed using GNU Build Tools
  (automake, autoconf and configure script) taking in account the
  POSIX Cross-Platform aspects. So you should be able to compile
  and install them everywhere you can launch the following commands:

111
     ./configure --enable-FEATURE1 ... VAR1=... VAR2=...
112 113 114
     make
     make install

Matteo Quintiliani's avatar
Matteo Quintiliani committed
115 116
  Options for nmxptool 'configure' script:

117 118 119 120
  Disabling optional Features
      --disable-libmseed      disable saving data in mini-SEED records
      --disable-ew            do not compile nmxptool as Earthworm module
      --disable-seedlink      do not compile nmxptool as Seedlink plug-in
121

122 123 124 125 126 127
  Some influential environment variables:
      EW_HOME     Earthworm home directory
      EW_VERSION  Earthworm version directory
      EW_PARAMS   Earthworm configuration files directory
      GLOBALFLAGS C compiler flags for Earthworm

128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
  'configure' adds -I${EW_HOME}/${EW_VERSION}/include to CFLAGS

  Examples:

    * 'configure' tries to compile all features
          ./configure CFLAGS="-O2 -Wall -pipe -I/<anywhere>/libmseed" \
                      LDFLAGS="-L/<anywhere>/libmseed"

    * Enable only Earthworm feature and set related variables
          ./configure --disable-libmseed --disable-seedlink \
                      CFLAGS="-O2 -Wall -pipe" \
                      EW_HOME="/home/ew" \
                      EW_VERSION="v7.2" \
                      EW_PARAMS="${EW_HOME}/${EW_VERSION}/params" \
                      GLOBALFLAGS="-D_SPARC -D_SOLARIS"

                           or, for example
                      GLOBALFLAGS="-m32 -Dlinux -D__i386 -D_LINUX -D_INTEL -D_USE_SCHED  -D_USE_PTHREADS -D_USE_TERMIOS"
                      GLOBALFLAGS="-D_MACOSX -D_INTEL -D_USE_PTHREADS -D_USE_SCHED "
                      GLOBALFLAGS="-D_WINNT -D_INTEL -D_CRT_SECURE_NO_DEPRECATE -D_USE_32BIT_TIME_T"
                      Use the last one to compile Earthworm feature under Windows-MinGW.

    * Enable only libmseed and seedlink
          ./configure --disable-ew \
                      CFLAGS="-O2 -Wall -pipe -I/<anywhere>/libmseed" \
                      LDFLAGS="-L/<anywhere>/libmseed"

155
  Verifying the version and enabled features after compilation:
156

157
     src/nmxptool --version
158

Matteo Quintiliani's avatar
Matteo Quintiliani committed
159
     nmxptool 1.2.4, tool for Nanometrics Protocols
160
              Private Data Stream 1.4, Data Access Protocol 1.0
161
              Enabled features: libmseed YES, SeedLink YES, Earthworm YES.
162
              Using pthread: YES.
163

164
  * libmseed, The Mini-SEED library - http://www.iris.edu/manuals/
165
         If available within include and library path,
166
         this library allows to save retrieved data in Mini-SEED records.
167
         You might add to CFLAGS this "-I/<anywhere>/libmseed"
168 169
         and to LDFLAGS this "-L/<anywhere>/libmseed",
         do not forget to run 'ranlib libmseed.a' or similars.
170

171
  * ew, Earthworm System - http://www.isti2.com/ew/
172
         nmxptool is included into the official Earthworm distribution since the version 7.2.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
173
         Anyway, you can compile nmxptool outside the EW distribution, for example, to upgrade.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
174
         Before launching 'configure', run the appropriate script from directory 'environment',
175
         the compilation depends on the following environment variables:
Matteo Quintiliani's avatar
Matteo Quintiliani committed
176
             $EW_HOME, $EW_VERSION, $EW_PARAMS and $GLOBALFLAGS.
177
         'configure' looks for necessary Earthworm object files inside $EW_HOME/$EW_VERSION/lib
178
         and link them to nmxptool in order to enable Earthworm module feature.
179 180
         If some of object files are missing then it will attempt to discover sources
         dependents on your operating system and it will compile them before linking.
181

182 183 184 185 186 187
         Install binary and configuration files for Earthworm:

             make install-ew-bin
             make install-ew-conf (ONLY THE FIRST TIME)

         The first command copies nmxptool binary in $EW_HOME/$EW_VERSION/bin
Matteo Quintiliani's avatar
Matteo Quintiliani committed
188
         The second command copies earthworm/nmxptool.d, earthworm/nmxptool.desc in $EW_PARAMS
189 190
         If you are upgrading nmxptool then you might do that:

191 192 193 194
             make install-ew-doc

         Last command copies nmxptool_ovr.html and nmxptool_cmd.html into the directories
	 $EW_HOME/$EW_VERSION/ewdoc/WEB_DOC/ovr and $EW_HOME/$EW_VERSION/ewdoc/WEB_DOC/cmd
195 196 197

  * seedlink, SeisComP - http://www.gfz-potsdam.de/geofon/seiscomp/
         Seedlink is a system for near real time seismic data distribution.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
198 199
         Inside the directory 'src' has been copied files
         'seedlink_plugin.c' and 'seedlink_plugin.h' from 'plugin.c' and 'plugin.h'
200
         belonging to the SeisComP 2.5 distribution.
201

202 203
         If your SeisComP root directory is not equal to /home/sysop/seiscomp,
         you have to launch the script 'configure' in the following way:
204 205 206 207 208 209 210 211 212

             ./configure ... ... SEISCOMPDIR=/<where>/<seiscompdir>/<is>

         Install binary and template files for SeedLink:

             make install-seiscomp-bin
             make install-seiscomp-templates (ONLY THE FIRST TIME)

         The first command copies nmxptool binary in %SEISCOMPDIR%/acquisition/bin
213 214 215
         The second command copies the directories
             seiscomp_templates/135_nmxptool
             seiscomp_templates/136_nmxptool_dod
216 217 218 219 220
         in %SEISCOMPDIR%/acquisition/templates/source/

         After, you can use:

             seiscomp config
221 222


223 224 225 226
- INSTALLATION BINARIES
   Download the binary distribution for your operating system from the
   web site http://mednet.rm.ingv.it, unpack it and copy the files where you want.

227
   Linux box within the SeisComp3 directory:
228

229 230 231
             wget http://mednet.rm.ingv.it/downloads/soft/nmxptool-1.2.3-bin-i686-pc-linux-gnu.tar.gz
             tar xvfz nmxptool-1.2.3-bin-i686-pc-linux-gnu.tar.gz
             cd nmxptool-1.2.3-bin-i686-pc-linux-gnu/
232 233
             cp bin/nmxptool ~/seiscomp3/acquisition/bin/
             cp -R seiscomp_templates/135_nmxptool ~/seiscomp3/acquisition/templates/source/
234
             cp -R seiscomp_templates/136_nmxptool_dod ~/seiscomp3/acquisition/templates/source/
235

236
   Solaris Sparc Machine within Earthworm environment:
237

238 239 240
             wget http://mednet.rm.ingv.it/downloads/soft/nmxptool-1.2.3-bin-sparc-sun-solaris2.10.tar.gz
             gunzip -c < nmxptool-1.2.3-bin-sparc-sun-solaris2.10.tar.gz | tar xvf -
             cd nmxptool-1.2.3-bin-sparc-sun-solaris2.10/
241 242 243 244 245 246 247
             cp bin/nmxptool $EW_HOME/$EW_VERSION/bin/
             cp earthworm/nmxptool.d $EW_PARAMS/
             cp earthworm/nmxptool.desc $EW_PARAMS/

             Inside the same directory 'earthworm' are also available the documentation
             html files nmxptool_cmd.html and nmxptool_ovr.html

248 249 250 251
   Windows-XP, Windows2000:

             Download http://mednet.rm.ingv.it/downloads/soft/nmxptool-1.2.3-bin-i686-pc-mingw32.zip
	     Unzip the file.
252
	     Copy the files nmxptool.exe and pthreadVC2.dll where you want.
253

254

Matteo Quintiliani's avatar
Matteo Quintiliani committed
255
- SUPPORTED PLATFORMS AND 64-Bit ISSUES
256 257 258
   nmxptool 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
Matteo Quintiliani's avatar
Matteo Quintiliani committed
259 260
   almost all the Unix-like operating systems, Mac OS X, Windows
   and either 32-bit or 64-bit architectures.
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276

   nmxptool has been successfully compiled and tested on the following
   operating systems and architectures:
       -------------------------------------------------
      |          |  Intel    Intel    PowerPC   SPARC   |
      |          | 32-bit   64-bit    32-bit   64-bit   |
      |-------------------------------------------------|
      | Linux    |    X        X                        |
      | Solaris  |    X                           X     |
      | Mac OS X |             X         X              |
      | FreeBSD  |    X                                 |
      | Windows  |    X                                 |
       -------------------------------------------------

   N.B. No test has been done on Earthworm when
        nmxptool is compiled with 64-bit option (-m64)
277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301


- NAQSSERVER CONFIGURATION

   * Data continuity when short disconnections to NaqsServer occur

   Inside the section Datastream of the file Naqs.ini set DataBufferLength to a high value.

       [ Datastream ] 
         Port = 28000              // TCP port for control/data connections to Naqs 
         Password = none           // access password (not used in version 1.3) 
         MaxConnections = 10       // maximum number of simultaneous connections 
         SocketType = Direct       // connection type (Direct or Callback) 
         DataBufferLength = 100    // Buffer length for data channels (# packets)

   * Packet retransmission

   Inside the section NetworkInterface of the file Naqs.ini enable RetxRequest.
   If RetxRequest is not enabled then MaxTolerableLatency is ineffective.

       [ NetworkInterface ] 
         Port = 32000           // UDP port for incoming NMX data (usually 32000) 
         SendDelay = 250        // milliseconds to delay after each send 
         RetxRequest = Enabled
         MulticastGroup = 224.1.1.1 
302
     
303

304 305 306 307 308 309 310 311
- DOCUMENTATION
    * Print nmxptool help:

         nmxptool --help

    * Earthworm module: earthworm/nmxptool_cmd.html
                                  nmxptool_ovr.html

312

313 314 315 316 317 318 319 320
- SIGNAL HANDLING

    You can send the following signals to nmxptool:

         Signals INT QUIT TERM : Sending these signals to nmxptool causes it
                                 to immediately attempt to gracefully terminate. 
                                 It may take several seconds to complete exiting.

Matteo Quintiliani's avatar
Matteo Quintiliani committed
321
         Signals ALRM          : Print current info about Raw Stream buffer.
322 323 324

         Signals HUP PIPE      : Ignored. (SIG_IGN)

325 326 327 328 329 330 331

- HISTORY
    Read file HISTORY for release notes.


- ACKNOWLEDGEMENT
   In no particular order:
332 333
     * Stefano Pintore - I.N.G.V. (Istituto Nazionale di Geofisica e Vulcanologia)
     * Salvatore Mazza - I.N.G.V.
334 335 336 337 338
     * Marco Olivieri - I.N.G.V.
     * Luigi Falco - I.N.G.V.
     * Martina Demartin - I.N.G.V.
     * Paul Frieberg - ISTI (Instrumental Software Technologies, Inc.)
     * Marian Jusko
339 340
     * Efthimios Sokos - (University of Patras - Greece)
     * Roman Racine - (ETH Zurich - Swiss Seismological Service)
341 342


343
- LICENSE
344 345
  Software is open-source and released under GNU Library General Public License.
  Read file COPYING for details.
346