Guralp Systems Limited
MAN-C3E-0002 - Güralp 3ESPCD Digital Broadband Seismometer (DM24 Versions) - Users' Guide

Chapter 6. Command line interface

6.1 Introduction

You can connect to the internal software of the digitiser over its output serial port and communicate with it. To enter command mode from Scream!, right-click on the digitiser's icon and select Terminal... from the menu that pops up. A window will open, and once the digitiser and computer are communicating properly you will see the prompt

ok

If you prefer, you can use a terminal program on your computer (such as minicom on Linux, or PuTTY on Microsoft Windows) to connect to the digitiser.

Whilst you are in terminal mode, data transfer will be interrupted; the digitiser may use any Flash memory as a temporary store, depending on how you have configured it. Some commands, such as SET-TAPS, require a reboot to take effect.

Güralp EAM and AM modules also allow you to send commands directly to the digitiser using command-line and/or web-based tools. For more information, please see the manual for your data module.

If you have problems connecting to the digitiser's console, you should check that the serial port's options and baud rate are set correctly in Scream! or your terminal program. As supplied, the digitiser expects connections at 19200 baud, with 8 data bits, no parity bit and 1 stop bit. No flow control is used.

6.1.1 FORTH

The digitiser uses FORTH to implement its features. To issue a command in FORTH, you must supply the arguments before the command, for example:

3 SENSOR-TYPE

In FORTH, anything you enter is termed a “word”. New words (case insensitive) are placed on a stack. Some words are known to the system, and may represent commands; if a command finds itself at the top of the stack (e.g. because it is the last thing you typed), they will execute, remove themselves from the stack, and then remove further items from the stack to use as arguments. Thus, in the command

3 SENSOR-TYPE

the 3 has no immediate effect, so stays on the stack; SENSOR-TYPE takes itself and the previous item (here 3) off the stack, then performs its action on the 3 (here, setting the configured sensor type to 3, representing a Güralp 3T sensor.)

If a command completes with nothing remaining on the stack, the digitiser will show the prompt ok. Otherwise, the prompt will remind you that the digitiser is waiting for you to complete the command. Some commands, such as SAMPLES/SEC, clear the stack automatically after they execute.

Some commands are interactive, and will ask you to provide extra information after you execute them. In the following sections, interactive commands are shown as example sessions, using the typographical conventions given in section 1.4.

6.2 General configuration

The following commands set the general configuration of the digitiser.

6.2.1 SET-ID

Syntax: SET-ID (interactive)

Sets the system identifier and serial number of the digitiser to values you supply:

SET-ID
System Identifier ? (e.g. ALPHA,)
DM24ID, Serial # ? (e.g. 1234,00) 4507,00

The system identifier that you supply may contain up to 6 alphanumeric (0-9A-Z) characters, and must have a comma after it. 6-character strings lexically greater than ZIK0ZJ are not permitted. The serial number you supply must contain exactly 6 alphanumeric (09A-Z) characters, and must have a comma after the fourth character.

6.2.2 SENSOR-TYPE

Syntax: type SENSOR-TYPE

Tells the digitiser which kind of sensor is attached to it. This affects whether or not the digitiser exposes commands such as locking and centring. The argument type can be one of

6.2.3 GPS-TYPE

Syntax: type GPS-TYPE

Tells the digitiser which kind of GPS is attached to it. The argument type can be one of

6.2.4 BAUD

Syntax: port baud-rate BAUD

Sets the baud rate for one of the serial ports on the digitiser, in bytes per second. The argument port is a small integer specifying the port: Most units have port 0 assigned to data output and communication, port 1 to GPS input, and port 2 to the DATA IN port. For example,

0 38400 BAUD
1 4800 BAUD
2 38400 BAUD

This will reset a standard single-sensor digitiser to its default configuration. The allowable values for baud-rate are 4800, 7200, 9600, 14400, 19200, 38400, 57600 and 1152 (for 115200 baud). GPS inputs should remain set at 4800 baud.

6.2.5 AZIMUTH

Syntax: instrument angle AZIMUTH

Some borehole digitisers can rotate incoming signals algorithmically as they are digitised. This feature allows you to compensate for an instrument being out of alignment with the North/South axis. To use it, first measure the orientation of the sensor, then connect to the digitiser and issue an AZIMUTH command, giving the angle you have measured.

The argument instrument tells the digitiser which instrument to apply the rotation to; 0 for a 4-channel digitiser.

The argument angle is the measured angle of deviation from the North/South axis, in tenths of a degree. The angle of deviation is the negative of the angle by which you want incoming signals to be rotated. Like all other parameters, it must be an integer (i.e. a whole number of tenths of a degree).

You can measure the orientation of a borehole sensor by placing a reference sensor nearby and carrying out coherence calculations. An extension to Scream! is available which can do this for you. For details, see the manual for Scream!, MAN-SWA-0001.

The AZIMUTH command only alters the digitiser's CMOS settings. You will need to re-boot the digitiser to transfer them to the DSP.

6.2.6 CROSS

Syntax: channel CROSS

Alters the DSP's transformation matrix to invert one of the digitiser channels.

The argument channel is one of 0 (vertical), 1 (N/S), 2 (E/W) and 3 (auxiliary).

The CROSS command only alters the digitiser's CMOS settings. You will need to re-boot the digitiser to transfer them to the DSP. If you need to set both AZIMUTH and CROSS, you must issue AZIMUTH first, since it overwrites the matrix.

6.3 Output configuration

The commands in this section control the serial data output.

6.3.1 SAMPLES/SEC

Syntax: tap-0 tap-1 tap-2 tap-3 samples/sec

The DSP software on the digitiser supports up to seven cascaded filter/decimation stages. At each stage, the sample rate can be decimated by a factor of 2, 4 or 5. The fixed decimation stages output data at 2,000 samples/sec, so decimated data streams are available from 1,000, 500 and 400 samples/sec down to 1 sample/sec.

You can specify the sample rate to use at four of these stages, known as taps. You can also take output from any of these four stages. The digitiser will arrange the remaining stages according to your settings.

The arguments tap-0 to tap-3 are the sample rates at each tap in turn, starting with the highest. You must ensure that each rate is lower than the previous one by a factor of 2, 4, 5, 8 (= 2 then 4), 10 (= 2 then 5) or 16 (= 4 then 4). Non-integer values are not allowed. The following four examples are all valid settings:

1000 125 25 5 samples/sec

1000 500 100 10 samples/sec

500 100 20 4 samples/sec

400 40 10 5 samples/sec

As long as you specify the initial taps, you can omit later ones. The command fills in the value of the missing taps, using a decimation factor of 2 where possible. Thus, the following commands are equivalent:

400 40 20 10 samples/sec

400 40 samples/sec

6.3.2 CONTINUOUS

Syntax: tap components CONTINUOUS

Sets which components are output under normal conditions, and at which tap(s).

The argument tap is the tap number at which to output the triggered stream. You can set which taps output which sample rates using the SAMPLES/SEC command, described above.

The argument components is an integer below 16, whose binary bits represent the Z (1), N (2), E (4) and auxiliary (8) components respectively. Thus, for example,

6.3.3 SET-TAPS

Syntax: tap-0 tap-1 tap-2 tap-3 SET-TAPS

This is an alternative to the CONTINUOUS command, which allows you to set the outputs for all taps simultaneously.

The arguments tap-0 to tap-3 are integers below 16, whose binary bits represent the Z (1), N (2), E (4) and auxiliary (8) components respectively. Each one sets which components are output at that tap under normal conditions. For example, if you issue

9 7 0 15 SET-TAPS

then

To set triggered output streams, you should use the TRIGGERED command detailed below.

6.4 Triggering

This section describes the commands which affect triggering.

6.4.1 TRIGGERS

Syntax: components TRIGGERS

Selects which component or components can generate a trigger. Only these components will be examined by the triggering algorithm.

The argument components is an integer below 16, whose binary bits represent the Z (1), N (2), E (4) and auxiliary (8) components respectively as described above. Issuing 0 TRIGGERS will disable the triggering system.

6.4.2 TRIGGERED

Syntax: tap components TRIGGERED

Selects which component or components will be output when a trigger is generated, and at which tap (sample rate).

The argument tap is the tap number at which to output the triggered stream. You can set which taps output which sample rate using the SAMPLES/SEC command, described above.

The argument components is an integer below 16, which represents which components to output in the same fashion as in the CONTINUOUS command, above.

(This command and the previous one have similar names; remember that a component TRIGGERS the system, whilst taps and components are TRIGGERED.)

6.4.3 STA

Syntax: Z-secs N-secs E-secs X-secs STA

Sets the length of the “short-term” averaging period in the STA/LTA triggering algorithm.

The arguments Z-secs, N-secs, E-secs and X-secs are the time period over which to calculate the average for the Z, N, E, and auxiliary components respectively. If a component is not considered by the triggering algorithm (see TRIGGERS, above), the value you specify here will be ignored. For example,

1 1 2 2 STA

will calculate short-term averages for 1 second of the Z and N components, and 2 seconds of the E and auxiliary components.

6.4.4 LTA

Syntax: Z-secs N-secs E-secs X-secs LTA

Sets the length of the “long-term” averaging period in the STA/LTA triggering algorithm.

The arguments Z-secs, N-secs, E-secs and X-secs are the time period over which to calculate the average for the Z, N, E, and auxiliary components respectively. If a component is not considered by the triggering algorithm (see TRIGGERS, above), the value you specify here will be ignored. For example,

15 20 20 20 STA

will calculate long-term averages for 15 seconds of the Z component and 20 seconds of the N, E and auxiliary components.

6.4.5 RATIOS

Syntax: Z-ratio N-ratio E-ratio X-ratio RATIOS

Sets the ratio of STA to LTA above which a trigger will be declared in the STA/LTA triggering algorithm.

The arguments Z-ratio, N-ratio, E-ratio and X-ratio are the time period over which to calculate the average for the Z, N, E, and auxiliary components respectively. If a component is not considered by the triggering algorithm (see TRIGGERS, above), the value you specify here will be ignored. For example,

4 10 10 10 RATIOS

will cause the digitiser to trigger if the STA/LTA ratio is above 4 for the Z component or above 10 for the remaining components.

6.4.6 PRE-TRIG

Syntax: time PRE-TRIG

Sets the pre-trigger recording time. The argument time is the number of seconds of data to output from before a trigger is declared.

6.4.7 POST-TRIG

Syntax: time POST-TRIG

Sets the post-trigger recording time. The argument time is the number of seconds of data to output after a trigger condition lapses. If an event persists for some time, all triggering components must fall below the threshold before the trigger condition will lapse; only then will the post-trigger period begin.

6.4.8 TRIGGERIN

Syntax: TRIGGERIN ENABLE | TRIGGERIN DISABLE

Enables or disables external trigger input, in instruments equipped with this option.

Enabling external trigger input allows you to trigger the digitiser from an external logic level supplied through its digital output port. This voltage can be between 5 and 10 V supplied between the Trigger In pin and signal ground. If the digitiser is triggered externally, it will behave exactly as if it had generated the trigger itself.

6.4.9 TRIGGEROUT

Syntax: TRIGGEROUT ENABLE | TRIGGEROUT DISABLE

Enables or disables external trigger output, in instruments equipped with this option.

Enabling external trigger output allows you to trigger other equipment through a relay contained within the digitiser whenever it triggers. The digitiser's digital output port contains two pins (Trigger out, common and Trigger out, normally-open) which are connected when it triggers. In particular, you can connect a second digitiser with TRIGGERIN ENABLE in effect, in which case triggered data from both instruments will be transmitted whenever the digitiser triggers.

If a digitiser has both TRIGGERIN ENABLE and TRIGGEROUT ENABLE in effect, only triggers which the digitiser itself has generated will be output. Triggers received through the Trigger in port will cause the digitiser to output triggered streams, but will not be passed on to other digitisers.

6.5 Calibration

These commands are all concerned with calibration.

6.5.1 SINEWAVE

Syntax: component freq-or-period unit SINEWAVE

Instructs the digitiser to inject a sine-wave calibration signal, starting on the zero crossing.

The argument component specifies which component is to be calibrated, one of Z, N/S, E/W, or X. Some sensors use only the Z calibration loop for all three components.

The arguments freq-or-period and unit together determine the frequency of the calibration signal. If unit is HZ, then freq-or-period is taken as a frequency, in Hz; if SECOND, then it is interpreted as a period, in seconds.

For example:

N/S 4 HZ SINEWAVE

The argument freq-or-period must be an integer; if you want to specify a period of, for example, 0.5 s, you should specify it as 2 HZ instead. T he calibration signal will be automatically disconnected after 2 minutes if you have not altered the setting using the MINUTE command, described below.

Whilst calibration is in progress, the fourth (auxiliary, or X) data channel is switched on to monitor the returning calibration signal.

6.5.2 SQUAREWAVE

Syntax: component SQUAREWAVE

Instructs the digitiser to inject a square-wave (step function) calibration signal, consisting of a positive step on the start of the next clock minute, followed by a negative step some minutes later (by default, 2). The calibration is disconnected the same number of minutes after the negative edge.

The argument component specifies which component is to be calibrated, one of Z, N/S, E/W, or X. Some sensors use only the Z calibration loop for all three components. You can alter the duration of each step using the MINUTE command, described below.

Whilst calibration is in progress, the fourth (auxiliary, or X) data channel is switched on to monitor the returning calibration signal.

6.5.3 RANDOMCAL

Syntax: component RANDOMCAL

Instructs the digitiser to inject a white-noise calibration signal generated by an on-board pseudo-random number generator.

The argument component specifies which component is to be calibrated, one of Z, N/S, E/W, or X. Some sensors use only the Z calibration loop for all three components.

The calibration signal will be automatically disconnected after 2 minutes if you have not altered the setting using the MINUTE command, described below.

Whilst calibration is in progress, the fourth (auxiliary, or X) data channel is switched on to monitor the returning calibration signal. The pseudo-random number generator produces true white noise over the entire passband, as shown in the power spectral density plot below:

The different coloured lines show the results of experiments which measure the power spectral density over several frequency bands. Together, the results show a flat noise level over the entire passband to within experimental error.

6.5.4 MINUTE

Syntax: duration MINUTE

Sets for how long the next SINEWAVE or RANDOMCAL calibration signal will be injected, or the period of the next SQUAREWAVE calibration signal.

The argument duration is the desired interval, in minutes. If you now issue a SINEWAVE or RANDOMCAL command, the calibration will last duration minutes; if the next calibration command is SQUAREWAVE, a positive step of duration minutes will be generated, followed by a negative step of a further duration minutes.

If you do not issue MINUTE, calibration signals will default to 2 minutes. This is to avoid the sensor and digitiser inadvertently being left in calibration mode. Issuing, e.g., 5 MINUTE will cause the next calibration signal to last 5 minutes, but later calibration signals will revert to a duration of 2 minutes. You will need to issue a MINUTE command before each injection.

Because of the way FORTH works, you can insert MINUTE commands into SQUAREWAVE, SINEWAVE or RANDOMCAL commands, for example:

N/S 4 HZ 5 MINUTE SINEWAVE E/W 10 MINUTE SQUAREWAVE

6.5.5 %AMPLITUDE

Syntax: value %AMPLITUDE

Sets the relative amplitude of the signal, as a percentage. For SQUAREWAVE and RANDOMCAL calibrations, the default of 100% is normally suitable. If you have a high-gain sensor, you may have to use a lower value. For SINEWAVE calibrations, you may have to adjust the %AMPLITUDE setting to suit the frequency of the calibration signal.

You can insert %AMPLITUDE commands into calibration commands as described above, e.g.:

Z 3 MINUTE 50 %AMPLITUDE RANDOMCAL

6.6 Actions

The commands in this section trigger specific actions, such as mass-locking.

6.6.1 LOCK

Syntax: LOCK

Locks the sensor mass of the instrument. Whilst this process is executing, the system displays the mass position for each component, measuring one position each second (i.e. one reading every 4 seconds for each component of a 4-component instrument). The process returns when locking is complete. The mass positions are measured to 16-bit accuracy, with full deflection corresponding to values around ±32000 counts.

6.6.2 UNLOCK

Syntax: UNLOCK

Unlocks the sensor mass, and returns when unlocking is complete. The system will display the mass positions as the process continues, as for LOCK, above.

6.6.3 CENTRE

Syntax: CENTRE

Centres the sensor mass, and returns when centring is complete. The system will display the mass positions as the process continues, as for LOCK, above. When the mass is correctly centred, the readings should be less than ±1000 counts.

6.6.4 RE-BOOT

Syntax: RE-BOOT (interactive)

Causes the digitiser to reset after a delay of 2 seconds.

RE-BOOT
Confirm with 'y' ?
y

Responding to the confirmation message with anything other than y will abort the reset.

6.7 Data storage and recovery

These commands control how data are stored, transmitted and recovered from the internal flash storage.

6.7.1 SHOW-FLASH

Syntax: SHOW-FLASH

Reports status information about the Flash memory in the digitiser, if fitted. For example, the SHOW-FLASH output for a new system with 8 × 64Mb chips fitted might be

512MB Flash File buffer : 16 Blocks Written 0 unread 524,288 Free
Oldest data [16] Blank
Read point [16] Blank
Latest data [16] Blank
File Replay [16] Blank

Similarly, SHOW-FLASH on a system in use with 1 × 64Mb chip fitted might display:

64MB Flash File buffer : 65,536 Blocks Written 65.532 Unread 4 Free
Oldest data [36,272] GURALP TESTZ1 2004 12 3 20:20:41
Read point [36,272] GURALP TESTZ1 2004 12 3 20:20:41
Latest data [36,268] GURALP TESTX2 2004 12 4 10:09:12
File Replay [36,272] GURALP TESTZ1 2004 12 3 20:20:41

The first line displays general status information, namely the quantity of Flash memory available (64MB Flash File buffer), how many 1k GCF blocks have been written (65,536 Blocks Written), how many remain to be transmitted (65,532 Unread), and how much space (in 1k blocks) remains (4 Free).

The next lines show, in turn:

The read pointer normally points to the oldest data in the file; however, if all the data up to the replay point have already been downloaded, the read pointer is set to the replay point and the number of blocks remaining unread is updated. Downloads where a time-period is not specified always start from the read pointer.

6.7.2 DIRECT

Syntax: DIRECT

Instructs the digitiser not to use Flash memory for storage. Instead, all data are transmitted directly to clients. A temporary RAM buffer allows clients to request blocks they fail to receive using the Block Recovery Protocol.

6.7.3 FILING

Syntax: FILING

Instructs the digitiser not to transmit blocks to clients, but to store all digitised data in the Flash memory. The memory is used in circular fashion, i.e. if it becomes full, incoming blocks begin overwriting the oldest in memory.

6.7.4 ADAPTIVE

Syntax: ADAPTIVE

Instructs the digitiser to transmit current blocks to clients if possible, but to store all unacknowledged blocks in the Flash memory and resend them when time allows. This differs from DIRECT in the following ways:

Adaptive mode is best suited for installations where the link between digitiser and client is intermittent or difficult of access.

6.7.5 FIFO

Syntax: FIFO

Instructs the digitiser to begin writing blocks to Flash memory as for FILING, but also to transmit data to clients. Data are transmitted in strict order, oldest first; the digitiser will only transmit the next block when it receives an acknowledgement of the previous block.

6.7.6 DOWNLOAD

Syntax: DOWNLOAD

Sets up a data transfer from the Flash memory over the serial connection. Which data are downloaded depends on various parameters you can set, which allow you to select a particular stream, streams of a specified sample rate, or streams within a certain time window. You can set parameters separately, or string the definitions before the DOWNLOAD command, e.g.

ALL-FLASH STREAM HPA0N1 DOWNLOAD

2004 12 01 00 00 FROM-TIME ALL-DATA DOWNLOAD

100 S/S ALL-TIMES DOWNLOAD

DOWNLOAD with no arguments starts another download with the same parameters as last time. See below for full details of the parameter commands.

The DOWNLOAD command returns immediately, so that you can issue more commands if required. To close the connection and begin downloading, issue the GO command. You can pause the download by entering terminal mode, and restart with another GO or abort with END-DOWNLOAD.

6.7.7 ALL-FLASH

Syntax: ALL-FLASH

Sets the read point to the oldest data held by the digitiser. This command does not alter which streams are to be transmitted; you should specify streams or use the ALL-DATA command in addition to this one.

6.7.8 ALL-DATA

Syntax: ALL-DATA

Instructs the digitiser to transmit all the data streams it holds next time a DOWNLOAD is issued. This command does not alter the read point or time period; you should specify a time period or use the ALL-FLASH command in addition to this one.

6.7.9 STREAM

Syntax: STREAM stream-id (n.b.)

Instructs the digitiser to transmit only the stream with ID stream-id. Stream IDs are normally a 4-character device code (e.g. HPA0) followed by a component letter (N) and a tap number (1). Unlike most FORTH commands, the stream-id parameter goes after the command.

6.7.10 STATUS-ONLY

Syntax: STATUS-ONLY

Instructs the digitiser to transmit only status streams (text streams, normally with stream IDs ending in 00.)

6.7.11 S/S

Syntax: rate S/S

Instructs the digitiser to transmit only streams with sample rates equal to rate. If rate is zero, only status streams are transmitted. Note that this command should not be confused with the SAMPLES/SEC command.

6.7.12 ALL-TIMES

Syntax: ALL-TIMES

Clears any time selection in force, allowing you to download all data held by the digitiser. This command does not alter which streams are to be transmitted; you should specify streams or use the ALL-DATA command in addition to this one.

6.7.13 FROM-TIME

Syntax: yyyy mm dd hh mm FROM-TIME

Instructs the digitiser to transmit only data more recent than yyyymm-dd hh:mm, where

6.7.14 TO-TIME

Syntax: yyyy mm dd hh mm TO-TIME

Instructs the digitiser to transmit only data more recent than yyyymm-dd hh:mm, where yyyy, mm, dd, hh and mm have the same meanings as in FROM-TIME, above.

6.7.15 GO

Syntax: GO

Closes terminal mode, and begins any download that you have set up. You can pause the download by re-entering terminal mode, and restart with another GO or abort with END-DOWNLOAD. Once the download has completed, the digitiser will carry on transmitting real-time data, if you have so configured it.

6.7.16 END-DOWNLOAD

Syntax: END-DOWNLOAD

Aborts any downloads which were in progress at the time you entered terminal mode.

6.7.17 DISKMENU

Syntax: DISKMENU (interactive)

Allows you to select various options for downloading data over the optional FireWire interface. When you issue this command you will see the message

Plug in FireWire cable

and the digitiser will wait for you to plug in a compatible disk. When it detects one, it will print out information about the disk:

FireWire Connection *BR
Node: FFC1 #Nodes 2
Reading Node FFC0 .
LaCie Group SA
1394-IDE Rev B2
LaCie DATA BANK drive LUN 0
Logging on @AgentCSR= 0010:00000
Capacity 39.0GB

Press a key for options else
7 seconds to automatic disk backup

At this point, pressing a key will cause the digitiser to bring up an options menu and pause. If you do not press a key within seven seconds, the disk will be automatically backed up.

Disk Options :-
(A) save All data
(N) save New data
(S) save Selected time window
(D) Directory – contents
(R) Reset disk – overwrite
(X) eXit
A/N/S/D/R/X ?

During the operation of any of these options, progress reports will occasionally be printed out and shown on the terminal, as well as on the on-board LCD screen, if fitted.

6.7.18 MBTRANSFER

Syntax: size MBTRANSFER

If a FireWire disk is plugged in to the digitiser outside the DISKMENU system, and there is enough new data in Flash memory, it will automatically transfer the new data to the disk. The MBTRANSFER command sets how much new data there needs to be, before the digitiser will power up the disk and transfer it. If the disk is left attached, the digitiser will then wait until it has collected the same amount of data again before starting another transfer.

The argument size is the amount of data to transfer, in megabytes; it must be greater than 10 and less than the total quantity of Flash memory in the device. Larger values will save power, because the disk needs to be accessed less often.

If you plug a FireWire disk into the digitiser when there is less than size Mb of data ready, no data will be transferred. If you need to transfer smaller amounts of data, you should use the DISKMENU system.

6.7.19 ERASEFILE

Syntax: ERASEFILE (interactive)

Removes all data from the Flash memory, and resets all pointers to the beginning. You will be asked for confirmation before you do this, as all data will be destroyed.

If you have been running the digitiser with a FireWire disk attached, remember that there will be some data still in Flash memory awaiting transfer, up to the amount you last set with MBTRANSFER. You should make sure these data are transferred with the DISKMENU command before you ERASEFILE.