Stefan Ostermann
884182e1f7
- Add custom HA integration (config flow, switch, water_for service) - Add MQTT Last Will & Testament for offline detection - Publish 'online' on successful MQTT connect - Update README with integration docs
125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
# Greenhousino Irrigation — Home Assistant Integration
|
||
|
||
Custom Home Assistant integration for the Greenhousino ESP8266/ESP32 irrigation controller.
|
||
|
||
## Features
|
||
|
||
- **Pump switch** — Turn the irrigation pump on/off from Home Assistant
|
||
- **State tracking** — Real-time pump state via MQTT
|
||
- **Availability** — Shows online/offline status
|
||
- **`water_for` service** — Water for a specific duration (1–3600 seconds)
|
||
- **Config flow** — Set up via Home Assistant UI (Settings → Devices & Services → Add Integration)
|
||
- **Device registry** — Appears as a proper device with manufacturer/model info
|
||
|
||
## Installation
|
||
|
||
### Option 1: HACS (recommended)
|
||
|
||
1. Install [HACS](https://hacs.xyz/) in Home Assistant
|
||
2. Add this repository as a custom repository
|
||
3. Search for "Greenhousino Irrigation" and install
|
||
4. Restart Home Assistant
|
||
|
||
### Option 2: Manual installation
|
||
|
||
1. Copy the `greenhousino` folder to your Home Assistant config directory:
|
||
|
||
```bash
|
||
cp -r greenhousino /config/custom_components/
|
||
```
|
||
|
||
2. Restart Home Assistant
|
||
|
||
3. Go to **Settings → Devices & Services → Add Integration** and search for "Greenhousino Irrigation"
|
||
|
||
## Configuration
|
||
|
||
The config flow will guide you through two steps:
|
||
|
||
### Step 1: Host
|
||
- **Host IP address** — The IP of your ESP device (e.g., `192.168.178.50`). This is used for the web UI link in device info.
|
||
|
||
### Step 2: MQTT Topics
|
||
- **Command topic** — MQTT topic to send commands (default: `greenhousino/pump`)
|
||
- **State topic** — MQTT topic for state updates (default: `greenhousino/pumpstate`)
|
||
|
||
## Usage
|
||
|
||
### Switch entity
|
||
|
||
The integration creates a switch entity (`switch.greenhousino_irrigation_pump`) that you can:
|
||
- Toggle on/off from the Home Assistant UI
|
||
- Use in automations
|
||
- Add to dashboards
|
||
|
||
### `water_for` service
|
||
|
||
Water for a specific duration:
|
||
|
||
```yaml
|
||
service: greenhousino.water_for
|
||
data:
|
||
duration: 60 # seconds
|
||
```
|
||
|
||
Or from an automation:
|
||
```yaml
|
||
automation:
|
||
- alias: "Water garden every morning"
|
||
trigger:
|
||
- platform: time
|
||
at: "06:00:00"
|
||
action:
|
||
- service: greenhousino.water_for
|
||
data:
|
||
duration: 300 # 5 minutes
|
||
```
|
||
|
||
## MQTT Topics
|
||
|
||
| Direction | Topic | Payload | Description |
|
||
|-----------|-------|---------|-------------|
|
||
| HA → ESP | `greenhousino/pump` | `on` | Turn pump on (default 30s) |
|
||
| HA → ESP | `greenhousino/pump` | `off` | Turn pump off |
|
||
| HA → ESP | `greenhousino/pump` | `5000` | Turn pump on for 5000ms |
|
||
| ESP → HA | `greenhousino/pumpstate` | `on` | Pump is active |
|
||
| ESP → HA | `greenhousino/pumpstate` | `off` | Pump is off |
|
||
| ESP → HA | `greenhousino/pump/status` | `offline` | Device disconnected |
|
||
|
||
## Requirements
|
||
|
||
- Home Assistant 2024.x or later
|
||
- MQTT integration configured and connected to the same broker as your ESP device
|
||
|
||
## Troubleshooting
|
||
|
||
### Switch shows "unavailable"
|
||
- Make sure the MQTT integration is connected
|
||
- Verify the ESP device is publishing to the state topic
|
||
- Check that topics match between the ESP firmware and HA config
|
||
|
||
### Service call doesn't work
|
||
- Ensure MQTT integration is set up
|
||
- Check HA logs: `Logger → greenhousino`
|
||
- Verify the ESP is subscribed to the command topic
|
||
|
||
## YAML-only alternative (no custom component)
|
||
|
||
If you don't want a custom integration, you can use the built-in MQTT platform:
|
||
|
||
```yaml
|
||
switch:
|
||
- platform: mqtt
|
||
name: "Irrigation Pump"
|
||
command_topic: "greenhousino/pump"
|
||
state_topic: "greenhousino/pumpstate"
|
||
payload_on: "on"
|
||
payload_off: "off"
|
||
state_on: "on"
|
||
state_off: "off"
|
||
availability_topic: "greenhousino/pump/status"
|
||
payload_available: "online"
|
||
payload_not_available: "offline"
|
||
qos: 1
|
||
```
|