PlantWater/MQTT_README.md

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:

# Turn pump 1 on
mosquitto_pub -h <broker> -t "plant_watering/pump/1/set" -m "on"

# Turn pump 1 off
mosquitto_pub -h <broker> -t "plant_watering/pump/1/set" -m "off"

# Pulse pump 2
mosquitto_pub -h <broker> -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:

# Set pump 1 to 50% speed
mosquitto_pub -h <broker> -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

{
  "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:

{
  "type": "interval",
  "enabled": true,
  "interval_minutes": 120,
  "duration_ms": 15000,
  "speed_percent": 70
}

2. Time of Day Schedule:

{
  "type": "time_of_day",
  "enabled": true,
  "hour": 6,
  "minute": 30,
  "duration_ms": 20000,
  "speed_percent": 80
}

3. Days and Time Schedule:

{
  "type": "days_time",
  "enabled": true,
  "hour": 18,
  "minute": 0,
  "days_mask": 127,
  "duration_ms": 25000,
  "speed_percent": 75
}

4. Disable Schedule:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

# Monitor everything
mosquitto_sub -h <broker> -t "plant_watering/#" -v

# Monitor pump activity only
mosquitto_sub -h <broker> -t "plant_watering/pump/#" -v

# Monitor schedules only
mosquitto_sub -h <broker> -t "plant_watering/schedule/#" -v

# Monitor alerts only
mosquitto_sub -h <broker> -t "plant_watering/alerts/#" -v

Common Operations

Daily Morning Watering

mosquitto_pub -h <broker> -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

# Get current time
mosquitto_pub -h <broker> -t "plant_watering/commands/get_time" -m "1"

# Get all schedules
mosquitto_pub -h <broker> -t "plant_watering/commands/get_schedules" -m "1"

Manual Watering

# Run pump 1 for 15 seconds
mosquitto_pub -h <broker> -t "plant_watering/commands/test_pump/1" -m "15000"

Going on Vacation

# Enable holiday mode
mosquitto_pub -h <broker> -t "plant_watering/commands/holiday_mode" -m "on"

# When back, disable holiday mode
mosquitto_pub -h <broker> -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)