A desktop GUI for fetching seismic waveforms from a Raspberry Shake device and running Horizontal-to-Vertical Spectral Ratio (HVSR) analysis — all without writing a single line of code.
Built with Python and Tkinter, ShakeFetch wraps ObsPy for data retrieval and hvsrpy for MHVSR processing, and adds SSH-based device management on top.
- Shake Connection — Connect to your Raspberry Shake over SSH and synchronise its clock to UTC in one click.
- Single Fetch — Pull a waveform for any NSLC channel and time window, preview the stream, and save it as MiniSEED.
- Multifetch — Batch-fetch waveforms for multiple measurement stations in one pass; files are automatically named and organised into a project folder.
- MHVSR Analysis — Run a full Microtremor HVSR workflow on MiniSEED files with configurable pre-processing and processing parameters, SESAME (2004) reliability/clarity checks, curve plotting, and CSV export.
- Profile Management — Save and reload device connection settings as named profiles; SSH passwords are stored securely in the system keyring.
- Non-blocking UI — All network and compute tasks run in background threads so the interface stays responsive.
- Logging — Every action and error is written to
logs/shakefetch.log.
| Dependency | Purpose |
|---|---|
| Python 3.9+ | Runtime |
| ObsPy | Waveform retrieval via Earthworm/SeedLink |
| hvsrpy | MHVSR processing and SESAME criteria |
| Paramiko | SSH connection to the Raspberry Shake |
| keyring | Secure credential storage |
| ttkthemes | "Arc" themed Tkinter GUI |
| NumPy | Numerical utilities |
| Matplotlib | Waveform and HVSR curve plotting |
If you just want to use the application without installing Python or dealing with dependencies:
- Download the latest
ShakeFetchSetup_v1.0.0.exeinstaller from Releases. - Run the installer to install ShakeFetch with desktop and start menu shortcuts.
To build the executable or installer yourself from source, see BUILD.md.
# 1. Clone the repository
git clone https://github.com/proboiii/shakefetch.git
cd shakefetch
# 2. (Recommended) Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 3. Install dependencies
pip install obspy hvsrpy paramiko keyring ttkthemes numpy matplotlibConda users: ObsPy is easiest to install via conda:
conda install -c conda-forge obspy pip install hvsrpy paramiko keyring ttkthemes
python shakefetch/shakefetch.pyThe application opens an 850 × 750 window with four tabs.
Use this tab before fetching data to verify connectivity and correct the device clock.
- Select or create a Profile — type a name in New Profile Name and fill in the fields below, or pick an existing profile from the dropdown. Check Remember SSH Credentials to store the password in the system keyring.
- Fill in Host (default:
rs.local), Username (default:myshake), and Password. - Click Connect. The status indicator turns green on success.
- Click Sync Time to set the Raspberry Shake's system clock to the current UTC time via SSH (
sudo date --set). - Click Disconnect when done.
Profiles are persisted to
profiles.jsonin the working directory. Passwords are never written to that file — they go to the system keyring only.
Fetch a single waveform segment and save it as a MiniSEED file.
| Field | Default | Description |
|---|---|---|
| Host | rs.local |
Raspberry Shake hostname or IP |
| Port | 16032 |
Earthworm/WaveServer port |
| Network | AM |
FDSN network code |
| Station | R1E3F |
Station code |
| Location | 00 |
Location code |
| Channel | EH* |
Channel code (wildcards supported) |
| Start Time (UTC) | now | Use the ... button to open the date-time picker |
| End Time (UTC) | now + 1 min |
- Fill in the parameters (or load a profile).
- Click Get Waveforms. A save dialog appears on success — choose a
.mseedoutput path. - Click Plot Waveforms to open an ObsPy waveform plot for the last fetched stream.
Batch-fetch waveforms for multiple measurement points in a single survey.
- Enter a Project Name and choose a Project Directory with Browse…
- Set the Number of Stations and click Generate Station Inputs. A scrollable row appears for each station.
- Set the Start Time and End Time for each station (the ... picker works here too).
- Fill in the shared Shake Connection Details (Host, Port, NSLC codes).
- Click Fetch All Waveforms.
ShakeFetch will create <Project Directory>/<Project Name>/ and save each file as:
<ProjectName>_<StationNumber>_<StartTime>_to_<EndTime>.mseed
Failed stations are logged and skipped; the batch continues.
Run a Microtremor HVSR analysis on one or more MiniSEED files using hvsrpy.
Click Select Files to choose one or more .mseed / .miniseed files (e.g., files from Multifetch).
| Parameter | Default | Description |
|---|---|---|
| Window Length (s) | 150 | Length of each analysis window |
| K&O Bandwidth | 40 | Konno–Ohmachi smoothing bandwidth |
| Filter Low Cut (Hz) | None | High-pass corner frequency; leave as None to skip |
| Filter High Cut (Hz) | None | Low-pass corner frequency; leave as None to skip |
| Taper Type | tukey | Window taper: tukey, hann, hamming, bartlett, blackman |
| Taper Width (alpha) | 0.2 | Taper fraction (0–1) |
| Combine Horizontals | geometric_mean | Method to combine H components: geometric_mean, squared_average, azimuth, single_azimuth |
- Select files and set parameters.
- Click Run MHVSR Analysis. The output pane shows:
- SESAME (2004) Reliability criteria results
- SESAME (2004) Clarity criteria results
- Statistical Summary (mean frequency, amplitude, standard deviation)
- Click Plot Results to display the HVSR curves in a Matplotlib window.
- Click Save Results to export the HVSR object to a
.csvfile.
shakefetch/
├── shakefetch.py # Main GUI application (ShakeFetchApp class)
├── data_acquisition.py # ObsPy Earthworm waveform fetching
├── mhvsr_logic.py # hvsrpy pre-processing and HVSR processing
├── time_sync.py # SSH connection and UTC time synchronisation
├── profiles.json # Saved device profiles (auto-generated)
└── logs/
└── shakefetch.log # Application log (auto-generated)
Default Earthworm port: The Raspberry Shake streams data on port 16032. This can be changed per profile.
Frequency axis (MHVSR): The default spectral estimate uses 200 log-spaced frequencies between 0.2 Hz and 50 Hz (numpy.geomspace). This is set in mhvsr_logic.py and can be adjusted for your survey's frequency range of interest.
Log level: Currently set to INFO. Change level=logging.INFO in setup_logging() inside shakefetch.py to logging.DEBUG for verbose output during development.
This project is licensed under the GNU General Public License v3.0. See LICENSE for details.