{"id":37651374,"url":"https://github.com/emirkmo/google-alert","last_synced_at":"2026-01-16T11:34:03.142Z","repository":{"id":314969100,"uuid":"1057552233","full_name":"emirkmo/google-alert","owner":"emirkmo","description":"Temperature monitoring system with Chromecast alerts","archived":false,"fork":false,"pushed_at":"2025-09-15T23:24:05.000Z","size":59,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-16T00:21:07.847Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emirkmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-15T22:18:44.000Z","updated_at":"2025-09-15T23:24:09.000Z","dependencies_parsed_at":"2025-09-16T00:21:11.207Z","dependency_job_id":"e075cef6-35a0-44b5-b426-0469ac6001cb","html_url":"https://github.com/emirkmo/google-alert","commit_stats":null,"previous_names":["emirkmo/google-alert"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/emirkmo/google-alert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emirkmo%2Fgoogle-alert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emirkmo%2Fgoogle-alert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emirkmo%2Fgoogle-alert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emirkmo%2Fgoogle-alert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emirkmo","download_url":"https://codeload.github.com/emirkmo/google-alert/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emirkmo%2Fgoogle-alert/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T11:34:02.348Z","updated_at":"2026-01-16T11:34:03.136Z","avatar_url":"https://github.com/emirkmo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Google Alert\n\nA 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.\n\nNOTE: AI was used to help write the README and with some github actions worklows. Rest is *hand-coded*. Apologies in advance for a rambling README as a result.\n\n## Features\n\n- 📺 **Chromecast Alerts**: Instant notifications via Chromecast devices\n- 🌙 **Night Mode**: Suppress alerts during specified hours (e.g., 9 PM - 7 AM)\n- ⏰ **Cooldown Period**: Prevent alert spam with configurable cooldown periods\n- 🔒 **Process Safety**: File locking prevents overlapping monitoring processes\n- 📊 **SQLite Integration**: Works with temperature data stored in SQLite databases\n- 🧪 **Comprehensive Testing**: Full test suite covering all core functionality\n\n## Quick Start\n\n### Installation\n\n**From PyPI (recommended):**\n```bash\npip install google-alert\n```\n\n**From source:**\n```bash\n# Clone the repository\ngit clone https://github.com/emirkmo/google-alert.git\ncd google-alert\n\n# Install with uv (recommended)\nuv sync\n\n# Or install with pip\npip install -e .\n```\n\n### Basic Usage\n\n**Set up monitoring alerts** (run via cron every minute):\n```bash\npython -m google_alert.monitor_chron /path/to/database.db\n```\n\n**Note**: This library focuses on the alerting functionality. For a complete temperature monitoring system including DHT sensor reading, see the [DHT22 Temperature Monitor](https://github.com/emirkmo/dht22_temp_monitor_google_alert/) repository, which includes the `temp_sensor.py` implementation and embedded Adafruit_DHT library.\n\n## Configuration\n\n### Monitor Settings\n\nThe monitor supports several command-line options:\n\n```bash\npython -m google_alert.monitor_chron database.db [options]\n\nOptions:\n  -s, --threshold FLOAT    Temperature threshold in °C (default: 8.0)\n  -c, --cooldown INT       Cooldown period in seconds (default: 3600)\n  -w, --window INT         Time window in seconds for averaging (default: 60)\n  -m, --message TEXT       Alert message (default: \"Temperature below threshold\")\n  --night-start INT        Hour when night mode starts (0-23, default: 21)\n  --night-end INT          Hour when night mode ends (0-23, default: 7)\n```\n\n### Example Cron Setup\n\nAdd to your crontab (`crontab -e`) to run monitoring every minute:\n\n```bash\n* * * * * /path/to/venv/bin/python -m google_alert.monitor_chron /path/to/database.db\n```\n\n## Architecture\n\n### Core Modules\n\n- **`monitor_chron.py`**: Main monitoring script that checks temperature averages and sends alerts\n- **`sensor_db.py`**: Database operations for reading temperature data and managing alert history\n- **`browser.py`**: Chromecast device discovery and message broadcasting\n\n### Module Descriptions\n\n#### `monitor_chron.py`\nThe core monitoring module that runs as a cron job. It:\n- Queries average temperature from SQLite over a configurable time window\n- Checks if temperature is below threshold\n- Enforces cooldown periods to prevent alert spam\n- Implements night mode to suppress alerts during specified hours\n- Uses file locking to prevent overlapping runs\n- Sends alerts via Chromecast when conditions are met\n\n#### `sensor_db.py`\nDatabase interface module that provides:\n- SQLite database initialization with proper schema\n- Temperature reading insertion and retrieval\n- Alert history tracking for cooldown management\n- Average temperature calculation over time windows\n\n#### `browser.py`\nChromecast communication module that handles:\n- Automatic discovery of Chromecast devices on the network\n- Message broadcasting to all available devices\n- Error handling for network and device communication issues\n\n### Example Usage\n\nThis library is designed to work with any temperature data source. See the `examples/` directory for usage examples:\n\n- **`examples/temp_sensor.py`**: Simple example showing how to use the library with DHT sensors\n- **[DHT22 Temperature Monitor](https://github.com/emirkmo/dht22_temp_monitor_google_alert/)**: Complete production implementation with modular sensor handling\n\n## Library Design Philosophy\n\n### Separation of Concerns\n\nThis library follows a clean separation of concerns:\n\n- **`google_alert`**: Pure alerting library focused on Chromecast notifications\n- **Sensor implementations**: Separate repositories handle hardware-specific data collection\n- **Database schema**: Controlled by the alerting library for consistency\n\n### Why Separate Repositories?\n\n1. **Library Reusability**: The `google_alert` package can be used with any temperature data source (DHT22, DS18B20, BME280, etc.)\n2. **Independent Evolution**: Alerting logic and sensor hardware can evolve independently\n3. **Clear Dependencies**: Sensor implementations depend on the alerting library, not vice versa\n4. **Focused Scope**: Each repository has a single, well-defined responsibility\n\n### Publishing to PyPI\n\nThis library uses **trusted publishing** for secure, automated PyPI releases via GitHub Actions. No API tokens are required!\n\n#### Automated Publishing\n\nReleases are automatically published to PyPI when GitHub releases are created:\n\n1. **Update version** in `pyproject.toml`\n2. **Create GitHub release** with a tag\n3. **GitHub Actions** automatically builds and publishes to PyPI via the `pypi` environment\n\n**Note**: The `pypi` environment has protection rules requiring approval before publishing.\n\n#### Manual Publishing\n\nFor manual publishing (requires PyPI API token):\n\n```bash\n# Build the package\nuv build\n\n# Publish to PyPI\nuv publish\n```\n\n#### Trusted Publishing Setup\n\nThe repository is configured for PyPI trusted publishing with these settings:\n- **PyPI Project**: `google-alert`\n- **GitHub Owner**: `emirkmo`\n- **GitHub Repository**: `google-alert`\n- **Workflow**: `.github/workflows/ci-cd.yml`\n- **Environment**: `pypi` (with protection rules)\n\n#### Verifying Setup\n\nCheck the environment and publishing configuration:\n\n```bash\n# Verify GitHub environment exists\ngh api repos/emirkmo/google-alert/environments\n\n# Check workflow configuration\ngh workflow view ci-cd.yml\n```\n\nThe minimal dependencies (`orjson`, `pychromecast`) make it lightweight and suitable for distribution.\n\n### Database Schema\n\nThe system uses SQLite with two main tables:\n\n- **`readings`**: Stores temperature and humidity readings with timestamps\n- **`alerts`**: Tracks alert history for cooldown management\n\n## Development\n\n### Running Tests\n\n```bash\n# Install development dependencies\nuv sync --extra dev\n\n# Run all tests\nuv run pytest tests/ -v\n\n# Run specific test\nuv run pytest tests/test_monitor.py::TestMonitorMinute::test_night_time_alert_silencing -v\n```\n\n### Examples\n\nCheck the `examples/` directory for usage examples:\n- `examples/temp_sensor.py`: Simple DHT sensor integration example\n\n### Building the Package\n\n```bash\n# Build distribution packages\nuv build\n\n# The built packages will be in the dist/ directory\n```\n\n## Requirements\n\n- Python 3.11+\n- Chromecast devices on the same network\n- SQLite database with temperature readings\n\n### Dependencies\n\n- `orjson`: Fast JSON serialization\n- `pychromecast`: Chromecast device communication\n\n## Alert Logic\n\nThe system follows this decision tree for sending alerts:\n\n1. ✅ **Temperature Check**: Is average temperature below threshold?\n2. ✅ **Cooldown Check**: Has enough time passed since last alert?\n3. ✅ **Night Mode Check**: Is current time outside night mode hours?\n4. ✅ **Send Alert**: If all conditions are met, broadcast to Chromecast devices\n\n## Night Mode\n\nNight 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.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **No Chromecast devices found**: Ensure devices are on the same network and not in guest mode\n2. **Database locked**: Check for multiple instances running simultaneously\n3. **No temperature data**: Ensure your temperature sensor system is writing data to the SQLite database\n\n### Logging\n\nThe system logs to syslog (LOCAL0 facility) by default. Check your system logs:\n\n```bash\n# On systemd systems\njournalctl -f -u your-service\n\n# On traditional systems\ntail -f /var/log/syslog | grep monitor_chron\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is open source. Please check the repository for license details.\n\n## Support\n\nFor issues and questions:\n- Open an issue on GitHub\n- Check the troubleshooting section above\n- Review the test cases for usage examples\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femirkmo%2Fgoogle-alert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femirkmo%2Fgoogle-alert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femirkmo%2Fgoogle-alert/lists"}