Chapter 8. Inside the DCM
The DCM is a fully-functional, Linux-based computer system especially designed for handling seismic data. It can collect and store data from several sources and, if required, output it in your preferred format to other locations on your network or on the Internet. This is done in the following manner.
Firstly, the DCM receives some data from an instrument connected to it. This can be any of
a digitizer connected through a serial link,
a computer running a Scream! server,
a CD1.0 or CD1.1 transmitter (optionally), or
another DCM or AM.
All the received data is stored in files in the on-board Flash memory. There are two banks of Flash memory available, which are accessible as /nand0 and /nand1 in the Linux file tree. Data is normally stored as GCF (Güralp Compressed Format) files.
As an option, you may be able to configure the DCM to use the miniSEED or sac formats instead (see Section 6.3, page 86.)
In automatic mode, when the Flash memory becomes more than 75% full, the oldest data files are moved to the DCM's primary hard disk until it is less than 50% full. If you prefer, you can configure the DCM to write to the hard disk at set intervals.
Writing to the hard disk is performed robustly, so that no data will be lost if a write is aborted (see Section 8.1, page 116.) This means that you can safely swap hardware in and out at any time. Stand-alone DCM modules use off-the-shelf Lacie hard disks, which can be easily removed and installed in most conditions. You can specify other models of IDE / USB or IEEE 1394 2.5” disk at manufacture. If an internal disk is not present, and the module has a USB host interface, it will look for hard disks connected to its external USB port.
Once the data is stored on the DCM, whether in Flash memory or on the hard disk, it can be retrieved
by a remote computer running Güralp Systems' Scream!, or other GCF-compatible software;
by another DCM or AM, also using GCF;
by setting up a CD1.0 or CD1.1 transmitter on the DCM;
by direct file transfer (using SSH, HTTP, HTTPS, etc.,)
optionally, by requesting the data using SeedLink or AutoDRM.
A PC running Güralp Systems' Scream! software can not only collect data from the DCM, but also configure the module and any instruments attached to it.
You may need to enable and configure some of these methods before you can use them: see Chapter 6, page 80, for more details.
Most installations of the DCM will not require any more complex setting up than the Web configuration system can offer. However, in some cases you may need to take advantage of the flexibility offered by the underlying Linux operating system.
8.1 File systems
The DCM uses the standard Unix/Linux file naming conventions. The operating system resides in two blocks of Flash memory, mounted on / and /boot; when the module is powered up, a separate boot loader loads the rest of the operating system.
Once the operating system is loaded, the main Flash memory blocks (where present) are mounted on /nand0 and /nand1. Incoming data, which may be from several sources, is combined into a single stream and placed in one of these blocks (whichever is less full). When in use, you can expect each to be between 50% and 75% full, with several da:ta files present. If the DCM is using GCF as its storage file format (recommended; see Section 6.3, page 86) then each file will be named after the timestamp on its first packet of data, in the following fashion:
file-yyyymmdd-jjj-s-cccccccc.gcf where yyyymmdd represents the date of the earliest data packet in the file, jjj the number of full days elapsed since midnight on January 1, s the time segment within the day (each day is divided into eight 3-hour segments), and cccccccc a unique hexadecimal code included to ensure filenames do not coincide.
When one of the Flash memory blocks approaches capacity, or after a fixed time period (if you have configured it to do this) the DCM will automatically move them onto the primary USB hard disk. This may be either an internal Lacie hard disk, or an external drive connected to the module through a USB client interface. This disk uses a specially-designed journalled filesystem, which is designed to maintain the integrity of your data at all times. Even if a write operation fails or is aborted suddenly, the disk will still contain a valid filesystem with all previously-saved data intact, which can be read using any driver that supports FAT32.
There is a set of specialised commands which allow you to perform basic tasks on this filesystem:
gfat32df : Displays the size of the filesystem, and how much free space remains, in a format similar to this:
FAT32 filesystem has 15 G bytes free
Partition is 37 G bytes (78140097 blocks of 512 bytes)
If no suitable storage medium can be found, you will see the message Failed to find a USB disk.
diskman : Ensures that the /nandx partitions do not become full by moving files when necessary. This program ordinarily runs constantly in the background. However, a user can use the command diskman -f to force the Flash memory to be entirely copied to the USB disk. Typing diskman -f is identical to clicking the Flush flash button on the Disk tools page. It does not remove data from the Flash memory. If you issue diskman -f and then swap hard disks, the data remaining in memory will later be written out to the new hard disk, causing some overlap between it and the old disk.
Whilst the DCM is copying the contents of the Flash memory to disk, you will be shown a log of its progress. The USB interface can transfer data at a speed around 100 Kb/s, so large files may take several minutes to complete.
Once a file has been moved from the Flash memory to disk, any further data received which would otherwise be appended to that file will instead be placed in a new file in the Flash memory. Because of this, a stream may occasionally be fragmented. The automatic options are chosen to minimize this likelihood by only moving the oldest files, and by keeping files in Flash memory for a reasonable period of time. If you choose to transfer files to disk more often than this, more files will be fragmented.
gfat32 ls : List the files present on the hard disk, with the size of each file.
gfat32 cpf filename-on-disk destination-filename : Copy a file from the disk into temporary storage in the Linux filesystem (e.g. in your home directory.) Once the file is in the Linux file system, you can modify or convert it using your own scripts running on the DCM, or use programs such as scp to transfer it to a remote machine.
gfat32 cpt source-filename filename-on-disk : Copy a file from the Linux file system onto the disk.
gfat32 mv filename new-filename : Rename a file on the disk.
8.2 Command line tools
The DCM module's Linux operating system can be accessed over a network via SSH. There are many programs available for your computer which implement this protocol: ssh is included as part of most Linux and Unix distributions, whilst for Windows putty is a reliable free client. ssh is essentially a secure version of programs like rlogin and telnet, and provides a simple command line interface to the device. Access to the DCM by SSH is enabled by default, although you can disable it using the net.remoteaccess.ssh configuration option.
In addition, if you have so configured it, you can connect directly to an RS232 port running the getty service.
Once the connection has been set up and you have logged in, you will then be shown a command prompt:
~ #
By default, your account uses the standard Bourne shell, sh. If you prefer, the more advanced shells ash and bash are also available. Many standard Unix programs are also present: ls, cat, more, sed, etc.
The following sections describe how to operate a DCM from the Linux command line, including descriptions of all commands unique to the DCM. Any of these commands can be included in your own shell script files, which can be run as services on the DCM or remotely using a ssh connection as required. If you need to compile your own C or FORTRAN programs to be run on the DCM, please contact Güralp Systems for assistance.
8.3 Configuration
Configuring the DCM is automated by a suite of command line tools. These maintain a configuration database and check that all the relevant Linux files are kept up to date. If you alter the standard Linux configuration files, you should bear in mind that these tools will overwrite them without checking that they match the information in the database. Because of this you should use the tools wherever possible rather than editing the files directly. The DCM's Web-based configuration system is just a front-end to these tools.
gcfgdbls prefix : Enter this command to find out which configuration options begin with the prefix prefix (case sensitive—all the configuration options are in lower case). The options are listed in alphabetical order. For example:
~ # gcfgdbls serial.0
serial.0.baudrate
serial.0.handshaking
serial.0.ppp
serial.0.service
gcfgdbset option-name new-value : Enter this command to set the value of the named option to new-value. The database will perform a simple type check on your value (for example, to check that certain options are numbers), but will not otherwise make sure that your change makes sense.
gcfgdbget option-name-or-prefix : Enter this command to find the current value of the named option. Instead of a single option name, you can also use a prefix (as described above) to find out the values of a range of options. The remaining tools also allow you to use prefixes in place of full option names.
Each option in the database can be marked either as “clean” or as “dirty”. This flag tells the DCM whether the database is currently in sync with the state of the device. Whenever you alter the value of an option using the gcfgdbset tool, or using the Web interface, the option is marked as “dirty”; the DCM then alters its configuration, and marks the option as “clean” again, to signify that the change completed successfully. Three more commands are provided to allow you to access this flag:
gcfgdbmark clean option-name-or-prefix : Enter this command to mark the named configuration option as “clean” in the database.
gcfgdbmark dirty option-name-or-prefix : Enter this command to mark the named configuration option as “dirty” in the database.
gcfgdbisdirty option-name-or-prefix (option-names-or-prefixes...) : This command finds out whether any of the named options is marked as “dirty”. If none are marked, the command exits successfully; otherwise, it exits with a failure code. Thus you can use gcfgdbisdirty in your own shell scripts, to perform actions depending on the status of the DCM's configuration options.
Note that marking an option as “dirty” will not necessarily lead to any action being taken. For example, you cannot force a service to be restarted using these commands.
Each of the four tools can also take two command-line options:
gcfgdbxxx -h : Displays a short usage reminder about the command gcfgdbxxx. All other arguments will be ignored.
gcfgdbxxx -c config-database other-arguments : Normally, all the gcfgdbxxx commands work on the system configuration database. However, you can supply the file name of an alternative database using the -c option, in which case the command will be performed on that database instead.
For a detailed description of the configuration options in the database, see Chapter 6, page 80.
The command gcli allows you to pass commands directly to the digitizer's console. The syntax is:
gcli port-number [-f] [-r] command
where port-number refers to the serial port connected to the digitizer. You can use serialmap to discover which serial port has which number, as described below. command is a DM24 FORTH command, which may contain several words. For information on the commands available on the DM24, please see its own documentation.
gcli will wait for the digitizer command to finish before exiting, and will only output any response from the digitizer afterwards. If you need to issue a command which monitors a value, you will need to connect to the digitizer's console directly using Scream! or minicom.
If you want to pass special characters to gcli, using the -f option allows you to use backslash sequences as used by the C command printf (e.g. \t = tab character, \n = newline, \r = carriage return, \a = bell, etc.) You can use \r to issue several commands to the digitizer in one session, since the carriage return will cause the digitizer to act on the previous command.
Passing the -r option causes the digitizer to reboot automatically once the command is completed. This is useful if you are using gcli to change the configuration of the digitizer, since many options require a restart for any changes to take effect.
If you need an interactive session with the digitizer, you can use the Linux terminal program minicom, which has been configured specially to cooperate with the DCM's various serial services. You can open a session with a digitizer by issuing the command
minicom -n port-number
If the port you specify is set to gcf_in, the DCM will automatically interrupt the data flow from the digitizer to allow you to enter commands.
When you have finished your session, press CTRL-a then q. minicom will ask you if you want to quit without resetting the connection. Choose yes to return the digitizer to data mode.
8.4 Monitoring
You can check that the DCM is receiving data either by monitoring the Summary page of the on-board Web interface (see Section 4.1, page 51), or from a command prompt using the command gnblocks:
Key 0x007000: Blocks 0 (Port 0, name Data out port, device /dev/ttySA0, baud 115200)
Key 0x007001: Blocks 0 (Port 1, name Port B, device /dev/ttySA1, baud 9600)
Key 0x007002: Blocks 149 (Port 2, name Port A, device /dev/ttySA2, baud 38400)
This command shows, for each port:
the Key number (in hexadecimal) of the process on that port which deals with incoming blocks,
the number of blocks received by that process,
the internal port number of the port,
the name you have assigned to it,
the port's Linux device name, and
the baud rate currently in operation on the port.
You can query a single port by using the port number or key as arguments to the gnblocks command:
gnblocks 2
gnblocks 0x7002
gnblocks 28674
(In the last example, 28674 is the key ID 0x7002 expressed in decimal: hex 7002 = 7 × 163 + 2 = 28674.)
Another way to find out the index, key ID, name or device name of a particular serial port is to issue the command serialmap. A line will be output for each serial port, in the form
Port 0, Key 7000, name tts0, device /dev/ttyS0, baud 115200
where port and baud are in decimal, and Key in hexadecimal. The related command serialmap -k returns the key ID in decimal.
The Güralp DM24mk3 digitizer outputs status information as a separate stream. If you have a DM24mk3, you can monitor this stream with the command
dm24mk3cds -s port-number
Whilst this program is running, it will output any status blocks it receives on that port directly onto your terminal:
HPA1CD: Wed Jun 30 14:51:13 2004
gps_fix=2 (0x32)
gps_mode=A (0x41)
gps_control=255 (on)
gps_power=255 (on)
gps_offset=167 ticks
busy_counter=0 ticks
locking=0 unlocking=0 centering=0
calibration V N E
The information given, after the stream ID (which will always end in CD), is as follows:
a time-stamp for the status block;
whether the GPS has obtained a fix (0 = has not received any data, 1 = has not obtained a fix, 2 = has obtained a 2D fix, and 3 = has obtained a 3D fix);
the mode the GPS is running in (A = automatic, and M = manual);
whether or not the system clock is being controlled by the GPS (255 = on);
whether the GPS is currently powered up (255 = on);
the current measured offset between GPS and the internal clock, in units of 500 ns;
the current value of the “busy” counter, which counts down towards zero whilst certain digitizer processes (such as calibration) are active;
whether the sensor is currentlty being locked, unlocked, or centred;
which, if any, of the channels are currently being calibrated (the channel appears with a + if this is the case).
The command tamper provides information about the current state of the DCM tamper lines. Issued with no arguments, it will output the status of all tamper lines once every 10 seconds. Including the -w option causes it to exit after printing the status once only:
[root@dcm-87AD9C933DE1 ~]# tamper -w
Input State Last Closed (Low) Last Open (High)
0 open (never) Mon Jan 5 21:50:37 1970
1 open (never) Mon Jan 5 21:50:37 1970
2 open (never) Mon Jan 5 21:50:37 1970
3 open (never) Mon Jan 5 21:50:37 1970
4 open (never) Mon Jan 5 21:50:37 1970
5 open (never) Mon Jan 5 21:50:37 1970
6 open (never) Mon Jan 5 21:50:37 1970
7 open (never) Mon Jan 5 21:50:37 1970
8 closed (never) (never)
9 closed (never) (never)
10 closed (never) (never)
11 closed (never) (never)
12 closed (never) (never)
13 closed (never) (never)
14 closed (never) (never)
15 closed (never) (never)
The output of the tamper command is included on the Summary page under Actions on the DCM Web site.
8.5 Updating the DCM
The easiest way to ensure that your DCM has all the latest software packages is to update it over the Internet.
The DCM is provided with a simple command-line script, upgrade, which checks for new versions of all packages in the distribution on the Güralp Systems Web site and installs them as necessary. It also rebuilds the configuration database to work with the new packages, resets it, and reboots the machine.
Running upgrade will restore the DCM to its factory settings, so make sure you will still be able to communicate with it before you issue the command, either
over a serial link to the DATA OUT port (115200 baud, 8 data bits, no parity bit, 1 stop bit, no flow control), or
over a DHCP-enabled network (using an IP address provided by the DHCP server.)
If your DCM does not have access to the Internet, you can update its software from a connected USB disk. You will need to make a copy of all the files in the directory http://www.guralp.net/cmgdcm/feeds, including all subdirectories, in a directory called /cmgdcm/feeds on the hard disk. On Linux, you can do this with the command
wget -np -nH -m http://www.guralp.net/cmgdcm/feeds
Once the files are on the hard disk, you can install it in a DCM and transfer the packages with the command
upgrade gfat32
This facility is available with versions 2.10 and greater of the upgrade package.
The DCM as shipped includes a package gsl-backdoor which enables Güralp Systems to respond to support issues by remote administration (e.g. installing updated firmware or packages.) If you prefer not to allow Güralp Systems access to the DCM you should use the command
ipkg remove gsl-backdoor
to remove the package. This will not affect the operation of the system in any other way; however, it may prevent Güralp Systems' engineers from being able to assist you in the event of problems.
ipkg can also be used for other package management tasks; however, if you remove software from the DCM, or replace packages with versions incompatible with the rest of the system, you risk leaving the unit in an unrecoverable state. We recommend that you use only upgrade wherever possible, to ensure that you have a fully tested set of packages.
Reinstalling the firmware from scratch is a more involved process, and you should only need to do it if the root or boot partitions of the DCM become corrupted. In this case, you can use the boot loader (which is resident in hardware) to update them. You will need a second DCM or Linux computer attached to the console port in order to do this.
Note that the firmware is not the same as the distribution. If you want to ensure that your DCM has all the latest software, you should use the upgrade command described above. Reinstalling the firmware will reset any changes you have made to the system.
The procedure for installing new firmware depends on which revision of the DCM design you have. All recent DCM units use “MkII” firmware. If you are unsure which hardware type you are using, contact Güralp Systems.
Mark II DCMs and AMs have a 256 kb bootloader, a 1 Mb kernel image and a 64 Mb file system image. Currently all surface DCM units are the Mark II design.
Download the latest revision of the root (and boot, if appropriate) files from the Güralp Systems website at http://www.guralp.net/software/modules/DCM/
Obtain the flashdcm tool from the same site. This is a Linux utility which enables you to access the DCM's firmware. If you are using a second DCM, flashdcm will already be present on it.
Note the baud rate of the DCM's console port (115200 by default).
Power down the DCM.
On the second computer or DCM, issue the command
flashdcm -r root-file -b boot-file -s baud-rate -p root-password -d port
where root-file and boot-file are the images you wish to transmit, baud-rate is the baud rate of the DCM's console port, root-password is the password of the user root on the DCM (not any other administrative account), and port is the port number of the serial interface (on the second computer or DCM) which you will be using.
If the device has several serial interfaces, the command serialmap may help you determine which port number corresponds to which device:
[root @ dcm] # serialmap
Library version: libserialmap Version 1.0.5 with LIBGCONFIGDB
4 serial ports
Port 0, Key 7000, name ttyS0, device /dev/ttyS0, baud 38400
Port 1, Key 7001, name ttyS1, device /dev/ttyS1, baud 19200
Port 2, Key 7002, name ttyS2, device /dev/ttyS2, baud 19200
Port 3, Key 7003, name ttyS3, device /dev/ttyS3, baud 19200
flashdcm also has an -e option, which wipes clean the Flash memory used for the filesystem before providing the new firmware. Some surface DCM units require you to do this when installing a root image. If you use the -e option to install a root image, you must also provide a new boot image, since the boot image in memory will be erased.
Power up the DCM. The second computer or DCM will detect messages coming from the bootloader of the DCM, and automatically interrupt the boot process to provide the new firmware.
Wait for the new firmware to be uploaded. The DCM will reboot automatically at the end of transmission, and the flashdcm process will terminate. This may take several minutes.
At this point, you will have a minimal installation of the DCM software, and can proceed to commissioning the system.