Skip past header information
USGS - science for a changing world

U.S. Geological Survey Open-File Report 2012-1178

Profile Measurements and Data From the 2011 Optics, Acoustics, and Stress In Situ (OASIS) Project at the Martha's Vineyard Coastal Observatory

Appendix 3. Software

Skip past contents information

This appendix lists the programs written or adapted by the U.S. Geological Survey (USGS) to log data and control instruments during the Optics, Acoustics, and Stress In Situ (OASIS) project deployment. Software falls into the following categories:

(a) programs run from a computer located onshore

(b) programs run on the Moxa main control computer on the tripod

(c) programs run on the Modtronix Engineering SBC68EC single-board computer on the tripod.

Key programs are listed here and are available, along with sample input and output files, in Code_and_sample_input_and_output. A Subversion version-control system was used to store programs written during development and testing. The repository was maintained by a commercial hosting service.

All the programs written by the USGS are in the public domain. However, some draw extensively from code examples posted on the Web, provided by instrument manufacturers, or listed in books, particularly Hyde (2004) and Kerrisk (2010). Those programs may be copyrighted. The following disclaimer applies to all USGS code used in this project:

"Although this program has been used by the U.S. Geological Survey (USGS), no warranty, expressed or implied, is made by the USGS or the U.S. Government as to the accuracy and functioning of the program and related program material nor shall the fact of distribution constitute any such warranty, and no responsibility is assumed by the USGS in connection therewith."

Onshore Scripts

Bash shell programs to control the Sequoia Scientific LISST-HOLO digital holographic particle imaging system (LISST-HOLO) and download data from the Moxa were written by Pat Dickhudt and Ellyn Montgomery. These programs resided on the Ubuntu operating system Linux computer at the Bigelow Laboratory at the Woods Hole Oceanographic Institution (WHOI). The programs were launched by cron, a Linux utility that schedules tasks defined by the user. The scheduled jobs are listed in a configuration file normally found in /etc/crontab. On most Unix-type systems, a crontab function can be used to change entries in this file.

Table 3-1. Scripts run from the onshore Linux computer for the 2011 OASIS experiment.

[Description of Abbreviations and Symbols]
Filename Description Comments Downloaded all data and log files from the Moxa Launched by cron; ran every 2 hours on even hours after arm motion and data logging have completed Initiated sampling by LISST-HOLO, stopped sampling, and downloaded images to shoreside computer; deleted files on LISST-HOLO after transfer Launched by cron; ran every 2 hours starting 3 minutes before even hours Duplicated LISST-HOLO data to second external hard drive on onshore computer Launched by cron; ran every 2 hours after sampling and download, starting 1 hour 47 minutes after even hours

Moxa Programs

The Moxa was running Linux 2.7 , firmware version FWR_UC8418_V2.0.4_Build_11062414.hfm. Moxa supplied a subset of standard Linux utilities and provided a version of the Minicom text-based modem control and terminal emulation program (minicom_2.4_xscale.ipk) that was used for testing and troubleshooting serial communications with the sensors. Moxa programs were written by Ellyn Montgomery and Chris Sherwood in C and in Linux bash shell scripting language. The C programs were cross-compiled for the Moxa on computers running Ubuntu operating system (version 11.04) with the GNU ARM tool chain (compiler) for Linux (version 4.2.1.). Compiled executable versions of programs were downloaded to the Moxa via file transfer protocol (ftp) and stored (along with any required input files) in the subdirectory /var/sda/progs. Programs compiled to run on the Moxa had the C code "-c" suffix substituted by an "-mx" suffix (for example, ac.c was compiled to ac-mx), and when test versions were compiled to run on Ubuntu computers, "-ub" replaced "-c".

Much of the Moxa code was derived from examples in The Linux Programming Interface (Kerrisk, 2010). Code for handling the SBG Systems IG-20 two-axis inclinometers and three-axis accelerometers was adapted from examples and called library routines (SbgComSerial) provided by SBG Systems with the instruments. Serial-port communications programs used routines from serial.c (an example provided by Moxa) and code graciously provided by Sam Laney (WHOI). A routine for extracting values and changing the endianness of data in the user data protocol (UDP) packets was based on an example from Hyde (2004).

Cron and system logging were not enabled on the Moxa by default. The following lines were added the file /etc/inittab to start both features when the Moxa booted:

# start cron
crond:2345:respawn:/etc/init.d/cron start
# start system logging

The cron scheduler on the Moxa differs from most other Unix or Linux implementations in that there is no crontab function; thus, users are required to edit the /etc/cron.d/crontab table. The contents of /etc/cron.d/crontab used during the deployment are as follows:

# sample sequence (note the fields must be separated by tabs!!!):
# update the web page every 5 minutes
1,6,11,16,21,26,31,36,41,46,51,56 * * * *     root     /var/sda/progs/ >> /var/log/cron_msg

# first kill gmsm-mx 2 minuted before the next arm movement- it will be restarted with the loggers
58 1,3,5,7,9,11,13,15,17,19,21,23 * * *     root     /var/sda/progs/ > /var/log/cron_msgkg
# 1 minute before arm movement begins, start the data loggers (and gmsm)
# the sleep n && command syntax to offset starting by a few seconds is in
59 1,3,5,7,9,11,13,15,17,19,21,23 * * *     root     /var/sda/progs/ > /var/log/cron_msglog

# on even two hour intervals, start the arm control program
0 0,2,4,6,8,10,12,14,16,18,20,22 * * *     root     /var/sda/progs/ac-mx &1>/dev/null 2>/dev/null

# 1.5 hours after arm movement started, kill the loggers (except for gmsm-mx)
30 1,3,5,7,9,11,13,15,17,19,21,23 * * *     root     /var/sda/progs/ > /var/log/cron_msgkl]

Tables 3-2 through 3-4 list files changed in the Moxa directory structure and files and programs necessary for arm control and data logging that were loaded onto the user-portion of the Moxa file system during the experiment. The names of the executable versions typically are appended with -mx to indicate they were cross-compiled for the Moxa and sometimes with _em to indicate they were compiled by Ellyn Montgomery from her version of the source code.

Table 3-2. System or application files added or modified on Moxa for the 2011 OASIS experiment.

Filename(s) Description Contents
/etc/cron.d/crontab Configuration for the cron scheduler List and schedule of programs to run automatically
/etc/minicom/mincom.adv /etc/minicom/minicom.ysi /etc/mincom/mincom.holo Default settings for minicom asynchronous communication program, and settings to use with specific instruments Baud, parity, and other settings

Table 3-3. User executable and data files on the Moxa for the 2011 OASIS experiment.

[See the Instrumentation section for a complete description of these instruments. See also Abbreviations and Symbols]
Directory Description Contents*
/var/sda Solid-state flash drive with user data All user data (except those noted below)
/var/sda/progs Executable programs, scripts, and configuration files ac-mx
/var/sda/logs Log files from the programs armadv_nnnn.log
/var/sda/data Directory of data files  
/var/sda/data/accel Data from the arm accelerometer ig20_YYYYMMDDhhmmss_nnnnnn.dat
/var/sda/data/armadv Data from the arm ADV (header info only) ig20_YYYYMMDDhhmmss_nnnnnn.dat
/var/sda/data/modtr Data from the Modtronix and arm control program ig20_YYYYMMDDhhmmss_nnnnnn.dat
/var/sda/data/pcadp Data from the PCADP pcadp_YYYYMMDDhhmmss_nnnnnn.dat
/var/sda/data/ysi Data from the YSI CTD ysi_YYYYMMDDhhmmss_nnnnnn.dat
* In data file names, nnnn represents the PID of the program writing the files, and date and time stamps.

Table 3-4. Programs and scripts on the Moxa for the 2011 OASIS experiment.

[Stored in the /var/sda/progs subdirectory. See the Instrumentation section for a complete description of these instruments. See also Abbreviations and Symbols]
Programs and scripts on the Moxa (in /var/sda/progs/)
Source (executable) Description Dependencies Input Output
Get Modtronix; read UDP packets from the Modtronix, write data to shared memory (to be read by ac.c) and log file SbgComSerial library.
Real-time libraries librt and libpthread.
Required that the Modtronix was running and sending UDP packets.
make_gm, pshm.h

Arm control; read arm control status from shared memory, execute arm control logic, and send UDP commands to Modtronix to control arm Real-time libraries librt and libpthread.
Required that gm-mx was running to establish and populate shared memory.
Required that the Modtronix was running and sending UDP packets.
make_ac, pshm.h
/var/sda/progs/ac.conf /var/sda/logs/
Log arm ADV data from RS-232 input. This is an instrument-specific modification of log_any.c that uses port 3 at 19200 baud make_log_adv, serial.c, serial.h   /var/sda/logs/

Log PCADP data from RS-232 input. This is an instrument-specific modification of log_any.c that used port 5 at 9600 baud make_log_pcadp, serial.c, serial.h   /var/sda/logs/

Log arm accelerometer data from RS-232 input. This is an instrument-specific logging program that uses the Sbg routines for serial input and output and data conversion SbgComSerial library.


Log any communications port; used for logging YSI CTD. This was intended to be a generic routing for logging RS-232 data make_logs, serial.c, serial.h /var/sda/progs/port5_ysi_9600.conf /var/sda/logs/

chk_modx_status.c Read current Modtronix data from shared memory and write to text file Real-time library librt.
Required that gm-mx was running to establish and populate shared memory
  /var/sda/logs/Modx_status.txt Shell script to start all logging programs; run automatically by cron scheduler on even hours Shell script to stop all logging programs; run by users to shut down gracefully before maintenance during experiment Shell script to read Modtronix status from shared memory and update the .html file used to display status Functional Web server
modx_status.txt moxa_status.html (copied into /home/httpd/htdocs/index.html
set_webRelay.c Issues HTTP GET command to toggle power on the Webrelay; not used during deployment chk_webrelay-mx Command-line arguments stdout Issues HTTP GET command to toggle power on the Webrelay; not used during deployment   Command-line arguments stdout

Modtronix Program

The Modtronix ran one firmware program adapted by Marinna Martini from examples provided by the manufacturer. This program was written in C and cross-compiled in the MPLAB Integrated Development Environment (MPLAB Tools v. 8.63) using a Microchip MPLAB C18 compiler on a Microsoft Windows operating system computer. The main program is mxwebsrvr.c, and a description of the program's functionality is provided in appendix 2.

Internet Protocol Addresses and Communication Port Assignments

Internet protocol (IP) addresses (table 3-5) were assigned to our system by WHOI system administrators and hard-coded into many of the programs. They are listed here to aid in the interpretation of the code.

Table 3-5. List of Internet addresses for USGS instruments while deployed at the MVCO node.

[See the Instrumentation section for a complete description of these instruments. See also Abbreviations and Symbols]
List of Internet Addresses for USGS instruments while deployed at the MVCO node
IP address MAC address Computer description 00:04:a3:00:00:01 Modtronix (arm control) 00:90:eb:22:53:2d Moxa   WebRelay 00:1b:eb:68:20:0d LISST-HOLO 00:04:a3:00:00:00 Modtronix (backdoor)

The Moxa had eight external RS-232 asynchronous communication ports. We used five for the Martha's Vineyard Coastal Observatory OASIS project. The instruments and settings assigned to the five ports are listed in table 3-6 to aid in the interpretation of the source code. Configuration files associated with the interactive communication program Minicom for specific instrument settings were stored (in /etc/minicom) so they could invoked with commands such as minicom adv, which would attempt to launch Minicom with settings appropriate for communicating with the blue SonTek ADV.

Table 3-6. Communication port assignments for the Moxa used in the 2011 OASIS experiment.

[Add one to each port number to get the corresponding RS-232 connection identification number on outside of Moxa main control computer. See the Instrumentation section for a complete description of these instruments. See also Abbreviations and Symbols]
Port Instrument Comm parameters1 Software flow control (XON/XOFF) Minicom configuration file
0 LISST-HOLO 19200 8 N 1 No holo
1 Accelerometer 2 (IG-20 on arm) 115200    
2 LISST-ST 9600 N 8 1 No lisst
3 Blue ADV and Hydra on arm and associated sensors 19200 N 8 1 N Yes adv
4 YSI CTD 9600 N 8 1 N Yes [default]
5 Red PCADP and Hydra on tripod and associated sensors 9600 N 8 1 N Yes pcadp
1Includes rate, stop bit, bits, check bit, and parity check.

Sequence for Power and Execution

Some of the programs assume that other operations or data streams are ready. Although the system was designed to boot and begin operations correctly after a power outage, the ideal starting sequence is as follows:

(1) Shoreside computer booted and ready (so that cron jobs for operating the LISST-HOLO and downloading data from the Moxa would run).
(2) Node power for side "A" (12 volts direct current (VDC)) applied (this provided power for the Moxa, the internal network switch, and the Web relay and allowed the Moxa to boot and begin receiving internet traffic).
(3) Node power for side "B" (24 VDC) applied (this provided power to the arm motor and Modtronix controller, which could then begin monitoring the arm and sending UDP packets to the Moxa; the Modtronix program used address resolution protocol (ARP) to confirm the network address of the Moxa, so it was important that the Moxa booted first).
(4) cron jobs execute on even hour.

References Cited

Hyde, R., 2004, Write great code, volume 1-Understanding the machine: San Francisco, California, No Starch Press, 445 p.

Kerrisk, M., 2010, The Linux programming interface: San Francisco, Calif., No Starch Press, 1,506 p.
Skip USGS links group

Accessibility FOIA Privacy Policies and Notices

Take Pride in America logo USAGov logo U.S. Department of the Interior | U.S. Geological Survey
End of USGS links group