google-alert 0.1.2

A Python library for sending temperature alerts via Chromecast devices

Google Alert

A Python library for sending temperature alerts via Chromecast devices. This library provides the core functionality for monitoring temperature data stored in SQLite and broadcasting alerts when thresholds are exceeded.

Features

• 📺 Chromecast Alerts: Instant notifications via Chromecast devices
• 🌙 Night Mode: Suppress alerts during specified hours (e.g., 9 PM - 7 AM)
• ⏰ Cooldown Period: Prevent alert spam with configurable cooldown periods
• 🔒 Process Safety: File locking prevents overlapping monitoring processes
• 📊 SQLite Integration: Works with temperature data stored in SQLite databases
• 🧪 Comprehensive Testing: Full test suite covering all core functionality

Quick Start

Installation

From PyPI (recommended):

pip install google-alert

From source:

# Clone the repository
git clone https://github.com/emirkmo/google-alert.git
cd google-alert

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Basic Usage

Set up monitoring alerts (run via cron every minute):

python -m google_alert.monitor_chron /path/to/database.db

Note: This library focuses on the alerting functionality. For a complete temperature monitoring system including DHT sensor reading, see the DHT22 Temperature Monitor repository, which includes the temp_sensor.py implementation and embedded Adafruit_DHT library.

Configuration

Monitor Settings

The monitor supports several command-line options:

python -m google_alert.monitor_chron database.db [options]

Options:
  -s, --threshold FLOAT    Temperature threshold in °C (default: 8.0)
  -c, --cooldown INT       Cooldown period in seconds (default: 3600)
  -w, --window INT         Time window in seconds for averaging (default: 60)
  -m, --message TEXT       Alert message (default: "Temperature below threshold")
  --night-start INT        Hour when night mode starts (0-23, default: 21)
  --night-end INT          Hour when night mode ends (0-23, default: 7)

Example Cron Setup

Add to your crontab (crontab -e) to run monitoring every minute:

* * * * * /path/to/venv/bin/python -m google_alert.monitor_chron /path/to/database.db

Architecture

Core Modules

• monitor_chron.py: Main monitoring script that checks temperature averages and sends alerts
• sensor_db.py: Database operations for reading temperature data and managing alert history
• browser.py: Chromecast device discovery and message broadcasting

Module Descriptions

monitor_chron.py

The core monitoring module that runs as a cron job. It:

• Queries average temperature from SQLite over a configurable time window
• Checks if temperature is below threshold
• Enforces cooldown periods to prevent alert spam
• Implements night mode to suppress alerts during specified hours
• Uses file locking to prevent overlapping runs
• Sends alerts via Chromecast when conditions are met

sensor_db.py

Database interface module that provides:

• SQLite database initialization with proper schema
• Temperature reading insertion and retrieval
• Alert history tracking for cooldown management
• Average temperature calculation over time windows

browser.py

Chromecast communication module that handles:

• Automatic discovery of Chromecast devices on the network
• Message broadcasting to all available devices
• Error handling for network and device communication issues

Example Usage

This library is designed to work with any temperature data source. See the examples/ directory for usage examples:

• examples/temp_sensor.py: Simple example showing how to use the library with DHT sensors
• DHT22 Temperature Monitor: Complete production implementation with modular sensor handling

Library Design Philosophy

Separation of Concerns

This library follows a clean separation of concerns:

• google_alert: Pure alerting library focused on Chromecast notifications
• Sensor implementations: Separate repositories handle hardware-specific data collection
• Database schema: Controlled by the alerting library for consistency

Why Separate Repositories?

1. Library Reusability: The google_alert package can be used with any temperature data source (DHT22, DS18B20, BME280, etc.)
2. Independent Evolution: Alerting logic and sensor hardware can evolve independently
3. Clear Dependencies: Sensor implementations depend on the alerting library, not vice versa
4. Focused Scope: Each repository has a single, well-defined responsibility

Publishing to PyPI

This library uses trusted publishing for secure, automated PyPI releases via GitHub Actions. No API tokens are required!

Automated Publishing

Releases are automatically published to PyPI when GitHub releases are created:

1. Update version in pyproject.toml
2. Create GitHub release with a tag
3. GitHub Actions automatically builds and publishes to PyPI via the pypi environment

Note: The pypi environment has protection rules requiring approval before publishing.

Manual Publishing

For manual publishing (requires PyPI API token):

# Build the package
uv build

# Publish to PyPI
uv publish

Trusted Publishing Setup

The repository is configured for PyPI trusted publishing with these settings:

• PyPI Project: google-alert
• GitHub Owner: emirkmo
• GitHub Repository: google-alert
• Workflow: .github/workflows/ci-cd.yml
• Environment: pypi (with protection rules)

Verifying Setup

Check the environment and publishing configuration:

# Verify GitHub environment exists
gh api repos/emirkmo/google-alert/environments

# Check workflow configuration
gh workflow view ci-cd.yml

The minimal dependencies (orjson, pychromecast) make it lightweight and suitable for distribution.

Database Schema

The system uses SQLite with two main tables:

• readings: Stores temperature and humidity readings with timestamps
• alerts: Tracks alert history for cooldown management

Development

Running Tests

# Install development dependencies
uv sync --extra dev

# Run all tests
uv run pytest tests/ -v

# Run specific test
uv run pytest tests/test_monitor.py::TestMonitorMinute::test_night_time_alert_silencing -v

Examples

Check the examples/ directory for usage examples:

• examples/temp_sensor.py: Simple DHT sensor integration example

Building the Package

# Build distribution packages
uv build

# The built packages will be in the dist/ directory

Requirements

• Python 3.11+
• Chromecast devices on the same network
• SQLite database with temperature readings

Dependencies

• orjson: Fast JSON serialization
• pychromecast: Chromecast device communication

Alert Logic

The system follows this decision tree for sending alerts:

1. ✅ Temperature Check: Is average temperature below threshold?
2. ✅ Cooldown Check: Has enough time passed since last alert?
3. ✅ Night Mode Check: Is current time outside night mode hours?
4. ✅ Send Alert: If all conditions are met, broadcast to Chromecast devices

Night Mode

Night mode suppresses alerts during specified hours to avoid disturbing sleep. The default night window is 9 PM to 7 AM, but this can be customized via command-line options.

Troubleshooting

Common Issues

1. No Chromecast devices found: Ensure devices are on the same network and not in guest mode
2. Database locked: Check for multiple instances running simultaneously
3. No temperature data: Ensure your temperature sensor system is writing data to the SQLite database

Logging

The system logs to syslog (LOCAL0 facility) by default. Check your system logs:

# On systemd systems
journalctl -f -u your-service

# On traditional systems
tail -f /var/log/syslog | grep monitor_chron

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is open source. Please check the repository for license details.

Support

For issues and questions:

• Open an issue on GitHub
• Check the troubleshooting section above
• Review the test cases for usage examples