# 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`)