104 lines
2.4 KiB
Markdown
104 lines
2.4 KiB
Markdown
# Rules Engine
|
|
|
|
APScheduler-based automation rules engine for the home automation system.
|
|
|
|
## Features
|
|
|
|
- **APScheduler**: Background job scheduler for rule execution
|
|
- **Interval Jobs**: Periodic rule evaluation
|
|
- **Graceful Shutdown**: Proper signal handling (SIGINT, SIGTERM)
|
|
- **Logging**: Structured logging at INFO level
|
|
|
|
## Running
|
|
|
|
```bash
|
|
poetry run python -m apps.rules.main
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The rules engine uses APScheduler's `BackgroundScheduler` to run automation rules on a schedule.
|
|
|
|
### Current Jobs
|
|
|
|
- **rule_tick**: Example job that runs every minute
|
|
- Logs "Rule tick" message
|
|
- Can be extended with actual rule logic
|
|
|
|
## Example Output
|
|
|
|
```
|
|
2025-10-31 13:05:46,865 - __main__ - INFO - Rules engine starting...
|
|
2025-10-31 13:05:46,868 - __main__ - INFO - Scheduler started with rule_tick job (every 1 minute)
|
|
2025-10-31 13:05:46,868 - __main__ - INFO - Rule tick
|
|
2025-10-31 13:06:46,874 - __main__ - INFO - Rule tick
|
|
2025-10-31 13:07:46,874 - __main__ - INFO - Rule tick
|
|
```
|
|
|
|
## Signal Handling
|
|
|
|
The application handles shutdown signals gracefully:
|
|
|
|
- **SIGINT** (Ctrl+C): Initiates graceful shutdown
|
|
- **SIGTERM**: Initiates graceful shutdown
|
|
|
|
On shutdown:
|
|
1. Stops accepting new jobs
|
|
2. Waits for running jobs to complete
|
|
3. Shuts down the scheduler
|
|
4. Exits cleanly
|
|
|
|
## Adding New Rules
|
|
|
|
To add a new rule, define a function and schedule it:
|
|
|
|
```python
|
|
def my_custom_rule() -> None:
|
|
"""Custom automation rule."""
|
|
# Your rule logic here
|
|
logger.info("Custom rule executed")
|
|
|
|
# In main():
|
|
scheduler.add_job(
|
|
my_custom_rule,
|
|
'interval',
|
|
minutes=5, # Run every 5 minutes
|
|
id='custom_rule',
|
|
name='My Custom Rule'
|
|
)
|
|
```
|
|
|
|
## Scheduler Triggers
|
|
|
|
APScheduler supports various trigger types:
|
|
|
|
- **interval**: Run at fixed intervals (e.g., every N minutes)
|
|
- **cron**: Run at specific times (e.g., daily at 8:00 AM)
|
|
- **date**: Run once at a specific datetime
|
|
|
|
Example with cron trigger:
|
|
|
|
```python
|
|
scheduler.add_job(
|
|
morning_routine,
|
|
'cron',
|
|
hour=8,
|
|
minute=0,
|
|
id='morning',
|
|
name='Morning Routine'
|
|
)
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- **APScheduler**: Advanced job scheduling
|
|
|
|
## Future Enhancements
|
|
|
|
- [ ] Load rules from configuration file
|
|
- [ ] MQTT integration for device state monitoring
|
|
- [ ] Rule conditions (if/then logic)
|
|
- [ ] Rule chaining and dependencies
|
|
- [ ] Web API for dynamic rule management
|
|
- [ ] Persistent job store (database)
|