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