From 1cd35970c106c012be94b7563048ef4509f28f8f Mon Sep 17 00:00:00 2001 From: Stephen Minakian Date: Sun, 20 Jul 2025 12:05:58 -0600 Subject: [PATCH] Added mqtt docs --- MQTT_README.md | 413 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 413 insertions(+) create mode 100644 MQTT_README.md diff --git a/MQTT_README.md b/MQTT_README.md new file mode 100644 index 0000000..6e01abd --- /dev/null +++ b/MQTT_README.md @@ -0,0 +1,413 @@ +# MQTT Topics Reference + +Complete reference for all MQTT topics used by the ESP32-S3 Plant Watering System. + +## Topic Structure Overview + +``` +plant_watering/ +├── status # System online/offline status +├── pump/ # Pump control and monitoring +│ ├── 1/ # Pump 1 +│ │ ├── set # Control commands +│ │ ├── state # Current state +│ │ ├── speed # Speed control +│ │ ├── stats # Runtime statistics +│ │ ├── runtime # Current runtime (when running) +│ │ └── cooldown # Cooldown status +│ └── 2/ # Pump 2 (same structure) +├── moisture/ # Moisture sensor readings +│ ├── 1 # Sensor 1 percentage +│ └── 2 # Sensor 2 percentage +├── schedule/ # Scheduling system +│ ├── status # Global scheduler status +│ ├── summary # Schedule summary (on demand) +│ ├── time/set # Manual time setting +│ ├── 1/ # Pump 1 schedules +│ │ ├── trigger # Manual trigger all schedules +│ │ ├── get # Get all schedules for pump +│ │ ├── executed # Execution notification +│ │ └── 0-3/ # Schedule slots +│ │ ├── config # Schedule configuration +│ │ ├── status # Schedule status (periodic) +│ │ └── current # Schedule details (on demand) +│ └── 2/ # Pump 2 (same structure) +├── system/ # System information +│ ├── time # Time response (on demand) +│ └── current_time # Current time (periodic) +├── commands/ # System commands +│ ├── emergency_stop # Stop all pumps immediately +│ ├── test_mode # Enable/disable test mode +│ ├── holiday_mode # Enable/disable all schedules +│ ├── get_time # Request current time +│ ├── get_schedules # Request all schedules +│ └── test_pump/ # Test pump operation +│ ├── 1 # Test pump 1 +│ └── 2 # Test pump 2 +├── settings/ # Runtime configuration +│ └── pump/ +│ └── 1-2/ +│ ├── max_runtime # Maximum runtime per cycle +│ ├── min_interval # Minimum time between runs +│ ├── min_speed # Minimum speed percentage +│ └── max_speed # Maximum speed percentage +└── alerts/ # System alerts + ├── pump_error/1-2 # Pump errors + └── schedule_error/1-2 # Schedule execution errors +``` + +## Pump Control Topics + +### Basic Pump Control +**Topic**: `plant_watering/pump/[1-2]/set` +**Direction**: Subscribe +**Payload**: +- `on` - Start pump at default speed (80%) +- `off` - Stop pump +- `pulse` - Run pump for 5 seconds + +**Example**: +```bash +# Turn pump 1 on +mosquitto_pub -h -t "plant_watering/pump/1/set" -m "on" + +# Turn pump 1 off +mosquitto_pub -h -t "plant_watering/pump/1/set" -m "off" + +# Pulse pump 2 +mosquitto_pub -h -t "plant_watering/pump/2/set" -m "pulse" +``` + +### Pump Speed Control +**Topic**: `plant_watering/pump/[1-2]/speed` +**Direction**: Subscribe +**Payload**: `0-100` (percentage) +**Note**: Only works when pump is running + +**Example**: +```bash +# Set pump 1 to 50% speed +mosquitto_pub -h -t "plant_watering/pump/1/speed" -m "50" +``` + +### Pump State +**Topic**: `plant_watering/pump/[1-2]/state` +**Direction**: Publish +**Payload**: `on` or `off` +**Retained**: Yes + +### Pump Statistics +**Topic**: `plant_watering/pump/[1-2]/stats` +**Direction**: Publish +**Payload**: JSON +```json +{ + "total_runtime": 123456, + "run_count": 42, + "last_duration": 5000 +} +``` + +### Pump Runtime (When Running) +**Topic**: `plant_watering/pump/[1-2]/runtime` +**Direction**: Publish +**Payload**: Current runtime in milliseconds +**Note**: Published every minute while pump is running + +### Pump Cooldown Status +**Topic**: `plant_watering/pump/[1-2]/cooldown` +**Direction**: Publish +**Payload**: `true` +**Note**: Published when pump is in cooldown period + +## Moisture Sensor Topics + +### Moisture Readings +**Topic**: `plant_watering/moisture/[1-2]` +**Direction**: Publish +**Payload**: `0-100` (percentage) +**Frequency**: Every 10 seconds +**Note**: Currently simulated values + +## Scheduling Topics + +### Schedule Configuration +**Topic**: `plant_watering/schedule/[1-2]/[0-3]/config` +**Direction**: Subscribe +**Payload**: JSON configuration + +**Schedule Types**: + +1. **Interval Schedule**: +```json +{ + "type": "interval", + "enabled": true, + "interval_minutes": 120, + "duration_ms": 15000, + "speed_percent": 70 +} +``` + +2. **Time of Day Schedule**: +```json +{ + "type": "time_of_day", + "enabled": true, + "hour": 6, + "minute": 30, + "duration_ms": 20000, + "speed_percent": 80 +} +``` + +3. **Days and Time Schedule**: +```json +{ + "type": "days_time", + "enabled": true, + "hour": 18, + "minute": 0, + "days_mask": 127, + "duration_ms": 25000, + "speed_percent": 75 +} +``` + +4. **Disable Schedule**: +```json +{ + "type": "disabled" +} +``` + +### Schedule Status +**Topic**: `plant_watering/schedule/[1-2]/[0-3]/status` +**Direction**: Publish +**Frequency**: Every minute (if enabled) +**Retained**: Yes +**Payload**: JSON with full schedule details including next run time + +### Schedule Execution +**Topic**: `plant_watering/schedule/[1-2]/executed` +**Direction**: Publish +**Payload**: JSON +```json +{ + "schedule_id": 0, + "duration_ms": 20000, + "speed": 80 +} +``` + +### Global Schedule Status +**Topic**: `plant_watering/schedule/status` +**Direction**: Publish +**Frequency**: Every minute +**Retained**: Yes +**Payload**: JSON +```json +{ + "holiday_mode": false, + "time_sync": true, + "active_schedules": 3, + "time": 1706436000 +} +``` + +### Manual Schedule Trigger +**Topic**: `plant_watering/schedule/[1-2]/trigger` +**Direction**: Subscribe +**Payload**: Any value +**Action**: Triggers all enabled schedules for the specified pump + +### Get Schedules +**Topic**: `plant_watering/schedule/[1-2]/get` +**Direction**: Subscribe +**Payload**: Any value +**Response**: Publishes all schedules for pump to `current` topics + +### Manual Time Setting +**Topic**: `plant_watering/schedule/time/set` +**Direction**: Subscribe +**Payload**: Unix timestamp as string +**Example**: `"1706436000"` + +## System Topics + +### System Status +**Topic**: `plant_watering/status` +**Direction**: Publish +**Payload**: `online` or `offline` +**Retained**: Yes +**Note**: Uses MQTT Last Will and Testament + +### Current Time (Periodic) +**Topic**: `plant_watering/system/current_time` +**Direction**: Publish +**Frequency**: Every minute +**Payload**: JSON +```json +{ + "timestamp": 1706436000, + "datetime": "2024-01-28 14:32:00 MST", + "day_of_week": 0, + "hour": 14, + "minute": 32 +} +``` + +### Time Response (On Demand) +**Topic**: `plant_watering/system/time` +**Direction**: Publish +**Trigger**: Send any message to `plant_watering/commands/get_time` +**Payload**: JSON +```json +{ + "timestamp": 1706436000, + "datetime": "2024-01-28 14:32:45 MST", + "timezone": "MST7MDT,M3.2.0,M11.1.0", + "synced": true +} +``` + +## Command Topics + +### Emergency Stop +**Topic**: `plant_watering/commands/emergency_stop` +**Direction**: Subscribe +**Payload**: Any value +**Action**: Immediately stops all pumps + +### Test Mode +**Topic**: `plant_watering/commands/test_mode` +**Direction**: Subscribe +**Payload**: `on` or `off` +**Action**: Enables/disables test mode with shorter intervals + +Test mode settings: +- Max runtime: 30 seconds +- Min interval: 5 seconds + +### Holiday Mode +**Topic**: `plant_watering/commands/holiday_mode` +**Direction**: Subscribe +**Payload**: `on` or `off` +**Action**: Pauses all schedules without deleting them + +### Get Time +**Topic**: `plant_watering/commands/get_time` +**Direction**: Subscribe +**Payload**: Any value +**Response**: Publishes to `plant_watering/system/time` + +### Get All Schedules +**Topic**: `plant_watering/commands/get_schedules` +**Direction**: Subscribe +**Payload**: Any value +**Response**: Publishes all schedules and summary + +### Test Pump +**Topic**: `plant_watering/commands/test_pump/[1-2]` +**Direction**: Subscribe +**Payload**: Duration in milliseconds (max 30000) +**Example**: `"15000"` for 15 seconds + +## Settings Topics + +### Pump Settings +**Base Topic**: `plant_watering/settings/pump/[1-2]/` + +#### Maximum Runtime +**Topic**: `plant_watering/settings/pump/[1-2]/max_runtime` +**Payload**: Milliseconds (e.g., `"60000"` for 60 seconds) + +#### Minimum Interval +**Topic**: `plant_watering/settings/pump/[1-2]/min_interval` +**Payload**: Milliseconds (e.g., `"300000"` for 5 minutes) + +#### Speed Limits +**Topic**: `plant_watering/settings/pump/[1-2]/min_speed` +**Topic**: `plant_watering/settings/pump/[1-2]/max_speed` +**Payload**: Percentage 0-100 + +## Alert Topics + +### Pump Errors +**Topic**: `plant_watering/alerts/pump_error/[1-2]` +**Direction**: Publish +**Payload**: Error description string +**Examples**: +- `"Maximum runtime exceeded"` +- `"Cooldown period not elapsed"` + +### Schedule Errors +**Topic**: `plant_watering/alerts/schedule_error/[1-2]` +**Direction**: Publish +**Payload**: Error description +**Example**: `"Schedule 0 failed: ESP_ERR_INVALID_STATE"` + +## Monitoring Examples + +### Subscribe to All Topics +```bash +# Monitor everything +mosquitto_sub -h -t "plant_watering/#" -v + +# Monitor pump activity only +mosquitto_sub -h -t "plant_watering/pump/#" -v + +# Monitor schedules only +mosquitto_sub -h -t "plant_watering/schedule/#" -v + +# Monitor alerts only +mosquitto_sub -h -t "plant_watering/alerts/#" -v +``` + +### Common Operations + +#### Daily Morning Watering +```bash +mosquitto_pub -h -t "plant_watering/schedule/1/0/config" -m '{ + "type": "time_of_day", + "enabled": true, + "hour": 6, + "minute": 0, + "duration_ms": 20000, + "speed_percent": 80 +}' +``` + +#### Check System Status +```bash +# Get current time +mosquitto_pub -h -t "plant_watering/commands/get_time" -m "1" + +# Get all schedules +mosquitto_pub -h -t "plant_watering/commands/get_schedules" -m "1" +``` + +#### Manual Watering +```bash +# Run pump 1 for 15 seconds +mosquitto_pub -h -t "plant_watering/commands/test_pump/1" -m "15000" +``` + +#### Going on Vacation +```bash +# Enable holiday mode +mosquitto_pub -h -t "plant_watering/commands/holiday_mode" -m "on" + +# When back, disable holiday mode +mosquitto_pub -h -t "plant_watering/commands/holiday_mode" -m "off" +``` + +## Notes + +- All timestamps are Unix timestamps (seconds since epoch) +- All durations are in milliseconds +- Speed values are percentages (0-100) +- Day of week: 0=Sunday, 1=Monday, ..., 6=Saturday +- Days mask is a bitmask where bit 0=Sunday +- Retained messages persist across broker restarts +- JSON payloads use unquoted booleans (`true`/`false`) \ No newline at end of file