3. Modules and Settings

You will need to adjust the settings file before running rsudp in order to both receive data and suit your earthquake detection and notification needs. Additionally after changing settings, you will need to restart rsudp to load new values.

By default, the rsudp settings file will live in $HOME/.config/rsudp/rsudp_settings.json, where $HOME is your home directory (often shortened to ~/). To output default settings to a different location, see Starting manually on Windows or Unix.

For convenience, you can use rsudp’s built-in rs-settings command (rsudp.entry_points.ep_edit_settings()) to call your system’s default editor to edit the settings file.

3.1. settings (general settings)

The "settings" portion of the settings file contains some basic items: "port", "station", "output_dir", and "debug". Change "port" if you are receiving the data at a different port than 8888. To set your station name, change the value set for "station". "output_dir" will contain folders for miniSEED data and plot screenshots, which are explained in the relevant sections (write and plot) below. The directory specified here will be created if it doesn’t already exist. "debug" controls how much text is sent to the command line STDOUT (even if this is false, output will always be sent to a log at /tmp/rsudp/rsudp.log).

3.2. plot (live data plot)

"plot" controls rsudp.c_plot.Plot, the thread containing the GUI plotting algorithm. This module can plot seismogram data from a list of 1-4 Shake channels, and calculate and display a spectrogram beneath each.

By default the plotted "duration" in seconds is 30. The plot will refresh at most once per second, but slower processors may take longer. The longer the duration, the more processor power it will take to refresh the plot, especially when the spectrogram is enabled. To disable the spectrogram, set "spectrogram" to false in the settings file. To put the plot into fullscreen window mode, set "fullscreen" to true. To put the plot into kiosk mode, set "kiosk" to true.

Note

Kiosk mode will force the plot to fill the entire screen. To exit, press Ctrl+W or Alt+Tab (Command+Tab on Mac OS) to bring up a window switcher).

Note

On a Raspberry Pi 3B+, plotting 600 seconds of data and a spectrogram from one channel, the update frequency is approximately once every 5 seconds, but more powerful processors will be able to accommodate a higher refresh speed.

Note

Because the plot module is queue-based, it will not drop any packets received, no matter the processor. Dropped packets (if you experience them) are most likely a sign of network issues where the missing data never actually arrives at the receiving machine.

By default, the "channels" field is ["HZ", "HDF"]. This will resolve to at least one channel of any Shake input. "HZ" will match either "SHZ" or "EHZ" depending on your Shake digitizer model, and "HDF" will match the pressure transducer channel on a Raspberry Boom or Shake & Boom. If one of the channels in the list doesn’t exist in the data sent to the port, it will be ignored.

The program will use the Raspberry Shake FDSN service to search for an inventory response file for the Shake you specify in the "station" field. If it successfully finds an inventory, setting “deconvolve” to true will deconvolve the channels plotted to either "ACC" (acceleration in m/s^2), "VEL" (velocity in m/s), or "DISP" (displacement in m). The default is "CHAN" which lets the program deconvolve the channel to its native units (acceleration for accelerometers, and velocity for geophones). This means that the Shake must both have the 4.5 Hz geophone distributed by RS, and be forwarding data to the Shake server, in order to deconvolve successfully. For the time being, the Raspberry Boom will display in counts of Voltage, i.e., not a deconvolved unit.

If the alert (STA/LTA earthquake detection trigger) module is enabled, setting "eq_screenshots" to true will result in screenshots being saved whenever there is an ALARM is internally forwarded for further processing (see Alert section below). The script will save one PNG figure per alert to the screenshots directory inside of "output_dir" when the leading edge of the quake is about 70% of the way across the plot window. This will only occur when the alarm gets triggered, however, so make sure to test your alert settings thoroughly.

Back to top ↑

3.3. alert (STA/LTA earthquake detection trigger)

Warning

Standard performance disclaimer

It is extremely important that you do not rely on this code to save life or property. It is not a substitute for earthquake early warning (EEW), or state or local official communication and alert systems.

Although this software can detect earthquakes and sudden motion events, Raspberry Shake makes no guarantee and provides no warranty in any way, implied or explicit, for the performance of this software in earthquake detection.

Raspberry Shake assumes no liability for false positives, false negatives, errors running the Alert module, or any other part of this software; it is meant for hobby and non-professional notification use only.

If you need professional-grade software to provide a warning intended to save life or property, please contact Raspberry Shake directly or look elsewhere. See sections 16 and 16b of the license for further details.

"alert" controls the rsudp.c_alert.Alert module (please see Warning above). The alert module is a fast recursive STA/LTA sudden motion detector that utilizes obspy’s obspy.signal.trigger.recursive_sta_lta() function (more detailed information on how to use that function here). STA/LTA algorithms calculate a ratio of the short term average of station noise to the long term average. The data can be highpass, lowpass, or bandpass filtered by changing the "highpass" and "lowpass" parameters from their defaults (0 and 50 respectively). By default, the alert will be calculated on raw count data from the vertical geophone channel (either "SHZ" or "EHZ"). It will throw an error if there is no Z channel available (i.e. if you have a Raspberry Boom with no geophone). If you have a Boom and still would like to run this module, change the default channel "HZ" to "HDF".

Like in the plot module, the alert module deconvolves the instrument response if a response file exists for your "station" on the Raspberry Shake FDSN server. Same as above, if the response file exists, setting "deconvolve" to true will cause the alert function to calculate the STA/LTA ratio on deconvolved data (again "ACC", "VEL", or "DISP").

If the STA/LTA ratio goes above a certain value (defined by "threshold"), then the rsudp.p_producer.Producer thread will generate an ALARM “event packet”, to be distributed to every consumer module. This tells all consumers listening for ALARM messages to do something.

When the ratio goes back below the "reset" value, the alarm is reset. The Producer will then send a RESET message to the queues.

For more information on the packets generated by the Producer, see Producer-consumer message passing.

3.3.1. Recommendations

The detection and filtering settings that we’ve found work well are below for different scenarios.

3.3.1.1. General use

For a station with sudden motion (footsteps nearby occasionally), or one atop unconsolidated sediment:

"alert": {
    "enabled": true,
    "channel": "HZ",
    "sta": 6,
    "lta": 30,
    "threshold": 4.5,
    "reset": 0.5,
    "highpass": 0.8,
    "lowpass": 9,
    "deconvolve": false,
    "units": "VEL"},

3.3.1.2. Quiet vault

For a very quiet station placed atop bedrock:

"alert": {
    "enabled": true,
    "channel": "HZ",
    "sta": 6,
    "lta": 30,
    "threshold": 1,
    "reset": 0.2,
    "highpass": 0.8,
    "lowpass": 9,
    "deconvolve": false,
    "units": "VEL"},

3.3.1.3. Classroom demonstrations

For a classroom looking to detect jumps but not necessarily earthquakes, start with the settings below. The main difference here is that there is no bandpass filter applied to the signal before it is put into the STA/LTA algorithm, which changes the calculation needed for exceedence of the threshold. Adjust the "threshold" downward, closer to 1.7 if 1.8 is too high.

"alert": {
    "enabled": true,
    "channel": "HZ",
    "sta": 6,
    "lta": 30,
    "threshold": 1.8,
    "reset": 1.6,
    "highpass": 0,
    "lowpass": 50,
    "deconvolve": false,
    "units": "VEL"},

3.3.2. Using "exec"

Deprecated since version 0.4.3: You can change the "exec" field and supply a path to executable Python code to run with the exec() function. exec() functionality will move to its own module in version 0.4.3 (see custom (run custom code) and the rsudp.c_custom.Custom class), and this part of the alert module will be fully removed in a future release.

Back to top ↑

3.4. RSAM (Real-time Seismic AMplitude)

New in version 1.0.1.

This module calculates the Real-time Seismic Amplitude Measurement (RSAM) of the data stream every few seconds and can forward this data to another location on the network.

"interval" is a float that specifies the number of seconds to wait between each RSAM analysis.

"quiet" controls the amount of data printed to the console in debug mode. When "quiet" is true, the module will not print any RSAM analysis, If debug mode is on and "quiet" is false, then the module will print the analysis to the console every "interval" seconds.

"fwaddr" and "fwport" specify the forwarding address and port to which to optionally send RSAM data. If one of these fields is false then no data will be forwarded. If these fields are populated with valid IP and port, data will be forwarded every "interval" seconds.

"fwformat" specifies the format of data to be forwarded. There are three formats, "LITE", "JSON", and "CSV", which can be used depending on the endpoint processing method and size constraints.

"channel" specifies the channel to use for RSAM analysis (only one can be chosen).

"deconvolve" specifies whether the instrument response should be removed from the data stream prior to RSAM calculations.

To run the RSAM module, set "enabled" to true.

3.5. alarmsound (play sounds upon alerts)

If alarmsound’s "enabled" is true and you have either ffmpeg or libav installed, rsudp.c_alertsound.AlertSound plays an MP3 sound every time it receives an ALARM queue message. For details on installation of these dependencies, see this page.

The rsudp software will install several small MP3 files. The "mp3file" is "doorbell" (two doorbell chimes) by default, but there are a few more aggressive alert sounds, including: a three-beep sound "beeps", a sequence of sonar pings "sonar", and a continuous alarm beeping for 5 seconds, "alarm". You can also point the "mp3file" field to an MP3 file somewhere in your filesystem. For example, if your username was pi and you had a file called earthquake.mp3 in your Downloads folder, you would specify "mp3file": "/home/pi/Downloads/earthquake.mp3". The program will throw an error if it can’t find (or load) the specified MP3 file. It will also alert you if the software dependencies for playback are not installed.

To test the sound output, ensure you have the correct dependencies installed (see below), change "enabled" to true, start rsudp, wait for the trigger to warm up, then stomp, jump, or Shake to trigger the sound.

3.5.1. Installing pydub dependencies

If you would like to play sounds when the STA/LTA trigger activates, you will need to take the following installation steps beforehand:

3.5.1.1. On Linux

ffmpeg comes installed by default on some OS flavors and is available on most Linux package managers.

Debian and Raspbian users can simply type sudo apt update; sudo apt install ffmpeg

3.5.1.2. On MacOS

Users with Homebrew can install by doing brew install ffmpeg

Users without Homebrew will need to install using a binary build from the ffmpeg website.

3.5.1.3. On Windows

Windows users will need to do a couple of extra steps to get ffmpeg installed. Following steps 1-8 in this installation guide should be sufficient to get things working.

Back to top ↑

3.6. telegram (Telegram notification module)

Telegram is a free and open source messaging and notification system, used by several earthquake notification agencies including the Mexican national early warning system (SASMEX, Telegram channel here). It has the bonus of being much, much easier to set up than Twitter, and will not as readily lock your account if there happen to be many posts in a short time period (in comparison to Twitter).

If "enabled" is true, and bot "token" key is correctly entered, rsudp.c_telegram.Telegrammer will use the Telegram bot API to create alerts when an ALARM message arrives on the queue. If "send_images" is true, then the module will also send a saved image of the event, if "eq_screenshots" is set to true in the "plot" module.

If any text is put in the "extra_text" string, then the software will insert that text (no longer than 3900 characters) into the message after the UTC designation and prior to the stationview hyperlink. This works similarly to the "extra_text" field in the Twitter module below. (See Examples.)

Warning

Starting the software with an "extra_text" string in excess of 3900 characters will yield a warning and the "extra_text" string will be truncated in order to avoid the message being rejected for exceeding the 4096 character limit.

3.6.1. Setting up a Telegram Bot

Here is a brief overview of the steps to set up a Telegram bot in order to make and distribute Telegram alerts from rsudp.

1. Download Telegram, create a profile, and sign in.

2. Create a Telegram bot by sending the /start message to the @BotFather account.

3. Follow the instructions. Your messages to @BotFather should look something like the following:

   1. /start

   2. /newbot

   3. Your Shake Bot Name

   4. your_shake_bot_id

   5. @BotFather will then give you an access token for your new bot.

4. Enter your bot’s access token in the "token" field of the settings file.

5. Enter a user or group ID into the "chat_id" field (or multiple separated by commas),

   which you can find by following the instructions in this stackoverflow answer.

If you wish to broadcast telegrams to a group or a channel, first add the bot to the group using your user account, then follow the instructions in the previous link, where you will see the group chat ID appear as a field in the last JSON entry. This chat ID may be negative, in which case you must enter the negative sign into "chat_id" as well.

Back to top ↑

3.7. tweets (Twitter notification module)

If "enabled" is true, and all API keys have been generated and are correctly entered, then the rsudp.c_tweet.Tweeter class will use the Twitter API to create tweets when an ALARM message arrives on the queue. If "tweet_images" is true, then the module will also tweet a saved image of the event, if "eq_screenshots" is set to true in the “plot” module. If any text is put in the "extra_text" string, then the software will insert that text (no longer than 103 characters) into the tweets after a single space. See examples below.

3.7.1. Examples

As a comparison point, an unmodified tweet with "extra_text": "" might look like the following:

An example tweet sent with the “extra_text” parameter empty (this is the default).

Changing the "extra_text" parameter to "extra_text": "from #Williamstown #MA" would render something like this:

An example tweet sent with the “extra_text” parameter filled.

Warning

Starting the software with an "extra_text" string in excess of 103 characters will yield a warning and the "extra_text" string will be truncated in order to avoid the tweet being rejected for exceeding the 280 character limit.

3.7.2. Setting up Twitter Apps

Here is a brief overview of the steps to set up a Twitter app (also known as an API bot) in order to make and distribute tweets from rsudp.

1. Create a twitter profile (or use an existing account).

2. Register this account as a Twitter developer account.

3. Create a Twitter API app inside said developer account.

4. Generate consumer keys and API keys for that app.

Once you have generated the four API keys required for authentication (consumer API key, consumer API secret, access token, and access token secret), you may enter them into your settings file in the appropriate fields: "api_key", "api_secret", "access_token", and "access_secret".

Back to top ↑

3.8. write (miniSEED writer)

"write" controls rsudp.c_write.Write, a very simple STEIM2 miniSEED writer class. If "enabled" is true, seismic data is appended to a miniSEED file with a descriptive name in the data directory inside of "output_dir" every 10 seconds. By default, "all" channels will be written to their own files. You can change which channels are written by changing this to, for example, ["EHZ", "ENZ"], which will write the vertical geophone and accelerometer channels from RS4D output.

Back to top ↑

3.9. forward (datacast forwarding)

The "forward" module controls rsudp.c_forward.Forward, a UDP datacast forwarding module. You can forward UDP packets containing data and/or alarm state messages to a list of destinations specified in "address" and "port", just like you would from the Shake’s web front end.

By default, ["all"] channels are forwarded. To forward only data from EHZ and ENZ channels, set this field to a list, e.g. ["EHZ", "ENZ"].

To change the types of messages that are forwarded, change the boolean fields "fwd_data" and "fwd_alarms" accordingly. Setting "fwd_data": true will forward data from the specified channels, while "fwd_alarms": true will forward ALARM and RESET messages. These can both be set to true simultaneously.

To take advantage of this forwarding capability in another piece of software (such as NodeRED), it may help to consult the Message types.

Forwarding to multiple destinations (such as in a classroom setting) is easy. Say you want to send alarm messages to several Raspberry Pis running NodeRED in a classroom. Simply create equal-length lists of addresses and ports in the forward settings like so:

"forward": {
    "enabled": false,
    "address": ["192.168.1.250","192.168.1.251","192.168.1.252","192.168.1.253"],
    "port": [8888,8888,8888,8888],
    "channels": ["all"],
    "fwd_data": false,
    "fwd_alarms": true},

This will create one Forward thread per destination and distribute ALARM and RESET messages to each simultaneously. Each Pi node can then be configured to listen to its own port 8888 (127.0.0.1:8888) to read these messages.

Back to top ↑

3.10. custom (run custom code)

New in version 0.4.3.

Warning

Do not use this module unless you understand the implications of running unchecked code.

"custom" controls the execution of a custom python code file specified by the "codefile" field. If "enabled" is true and a python file is found at the path specified, this thread will run the specified file using python’s exec() function.

Be very careful when using this module, as the exec() function is known to have problems. Notably, exec() does not check the passed file for errors prior to running. Also, the passed file cannot have Windows line endings (see warning below). Additionally, if the code takes too long to execute, you could end up losing data packets from the queue, so keep it simple. Sending a message or a tweet, which should either succeed or time out in a few seconds, is really the intended purpose, and this can typically be achieved by setting up a different module anyway (see Twitter and Telegram modules).

In testing, we were able to run scripts with execution times of 30 seconds without losing any data packets. Theoretically you could run code that takes longer to process than that, but the issue is that the longer it takes the function to process code, the longer the module will go without processing data from the queue (the queue can hold up to 2048 packets, which for a RS4D works out to ~128 seconds of data). Another way of saying this is: you could miss whatever subsequent earthquakes occur while exec() is running. A better way to run your own code would be to fork this repository and create a new thread that does the thing you want when it sees an ALARM data packet on the queue. That way, the code will be checked for errors prior to running.

Warning

If you are running Windows and have code you want to pass to the exec() function, Python requires that your newline characters are in the UNIX style (n), not the standard Windows style (rn). To convert, follow the instructions in one of the answers to this stackoverflow question. If you’re not sure what this means, please read about newline/line ending characters here. If you are certain that your code file has no Windows newlines, you can set "win_override" to true.

Code will not execute on Windows unless this field is set to true.

Back to top ↑

3.11. printdata (print data to console)

"printdata" controls the data output module rsudp.c_printraw.PrintRaw, which simply prints Shake data packets to stdout as it receives them. Change "enabled" to true to activate.

Back to top ↑

You are now ready to proceed to the next section, Running rsudp.

3.12. Default settings

By default, the settings are as follows:

{
"settings": {
    "port": 8888,
    "station": "Z0000",
    "output_dir": "@@DIR@@",
    "debug": true},
"printdata": {
    "enabled": false},
"write": {
    "enabled": false,
    "channels": ["all"]},
"plot": {
    "enabled": true,
    "duration": 90,
    "spectrogram": true,
    "fullscreen": false,
    "kiosk": false,
    "eq_screenshots": false,
    "channels": ["all"],
    "deconvolve": true,
    "units": "CHAN"},
"forward": {
    "enabled": false,
    "address": ["192.168.1.254"],
    "port": [8888],
    "channels": ["all"],
    "fwd_data": true,
    "fwd_alarms": false},
"alert": {
    "enabled": true,
    "channel": "HZ",
    "sta": 6,
    "lta": 30,
    "threshold": 3.95,
    "reset": 0.9,
    "highpass": 0.8,
    "lowpass": 9,
    "deconvolve": false,
    "units": "VEL"},
"alertsound": {
    "enabled": false,
    "mp3file": "doorbell"},
"custom": {
    "enabled": false,
    "codefile": "n/a",
    "win_override": false},
"tweets": {
    "enabled": false,
    "tweet_images": true,
    "api_key": "n/a",
    "api_secret": "n/a",
    "access_token": "n/a",
    "access_secret": "n/a",
    "extra_text": ""},
"telegram": {
    "enabled": false,
    "send_images": true,
    "token": "n/a",
    "chat_id": "n/a",
    "extra_text": ""},
"rsam": {
    "enabled": false,
    "quiet": true,
    "fwaddr": "192.168.1.254",
    "fwport": 8887,
    "fwformat": "LITE",
    "channel": "HZ",
    "interval": 10,
    "deconvolve": false,
    "units": "VEL"}
}

---

• Index

• Search Page

Back to top ↑