README 8.77 KB
Newer Older
1

Matteo Quintiliani's avatar
Matteo Quintiliani committed
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

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


CONTENTS
   INTRODUCTION
   DEPENDENCIES
   QUICK INSTALLATION
   INSTALLATION
19
   SUPPORTED PLATFORMS AND 64-Bit ISSUES
Matteo Quintiliani's avatar
Matteo Quintiliani committed
20
   DOCUMENTATION
Matteo Quintiliani's avatar
Matteo Quintiliani committed
21
   HISTORY
Matteo Quintiliani's avatar
Matteo Quintiliani committed
22 23 24
   ACKNOWLEDGEMENT
   LICENSE

25 26 27

- INTRODUCTION

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

	
57 58
- DEPENDENCIES

Matteo Quintiliani's avatar
Matteo Quintiliani committed
59
  Optional libraries:
60 61 62 63 64

    * libmseed-2.1.4 or later: http://www.iris.edu/manuals/
      The Mini-SEED library. A C library framework for manipulating and
      managing SEED data records.  Author: Chad Trabant, IRIS DMC

Matteo Quintiliani's avatar
Matteo Quintiliani committed
65 66 67 68 69 70 71
    * 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.

  Read section INSTALLATION below.

72 73

- QUICK INSTALLATION
Matteo Quintiliani's avatar
Matteo Quintiliani committed
74 75 76

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

77
     cd nmxptool-X.X.X
78 79
     ./configure
     make
80
     src/nmxptool --version
Matteo Quintiliani's avatar
Matteo Quintiliani committed
81 82 83 84 85 86 87 88 89

     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
90 91
     cp src/nmxptool <where_you_want>

Matteo Quintiliani's avatar
Matteo Quintiliani committed
92
     nmxptool --help
93

Matteo Quintiliani's avatar
Matteo Quintiliani committed
94

95
- INSTALLATION
Matteo Quintiliani's avatar
Matteo Quintiliani committed
96

97 98 99 100 101 102 103 104 105
  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:

     ./configure
     make
     make install

Matteo Quintiliani's avatar
Matteo Quintiliani committed
106 107
  Options for nmxptool 'configure' script:

108 109 110 111
  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
112

113 114 115 116 117 118
  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

119
  Verifying the version and enabled features after compilation:
Matteo Quintiliani's avatar
Matteo Quintiliani committed
120

121
     src/nmxptool --version
Matteo Quintiliani's avatar
Matteo Quintiliani committed
122 123 124

     nmxptool 1.2.1, Nanometrics tool
             (Private Data Stream 1.4, Data Access Protocol 1.0)
125
              Enabled features: libmseed YES, SeedLink YES, Earthworm YES.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
126

Matteo Quintiliani's avatar
Matteo Quintiliani committed
127
  * libmseed, The Mini-SEED library - http://www.iris.edu/manuals/
128
         If available within include and library path,
Matteo Quintiliani's avatar
Matteo Quintiliani committed
129
         this library allows to save retrieved data in Mini-SEED records.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
130
         You might add to CFLAGS this "-I/<anywhere>/libmseed"
Matteo Quintiliani's avatar
Matteo Quintiliani committed
131 132
         and to LDFLAGS this "-L/<anywhere>/libmseed",
         do not forget to run 'ranlib libmseed.a' or similars.
133

Matteo Quintiliani's avatar
Matteo Quintiliani committed
134
  * ew, Earthworm System - http://www.isti2.com/ew/
Matteo Quintiliani's avatar
Matteo Quintiliani committed
135
         nmxptool is included into the official Earthworm distributions since version 7.2.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
136
         Anyway, you can compile nmxptool outside the EW distribution, for example, to upgrade.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
137
         Before launching 'configure', run the appropriate script from directory 'environment',
Matteo Quintiliani's avatar
Matteo Quintiliani committed
138
         the compilation depends on the following environment variables:
Matteo Quintiliani's avatar
Matteo Quintiliani committed
139
             $EW_HOME, $EW_VERSION, $EW_PARAMS and $GLOBALFLAGS.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
140
         'configure' looks for necessary Earthworm object files inside $EW_HOME/$EW_VERSION/lib
141
         and link them to nmxptool in order to enable Earthworm module feature.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
142 143
         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.
144

Matteo Quintiliani's avatar
Matteo Quintiliani committed
145 146 147 148 149 150
         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
151
         The second command copies earthworm/nmxptool.d, earthworm/nmxptool.desc in $EW_PARAMS
Matteo Quintiliani's avatar
Matteo Quintiliani committed
152 153
         If you are upgrading nmxptool then you might do that:

154 155 156 157
             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
Matteo Quintiliani's avatar
Matteo Quintiliani committed
158 159 160

  * 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
161 162
         Inside the directory 'src' has been copied files
         'seedlink_plugin.c' and 'seedlink_plugin.h' from 'plugin.c' and 'plugin.h'
Matteo Quintiliani's avatar
Matteo Quintiliani committed
163
         belonging to the SeisComP 2.5 distribution.
Matteo Quintiliani's avatar
Matteo Quintiliani committed
164

Matteo Quintiliani's avatar
Matteo Quintiliani committed
165 166
         If your SeisComP root directory is not equal to /home/sysop/seiscomp,
         you have to launch the script 'configure' in the following way:
Matteo Quintiliani's avatar
Matteo Quintiliani committed
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181

             ./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
         The second command copies the directory seiscomp_templates/135_nmxptool
         in %SEISCOMPDIR%/acquisition/templates/source/

         After, you can use:

             seiscomp config
182 183


Matteo Quintiliani's avatar
Matteo Quintiliani committed
184
- SUPPORTED PLATFORMS AND 64-Bit ISSUES
Matteo Quintiliani's avatar
Matteo Quintiliani committed
185 186 187
   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
188 189
   almost all the Unix-like operating systems, Mac OS X, Windows
   and either 32-bit or 64-bit architectures.
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205

   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)
Matteo Quintiliani's avatar
Matteo Quintiliani committed
206
     
Matteo Quintiliani's avatar
Matteo Quintiliani committed
207

208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
- DOCUMENTATION
    * Print nmxptool help:

         nmxptool --help

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


- HISTORY
    Read file HISTORY for release notes.


- ACKNOWLEDGEMENT
   In no particular order:
     * Salvatore Mazza - I.N.G.V. (Istituto Nazionale di Geofisica e Vulcanologia)
     * 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


231
- LICENSE
Matteo Quintiliani's avatar
Matteo Quintiliani committed
232 233
  Software is open-source and released under GNU Library General Public License.
  Read file COPYING for details.
234