UDPQuake Release Notes

🎉 v1.0.0 - Initial Release

Released: May 25, 2025

We're excited to announce the initial release of UDPQuake - a Raspberry Pi service that brings real-time earthquake monitoring to Meshtastic mesh networks! This first release provides a complete, production-ready solution for distributed seismic awareness in off-grid and emergency communication scenarios.

🌟 Core Features

🌍 Real-Time Earthquake Monitoring

USGS Integration: Direct connection to USGS earthquake data feeds for authoritative seismic information
Configurable Regions: Support for custom geographic boundaries (Southern California, Northern California, Pacific Northwest, and more)
Intelligent Polling: Smart polling system that checks the last 72 hours on startup, then monitors hourly for new events
Magnitude Filtering: Configurable minimum magnitude thresholds to focus on relevant seismic events

📡 Meshtastic Mesh Integration

UDP Multicast Broadcasting: Seamless integration with Meshtastic networks via UDP on 224.0.0.69:4403
Smart Alert Thresholds: Text messages sent only for significant earthquakes (magnitude > 3.5)
Position Data: Earthquake epicenter coordinates transmitted as position data with depth-based altitude
Rich Messaging: Formatted alerts including magnitude, location, time, and depth information

🔧 System Integration

Systemd Service: Complete systemd integration for automatic startup and robust service management
Resource Management: Built-in resource limits to prevent system exhaustion
Graceful Shutdown: Proper signal handling for clean service stops
Comprehensive Logging: Detailed logging via systemd journal for monitoring and debugging

⚙️ Configuration & Deployment

Environment-Based Config: Simple .env file configuration for all service parameters
UV Package Management: Modern Python dependency management with UV for fast, reliable installs
Raspberry Pi Optimized: Lightweight design specifically optimized for Raspberry Pi hardware
Development Tools: Complete development environment with testing, formatting, and type checking

📋 What's Included

Core Components

EarthquakeService: Robust USGS API client with comprehensive error handling
MUDP Integration: Meshtastic UDP protocol implementation for mesh broadcasting
Main Application: Service orchestration with intelligent polling and duplicate detection
Systemd Integration: Production-ready service configuration

Regional Presets

Southern California (default): 33.0°N to 35.0°N, -120.0°W to -116.0°W
Northern California: 36.0°N to 42.0°N, -124.0°W to -119.0°W
Pacific Northwest: 42.0°N to 49.0°N, -125.0°W to -116.0°W
Custom Regions: Easy configuration for any geographic area worldwide

Message Format

Earthquake alerts are broadcast in a clear, concise format:

🚨 EARTHQUAKE ALERT 🚨
2024-01-15 14:30:22 UTC
15km SW of San Francisco, CA
Mag: 4.2 Depth: 8.3 km

🛠️ Technical Specifications

Requirements

Python: 3.12+ (leveraging modern Python features)
Hardware: Raspberry Pi 3B+ or newer
Storage: 16GB+ microSD card
Network: Internet connection for USGS feeds, local network access to Meshtastic devices
Radio: Meshtastic-compatible LoRa modules (ESP32-based)

Dependencies

Runtime: requests, python-dotenv, mudp
Development: pytest, pytest-cov, black, isort, mypy, bump2version

Performance

Memory Usage: < 256MB (with built-in limits)
CPU Usage: < 50% (with built-in quotas)
Network: Minimal bandwidth usage with intelligent polling
Startup Time: < 60 seconds with network dependency management

🚀 Installation & Setup

Quick Start

# Clone and setup
git clone https://github.com/yourusername/UDPQuake.git
cd UDPQuake
uv venv && source .venv/bin/activate
uv pip install -e .

# Configure
touch .env
# Edit .env with your region settings

# Test
python -m udpquake

# Install as service
sudo systemctl enable udpquake
sudo systemctl start udpquake

Service Management

# Check status
sudo systemctl status udpquake

# View logs
sudo journalctl -u udpquake -f

# Control service
sudo systemctl {start|stop|restart} udpquake

🧪 Quality Assurance

Comprehensive Testing

100% Test Coverage: Complete unit test suite covering all major components
Integration Tests: End-to-end testing of USGS API integration and Meshtastic broadcasting
Error Handling: Robust error handling with graceful degradation
Type Safety: Full mypy type checking for enhanced reliability

Production Readiness

Error Recovery: Automatic reconnection and error handling
Resource Protection: Built-in memory and CPU limits to prevent system issues
Dependency Management: Network dependency ordering to ensure reliable startup
Monitoring: Comprehensive logging and status reporting via systemd

🔒 Security & Reliability

Network Security

UDP Multicast: Uses standard multicast protocols without opening additional ports
No Incoming Connections: Service only makes outbound connections to USGS
Isolation: Service runs as non-root user with limited permissions

Service Reliability

Automatic Restart: Service automatically restarts on failure
Graceful Degradation: Continues operation even if individual earthquake processing fails
Memory Management: Automatic cleanup of old earthquake IDs to prevent memory leaks
Network Resilience: Robust handling of network interruptions and API failures

📈 Performance Features

Intelligent Processing

Duplicate Detection: Automatic filtering of duplicate earthquake events
Memory Optimization: Smart cleanup of processed earthquake IDs
Efficient Polling: Optimized polling intervals to balance timeliness with resource usage
Batch Processing: Efficient handling of multiple simultaneous earthquake events

Resource Optimization

Lightweight Design: Minimal resource footprint suitable for Raspberry Pi
Background Operation: Runs efficiently as a background service
Network Efficiency: Minimal bandwidth usage with intelligent caching

🔧 Configuration Options

Geographic Boundaries

EARTHQUAKE_MIN_LATITUDE=33.0    # Southern boundary
EARTHQUAKE_MIN_LONGITUDE=-120.0 # Western boundary  
EARTHQUAKE_MAX_LATITUDE=35.0    # Northern boundary
EARTHQUAKE_MAX_LONGITUDE=-116.0 # Eastern boundary

Service Configuration

USGS_HOST=earthquake.usgs.gov   # USGS API hostname

🎯 Use Cases

Emergency Preparedness

Off-Grid Communities: Earthquake awareness for remote communities without cellular coverage
Emergency Response: First responders with mesh network communication
Disaster Recovery: Backup communication during infrastructure failures

Research & Monitoring

Citizen Science: Distributed earthquake monitoring networks
Educational Projects: STEM education and geology awareness
IoT Integration: Part of larger environmental monitoring systems

🐛 Known Issues & Limitations

Current Limitations

USGS Dependency: Requires internet connection for earthquake data (by design)
Regional Focus: Optimized for specific geographic regions (configurable)
Magnitude Threshold: Text alerts only sent for earthquakes > 3.5 magnitude

Troubleshooting Resources

Comprehensive troubleshooting guide in README.md
Service setup validation steps
Debug mode for development and testing
Detailed logging for issue diagnosis

🛣️ Future Roadmap

Planned Enhancements

Multiple Data Sources: Support for additional seismic data providers
Enhanced Filtering: Distance-based filtering from node location
Web Dashboard: Optional web interface for monitoring and configuration
Mobile Integration: Smartphone app integration for enhanced alerts

Community Features

Plugin System: Extensible architecture for custom alert types
Multi-Region: Support for monitoring multiple regions simultaneously
Advanced Analytics: Historical earthquake analysis and trending

👥 Community & Support

Getting Help

GitHub Issues: Bug reports and feature requests
GitHub Discussions: Community support and questions
Documentation: Comprehensive README with setup guides

Contributing

Open Source: GPL-3.0 license encourages community contributions
Development Environment: Complete development setup with testing tools
Code Quality: Automated formatting, linting, and type checking

🙏 Acknowledgments

Special thanks to:

USGS Earthquake Hazards Program for providing reliable, real-time earthquake data
Meshtastic Project for creating an excellent mesh networking platform
Open Source Community for the foundational libraries and tools

⚠️ Important Notes

Safety Disclaimer

UDPQuake is designed for informational purposes only. Always rely on official emergency services and warning systems for critical earthquake information and emergency response.

System Requirements

Ensure adequate power supply for Raspberry Pi and LoRa modules
Verify Meshtastic device compatibility and configuration
Test thoroughly in your specific environment before deploying

Ready to get started? Check out our comprehensive README.md for detailed installation and configuration instructions.

Have questions? Join the discussion on GitHub Discussions or report issues on GitHub Issues.

Initial release