🌋 Real-time Earthquake Early Warning System

This project implements a real-time earthquake early warning system based on streaming data from a seismic sensor (seismometer). The system continuously receives and filters acceleration measurements, detects significant seismic activity, and sends notifications via Telegram when thresholds are exceeded.

⚠️ Disclaimer:
This is a local research project and is not intended for production use.
It is designed for experimental purposes only and should not be relied upon for life-safety or mission-critical applications.

---

🔬 Scientific Foundations

Seismic activity can be detected and quantified through analysis of ground acceleration in three orthogonal directions: X, Y, and Z. Earthquake waves propagate through the Earth and produce patterns of vibrations that are distinguishable from background noise.

To improve accuracy and reduce false positives, this system applies a Kalman filter, a statistical estimator widely used in control systems and robotics. It assumes a constant-acceleration model and recursively corrects sensor noise over time.

Key steps:

• Signal smoothing: via Kalman filter to suppress noise
• Vector magnitude computation: to estimate resultant acceleration
• Amplitude-based classification: empirical thresholds are used to distinguish between noise, distant tremors, and local seismic events

---

🧠 System Logic

1. TCP connection to seismic sensor

   • Data format: timestamp,x,y,z
   • Raw acceleration values are scaled to m/s²

2. Line-by-line parsing

   • Input is validated and cleaned
   • Timestamps are converted to local time (Europe/Podgorica)
   • Only current-year data is accepted

3. Kalman filtering

   • Applies a constant-acceleration filter
   • Reduces noise in acceleration readings

4. Buffering and activity analysis

   • Data is buffered in fixed-size windows (e.g. 50 readings)
   • Root-mean-square (RMS) amplitude is computed
   • Activity levels are classified:

Amplitude (m/s²)	Level	Description
< 0.01	0	Noise
< 0.02	1	Distant earthquake
< 0.05	2	Local vibration
< 0.1	3	Local EQ (~1–2 on Richter scale)
< 0.2	5	Local EQ (~3 on Richter scale)
≥ 0.2	8	Strong local EQ (>3 Richter scale)

5. Notifications
   • Significant activity (level > 2) triggers a Telegram message
   • Messages are formatted with timestamp, activity level, deviation

---

🧱 Components

Module	Role
TcpClient	Handles connection to the seismic data source (TCP socket), retries on failure
SeismicDataProcessor	Filters and transforms raw data, computes amplitude, classifies activity
KalmanFilterWrapper	Applies a Kalman filter to smooth acceleration data
TelegramNotifier	Sends formatted alerts via Telegram Bot API
index.ts	Initializes the system with environment config and starts processing loop

---

🚀 Quick Start

1. Clone the repo

git clone https://github.com/your/seismic-monitor.git
cd seismic-monitor

2. Setup environment

Create a .env file:

TCP_SERVER_HOST=mock.tcp.server
TCP_SERVER_PORT=21041
TELEGRAM_TOKEN=your-telegram-bot-token
TELEGRAM_CHAT_ID=your-chat-id
BUFFER_WINDOW_SIZE=50

3. Run with Docker

docker build -t seismic-monitor .
docker run --env-file .env seismic-monitor

Or use Bun directly:

bun install
bun run index.ts

---

🧪 Sample Input

1714824088414,20,15,4
1714824088496,22,14,5

📦 Project Structure

.
├── services/
│   ├── TcpClient.ts
│   ├── SeismicDataProcessor.ts
│   ├── KalmanFilterWrapper.ts
│   └── TelegramNotifier.ts
├── types.ts
├── index.ts
├── Dockerfile
├── .env.example
└── README.md

---

🛡️ Why Not Use Telegram SDKs?

The TelegramNotifier uses raw HTTP requests via axios rather than node-telegram-bot-api:

• ✅ Lighter: avoids pulling full bot framework
• ✅ Simpler: only requires sending messages, no webhooks or polling
• ✅ Transparent: raw payload structure is visible and controllable

---

📈 Future Improvements

• Add web dashboard for live seismic plots
• Machine learning–based activity classifier
• Historical data analysis and offline replay mode
• Exporting to Prometheus/Grafana

---

📚 References

• Kalman Filtering Theory
• Telegram Bot API
• Earthquake Glossary – Montana Bureau of Mines and Geology (MBMG)