Added mqtt docs
This commit is contained in:
413
MQTT_README.md
Normal file
413
MQTT_README.md
Normal file
@ -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 <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**:
|
||||
```bash
|
||||
# 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
|
||||
```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 <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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Run pump 1 for 15 seconds
|
||||
mosquitto_pub -h <broker> -t "plant_watering/commands/test_pump/1" -m "15000"
|
||||
```
|
||||
|
||||
#### Going on Vacation
|
||||
```bash
|
||||
# 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`)
|
||||
Reference in New Issue
Block a user