QuakeGuard PCB

📖 Overview

QuakeGuard is a full-stack IoT architecture for real-time detection, analysis, and reporting of seismic events. The system transforms everyday household appliances — washing machines, TVs, refrigerators — into a distributed seismic sensor network, each node capable of detecting and reporting earthquake activity autonomously.

Intelligent edge sensors (ESP32-C3 + ADXL345) analyze vibrations locally using professional-grade algorithms and transmit cryptographically signed data to an asynchronous cloud backend. The backend is engineesred to handle the massive traffic spikes — the Thundering Herd effect — typical during widespread seismic events, ensuring reliable alarm delivery without bottlenecking. A React Native mobile app receives real-time haptic and visual alerts via WebSocket.

QuakeGuard Proprietary Hardware

The QuakeGuard v2.0 fully assembled PCB, featuring the ESP32-C3 SuperMini, the ADXL345 accelerometer, and the u-blox GNSS module. For a complete list of required components, refer to the Bill of Materials (BOM) in the Wiki.

🏗️ System Architecture

ESP32-C3 + ADXL345
       │
       │  MQTT (signed payload)
       ▼
MQTT Bridge ──► POST /readings/ ──► ECDSA Verification
                                              │
                                              ▼
                                        Redis Queue
                                              │
                                              ▼
                                     Background Worker ────►┌───────────┐
                                      │           │ (Queue)  │ AI Worker │
                                      ▼           ▼          │ (Ollama)  │
                               PostgreSQL    Redis Pub/Sub ◄─└─────┬─────┘
                               + PostGIS               │
                                                   ▼
                                            WebSocket Broadcast
                                                  │
                                                  ▼
                                        React Native Mobile App
                                        (Haptic + Visual Alert)

The project follows Microservices and Event-Driven Design principles across three fully independent layers.

📡 IoT Edge (firmware/)

☁️ Backend (backend/)

📱 Frontend (mobile/)

🔐 Security Model

Data integrity is paramount in an emergency system. Every telemetry packet is cryptographically secured end-to-end.

ESP32 signs payload with ECDSA NIST256p (SHA256)
         ↓
Backend verifies signature against registered public key
         ↓
Timestamp validated within 300-second window (Anti-Replay)
         ↓
API Key checked on every request (X-API-Key header)
         ↓
Payload accepted → Redis Queue

Threat model coverage:

• ✅ Man-in-the-Middle (MitM) — ECDSA signature verification
• ✅ Spoofing — public key registration + signature check
• ✅ Replay attacks — 300-second timestamp window
• ✅ Brute force — rate limiting 50 req/s per IP
• ✅ Unauthorized access — API Key + enrollment token fail-fast

🚀 Quick Start

Prerequisites

• Docker Desktop & Docker Compose
• PlatformIO (VS Code Extension)
• Node.js 18+ & Expo Go (mobile)
• A mobile hotspot or shared WiFi network for ESP32 + backend connectivity

1. Configure Environment Variables

cd backend
cp .env.example .env

Edit .env and set the required secrets:

# --- Application Secrets ---
IOT_API_KEY=your_secret_key
MOBILE_WS_TOKEN=your_ws_token
ENROLLMENT_TOKEN=your_enrollment_token

# --- Database ---
POSTGRES_DB=quakeguard_db
POSTGRES_USER=developer
POSTGRES_PASSWORD=your_db_password
API_PORT=8000

# --- Local MQTT (Mosquitto) ---
MQTT_BROKER=localhost
MQTT_PORT=1883

# --- AI Emergency Reports (hybrid Edge AI architecture) ---
AI_REPORT_ENABLED=true
OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2:1b

⚠️ The backend will refuse to start if any of these are missing — this is intentional fail-fast behavior.

💡 Edge AI Architecture (v2.0.0): To maximize hardware efficiency and avoid Docker's GPU passthrough overhead, QuakeGuard employs an industrial Hybrid Edge AI pattern (similar to NVIDIA Jetson or Tesla FSD architectures). The core AI inference engine (Ollama) runs bare-metal on the host Linux OS, while the application microservices run in Docker and communicate via network_mode: "host".

To enable on-premise AI reports:

1. Install Ollama natively on your Linux host: curl -fsSL https://ollama.com/install.sh | sh
2. Pull the model natively: ollama pull llama3.2:1b
3. Start the Docker stack with the AI worker profile: docker compose --profile ai up --build -d

Reports are generated entirely on your machine: telemetry never leaves the host.

2. Launch the Backend Stack

cd backend
docker compose up --build -d

3. Configure and Flash the IoT Firmware

cd firmware
cp esp32_config.env.example esp32_config.env
# Edit esp32_config.env with your network IP and ENROLLMENT_TOKEN

Flash via PlatformIO. On first boot the device will:

1. Open a WiFi captive portal (QuakeGuard-Setup) — serves the mobile APK download link and displays the ECDSA Public Key for enrollment
2. Connect to your network
3. Automatically register with the backend and receive a sensor_id

💡 If the sensor registers with latitude=0.0, longitude=0.0 it will be assigned to "Unknown Region". Hardcode your coordinates in main.cpp for correct zone assignment until GPS integration is complete.

4. Launch the Mobile App

cd mobile
npm install

Update constants/config.ts with your machine's local IP:

export const API_BASE_URL = "http://YOUR_LOCAL_IP:8000";

Create .env in the mobile root:

EXPO_PUBLIC_IOT_API_KEY=your_secret_key
EXPO_PUBLIC_MOBILE_WS_TOKEN=your_ws_token

npx expo start

Scan the QR code with Expo Go. Ensure your phone is on the same WiFi network as the backend machine.

🧪 Stress Test

Validates the full pipeline: ingestion → Redis → worker → PostGIS → WebSocket alerts.

cd backend
export API_URL="http://localhost:8000"
export NUM_SENSORS=150
export CONCURRENCY_LIMIT=50
python -m tests.stress_test

Three phases:

A successful run ends with 🏆 SYSTEM CERTIFIED.

🎮 Demo Mode

Trigger a simulated earthquake instantly from Swagger UI without running the stress test:

POST /demo/trigger-earthquake

Default payload (works with empty {}):

{
  "zone_id": 1,
  "magnitude": 7.5,
  "message": "Simulated Critical Event"
}

This publishes directly to the Redis quake_alerts channel, bypassing the IoT pipeline entirely and triggering the mobile app alert UI within milliseconds.

🗺️ Geographic Zones

The database is pre-seeded with 8 global macro-regions. Sensors are automatically assigned to the correct zone via PostGIS spatial query at registration time.

🔄 CI/CD Pipeline

🗂️ Project Structure

QuakeGuard/
├── backend/
│   ├── src/
│   │   ├── main.py              # FastAPI gateway + REST endpoints
│   │   ├── security.py          # ECDSA, API Key, Anti-Replay
│   │   ├── worker.py            # Redis consumer + magnitude + alert engine + AI enqueue
│   │   ├── ai_report_worker.py  # Dedicated AI report consumer (Ollama + state machine)
│   │   ├── ollama_client.py     # Deterministic LLM client (anti-hallucination)
│   │   ├── mqtt_subscriber.py   # MQTT to HTTP bridge
│   │   ├── seed.py              # Geographic zone seeder
│   │   ├── models.py            # SQLAlchemy ORM models (+ EmergencyReport)
│   │   ├── schemas.py           # Pydantic request/response schemas
│   │   └── database.py          # DB engine and session factory
│   ├── tests/
│   │   ├── stress_test.py       # Critical E2E stress test suite
│   │   └── unit/                # Unit tests (worker, ollama client, AI worker, models, ...)
│   ├── init-scripts/
│   │   └── ollama-entrypoint.sh # Auto-pulls the Ollama model on startup
│   ├── build.ps1                # Automatic container publish
│   ├── docker-compose.yml
│   ├── Dockerfile
│   ├── mosquitto.conf
│   ├── grafana/                # Grafana provisioning (datasource + dashboard JSON)
│   ├── requirements.txt         # Python requirements for backend development

🔮 Roadmap

#Research — Scientific Validation (SIL)

🏆 Awards & Recognition

QuakeGuard's architecture and real-world applicability have been recognized in the following academic and industrial contexts:

• 🥇 1st Place Overall - Institute Project Day (2025): Awarded best technical project out of ~20 prototypes across four engineering disciplines (Computer Science, Automation, Mechanics, Chemistry) at I.S. Archimede. The full-stack architecture was evaluated and awarded by an industrial jury featuring technical representatives from Siemens, ABB, SORINT.lab, SAME, Ferrero, and Confindustria.
• 🎓 Academic Origin & Consultation: The system's conceptualization originated during the 2025 CQIIA-MatNet Summer School (Università di Bergamo). The distributed network logic and spatial deployment strategy were subsequently refined following technical consultations with Prof. F. Finazzi.
• 🥇 1st Place - GF Marilli Competition (2026 - 5th Year Category): Awarded 1st place in the 5th-year category of the Gianfranco Marilli competition at the HackersGen Event, recognizing QuakeGuard for innovation in distributed edge IoT architectures, real-time seismic sensing, and full-stack engineering.

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

Hardware designs (hardware/) are licensed under the CERN Open Hardware Licence v2 — Strongly Reciprocal (CERN-OHL-S-2.0). See hardware/LICENSE for details.

⚠️ Hardware Compliance: The QuakeGuard PCB is not certified for CE/FCC/RoHS. It is intended for prototyping, educational, and research use only. Do not deploy as a commercial safety-critical device without appropriate regulatory certification.