Part 1 of this documentation dealt with installing the OS onto the Raspberry Pi board and to compile Earthworm . Now we will go through what is needed to run a few of the EW modules. The intent here is not to run a complete installation of EW that can locate events. I don't think a small board like the PI2 has enough resource to do this. The main bottleneck is reading and writing to the relatively slow SD card. What we can use the board for is to setup a remote node and have it send in A/D data from the digitizer to a larger EW system. For redundancy we will use the wave_serverV module to store the data locally to the SD card. This setup will also setup a module called Ew2Winsdr (Ew2Ws). This will allow the user to connect to the PI board and view and store the data using or WinSDR datalogger program.

statmgr - This is the status manager. It monitors the other modules to see if they are running correctly.

psnadsend - This is our module that imports the data from the digitizer board into EW.

wave_serverV - This module stores and serves the A/D data to other modules using a TCP/IP connection.

export_ack - This module sends real-time data to another installation of EW using a TCP/IP connection.

ew2ws - This is another one of our modules. It allows WinSDR to receive data from the PI board.

We will now go through the setup of each of the above modules. Each module has two configuration files associated with it. The .d file has the module configuration parameters and the .desc file is used by the statmgr module to monitor the module status.

startstop module: This module starts up EW. It is executed by type startstop at the command prompt. Before starting EW remember to run as root and you have used the command source ew_linux.bash to setup your environment. This module is hard coded to use the startstop_unix.d file in your params subdirectory. This should be /earthworm/run_working/params. This file defines the transport data rings that will be used to transfer data around and what modules to run at start up.

statmgr module: This module monitors the other modules to make sure they are running. If the .desc file for the various modules are configured properly, statmgr will restart the module if it crashes. A list of modules to monitor can be found at the end of the statmgr.d file.

psnadsend module: This module imports the data from our digitizer boards into one or two data rings. If you will be running the ew2ws module you will need to use two data rings. One is for the normal demultiplexed data that will be used by the export_ack and wave_serverV modules. The second ring is used to send multiplexed data to the ew2ws module and then off to WinSDR if the program connects to the ew2ws module using a TCP/IP connection. The PsnAdSend.d files is configured to be used with one of our 24-Bit 4-Channel PSN-ADC24 digitizer board.

wave_serverV module: This module is used to archive the A/D data to a local drive. In our case that will be a directory on the SD card. This module is optional, it is not needed to run the export_ack and ew2ws modules. It can be used as a local backup of the data if the TCP/IP link between the main EW system goes down. The parameter ServerIPAdr needs to be changed to the IP address of your Pi system. This is why you should setup your network configuration to use a static IP address. Another option is to setup the DHCP server to always supply the same IP address to the PI2 board based on the NIC address. You will also need to create a directory to store the data to. The example files uses a directory called seisdata off of the main EW root directory. This needs to be created before you can run EW.

export_ack module: This module listens for connections from a import_ack module running on another system. Once connected using the specified port, the export_ack module will send all of the data it sees on the ring to the remote import_ack module. You do not need to run this module if all you want to do is send the data to WinSDR using the Ew2Ws module.

ew2ws module: This module is only needed if you want to view the data from the digitizer board using our WinSDR datalogger program. Besides being able to directly connect up to one of our digitizer boards, WinSDR can use a TCP/IP connection to receive data from a remote system. The remote system could be another WinSDR system or the ew2ws module running on your PI2 board. This setup requires two wave/data rings. One for the export_ack and wave_serverV modules, they require demultiplexed data, and the other ring has multiplexed data that can be used by WinSDR.

copystatus module: This EW utility simply copies status messages from one ring to another. It is not needed if you are only running one wave/data ring. This module does not have a .d or .desc files. The wave ring to monitor and send out to are defined in the startstop_unix.d file.

Additional files: The file earthworm.d, located in the params directory, is used to define the wave/data rings, module IDs and additional messages types. This line:

Should be added to the file if you are going to use Ew2Ws. Each module will also need a unique module ID number. Our example files uses these IDs:

Installation Identification: One of the parameters you need to define in the ew_linux.bash file is the Installation ID string. Our example ew_linux.bash file uses:

For the statmgr to work correctly each of the module .desc files must use the same installation ID of INST_DPSN. The ID strings to ID number are defined in the earthworm_global.d file. As an example in the PsnAdSend.desc file you will find the following 3 lines:

Hardware Information: The easiest way of connecting the digitizer board to the Raspberry PI2 is using USB. The PI2 board has 4 USB ports. If you have one of our digitizer boards with USB interface simply connect the A/D board to the PI2. For best noise immunity a short USB cable with one or two noise filters should be used. If you have a RS-232 interface only board use a FTDI based USB to RS-232 adapter. This type of adapter will be identified by the OS and create a device called /dev/ttyUSB0. The PI2 board only has one serial UART on it and to interface to it requires special hardware. You can not connect the RS-232 lines from the A/D board directly to the PI2 UART input and output pins. The maximum input level on the PI2 board is 0 to +3.3V. The RS-232 output voltage levels from the A/D board are +-12V. This will damage you PI2 board! Besides the voltage levels the signals into and out of the A/D board need to be inverted.

Running Earthworm: It is now time to run EW. We have installed the OS, setup our development and Earthworm environment, compiled EW and modified the *.d and *.desc files. It is now time to run as root. If you don't PsnAdSend will not be able to open the /dev/ttyUSB0 device and other modules may not work if you don't have the directory/file permissions just right. Open a terminal and type sudo su - and then type the root password. Now source the ew_linux.bash file. You are now ready to run EW. Type startstop on the command line. After a few seconds you should see something like this on the screen:

EARTHWORM SYSTEM STATUS

        Hostname-OS:            Mate - Linux 3.18.0-24-rpi2
        Start time (UTC):       Tue Jun 30 04:02:56 2015
        Current time (UTC):     Thu Jul  2 02:06:40 2015
        Disk space avail:       2001924 kb
        Ring  1 name/key/size:  WAVE_RING / 1000 / 1024 kb
        Ring  2 name/key/size:  MUX_DATA_RING / 1038 / 2048 kb
        Startstop's Log Dir:    /earthworm/run_working/log/
        Startstop's Params Dir: /earthworm/run_working/params/
        Startstop's Bin Dir:    /earthworm/trunk/bin
        Startstop Version:      v7.8 2015-06-25

         Process  Process           Class/    CPU
          Name      Id     Status  Priority   Used  Argument
         -------  -------  ------  --------   ----  --------
       startstop   30815   Alive      ??/ 0 00:00:13  -
       psnadsend    4943   Alive      RR/10 00:01:07  PsnAdSend.d
         statmgr   30817   Alive      ??/ 0 00:00:16  statmgr.d
    wave_serverV   30818   Alive      ??/ 0 00:03:33  wave_serverV.d
           ew2ws   30819   Alive      ??/ 0 00:00:14  Ew2Ws.d
      export_ack   30820   Alive      ??/ 0 00:00:13  export_ack.d
      copystatus   30821   Alive      ??/ 0 00:00:10  MUX_DATA_RING WAVE_RING

   Press return to print Earthworm status, or
   type restart nnn where nnn is proc id or name to restart, or
   type quit<cr> to stop Earthworm.

Note the Status field, each module should be marked Alive. If not check the log file for the module to see why it crashed. The log files can be found here: /earthworm/run_working/log

Using Screen: In part 1 we installed the screen utility. This will allow us to run EW in the background even if you are not logged into the system using SSH. If you run EW directly from a SSH shell and then exit the startstop module will be terminated. You can get around the problem by using screen. This command:

This will start a screen session and run the startstop executable. The parameter after the flags -dmS is the screen name and the next one is the program to run. The screen name is used to reference a screen when attaching to it. When you are in a detached screen use the ctrl-a ctrl-d keys to detach from the screen. When you do this the screen will be running in the background. To reattach to the screen use:

You can use screen to run a EW module independently from the startstop module. As an example you could run PsnAdSend in it's own screen. First comment out PsnAdSend in the startstop_unix.d file. Restart EW. Now start PsnAdSend by using this command:

Remember to shutdown EW if you need to restart it or if you are shutting down the system. Attach to the main screen and type quit. This should start the shutdown sequence. If you are using more the then one screen session the others should be closed automatically when the module received the terminate message from the startstop module.

The two commands screen -dmS main startstop and screen -dmS adc psnadsend PsnAdSend.d can be added to a bash script and run from the command line. The same script could also be used to start EW when the system boots up. Name the file something like startew.sh and make it executable: chmod +x startew.sh

#!/bin/bash
cd /earthworm
source ./trunk/ew_linux.bash
screen -dmS main startstop
screen -dmS adc psnadsend PsnAdSend.d <-- Only needed if startstop is not starting PsnAdSend.

Running Earthworm on a Raspberry Pi 2 Model B Board

Part 2