This is a simple Docker configuration to startup a new OpenEEW detection system on your local machine. It ingests data from OpenEEW sensors via an MQTT broker, and triggers for individual sensors using a detection method. These events are then sent to a multi-station logic script that checks time and distance proximity for sensors before declaring an earthquake. You can also deploy the Docker container on Kubernetes to target a publicly accessible endpoint.
The OpenEEW strategy for accurately detecting earthquakes while avoiding false positives is to use a variety of tactics, including:
- Filtering out non-earthquake vibrations by using STA/LTA (Short-Term Average/Long-Term Average)
- Detecting peak accelerations (PGAs) above a certain threshold from the sensors
- Aggregating readings from multiple nearby sensors
First install Docker
Jump to Run Detector Docker section, if you already have a local copy of the openeew-detection code. Else, get a copy first before running the docker shell-script. After changing to a folder of your choice, to retrieve the code
- Option 1 : download the code using the browser Code --> Download ZIP or run the
wget https://github.com/openeew/openeew-detection/archive/master.zip; to then extract the zipped files. - Option 2 : clone the code using the git command; especially if you intend to make changes to this repo
git clone https://github.com/openeew/openeew-detection.git
run a detector container with the following command.
docker run \
--interactive \
--tty \
--detach \
--env username=admin \
--env password=admin \
--publish 1883:1883 \
--name openeew-detector \
openeew/detectorYou can change the port published to host and the credentials. In the following example the detector listens on port
8080 and the username and password created for authentication are foo and bar.
docker run \
--interactive \
--tty \
--detach \
--env username=foo \
--env password=bar \
--publish 8080:1883 \
--name openeew-detector \
openeew/detectorYou can also omit the username and password parameters but that would be a less secure option and would allow
anyone to publish data to your detector. This setup is primary meant for development.
The Docker image contains a PostgreSQL database which is used to store devices and events. You can find its structure here.
For developers only. Apply the changes to the Dockerfile and run the following command.
docker build --tag openeew/detector:dev .Then run a development container:
docker run \
--interactive \
--tty \
--detach \
--publish 1883:1883 \
--name openeew-detector-dev \
openeew/detector:devStart a container as indicated above and then run the following on the host machine:
cd openeew
python3 sensor_simulator.py --username admin --password admin --earthquake 2018_7.2 --port 1883Note: You may need to install the Paho MQTT client. For example, pip install paho-mqtt
The data comprises records of acceleration in three channels representing sensor movement in the space. The channels are orthogonal (90 degrees from each other), two components are horizontal, x and y, and one vertical, z. The units are gals, centimeter per second squared. This is true of both the simulated sensor data, and actual sensor data. The script will send data at the rate of one message from each sensor per second.
PYTHONPATH=./openeew:./test python -m unittestsensor_simulator.py selects historic data from /input and publishes them to MQTT at an accurate rate (1 msg per sensor per second).
A Mosquitto MQTT broker administers the following topics:
/traces(raw accelerations from sensor, time, deviceid)/device(device metadata; deviceid, lat, lon, firmware version)/pga-trigger(threshold triggered for sensor; deviceid, pga intensity, time)/earthquake(earthquake declared by comparing recent pga-triggers from various devices; eventid, time of event, pga intensity)
DBwriter.py updates the devices table in the database with meta data for each sensor, including its location coordinates. This script also writes earthquake events to the database as they happen.
The detection.py script runs a Short-Term Average/Long-Term Average STA/LTA algorithm followed by a Peak Ground Acceleration (PGA) calculation.
This method is widely used to identify any disturbances in the signal (such as earthquakes) and determine the time when an event starts.
The algorithm takes each channel independently (x, y and z) and applies the moving average using two windows and returns the ratio as a function. Based on the part of the signal where there is no earthquake, a trigger level can be defined.
The maximum acceleration, or Peak Ground Acceleration (PGA) (x**2 + y**2 + z**2)**0.5) is used to determine the level of shaking that needs to be updated after a triggering using the three components at the same time.
The output from this process is sent as a value (PGA) using the topic /pga-trigger.
The multistation.py script subscribes to /pga-trigger to determine if an earthquake is occuring. This is done by evaluating distance and time between each pga-trigger msg. To get latitude and longitude, the script must read from the devices table in the database.
The outcome of this script is a confirmed earthquake event. This is sent by msg to the /earthquake topic.
The openeew-nodered README contains an example of how to implement the PGA algorithm in JavaScript.
Enjoy! Give us feedback if you have suggestions on how to improve this information. Here are some guidelines for contributing algorithms.
This information is licensed under the Apache Software License, Version 2. Separate third party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 (DCO) and the Apache Software License, Version 2.