Plugin mqtt home assistant

Home Assistant

Publishes OSPy devices, controls and sensor values through Home Assistant MQTT Discovery.

At a glance

Item	Value
Version	1.0.1
Category	Automation and integrations
Author	Martin Pihrt
License	GPL-3.0
OSPy	3.0.211 or newer
Python	3.8 or newer
Permissions	network, system
Hardware	No dedicated hardware requirement declared
Dependencies	None
Python/OS packages	paho.mqtt.client / paho-mqtt (required), slugify / python-slugify (required), blinker (required)
Interfaces	Mobile API v1
Source	Open the plug-in directory

What it is for

Publishes OSPy devices, controls and sensor values through Home Assistant MQTT Discovery.

How it works and how to configure it

Tested in Python 3+

The MQTT HASS plugin implements MQTT Discovery for Home Assistant (HASS), including reporting and control of selected OSPy system settings, stations, programs, and sensor values over MQTT. MQTT Discovery enables automatic device and entity enrollment from the HASS user interface configuration panel, including plug-and-play availability detection, status, and control.

The plug-in includes an OSPy plugin.json manifest, registers its update worker and short balance-calculation jobs with the shared plug-in runtime, uses the common stop signal, and implements health(). Broker state now follows the real MQTT connect and disconnect callbacks. Discovery event receivers are replaced as one managed set during rediscovery and removed during stop, preventing duplicate Home Assistant updates after configuration changes or plug-in restarts. Diagnostics reports broker, client, receiver, subscription, discovery and publish state without exposing MQTT credentials.

Available devices and entities

This plugin can expose:

• System controls: rain delay, water level adjustment, scheduler enable switch, manual operation switch, and rain sensor state.
• Stations: one switch entity for each enabled OSPy station.
• Programs: one button entity for each OSPy program.
• Stop buttons for stopping all stations from Home Assistant.
• Temperature and humidity extension values: DHT temperature, DHT humidity, and DS1 to DS6 temperature sensors from the air temperature and humidity plugin.
• DS18B20 error filtering: DS error values such as -127 can be sent or suppressed before publishing to Home Assistant.
• Water tank extension values: tank level percentage and tank volume from the ultrasonic tank monitor plugin.
• Current loop tank extension values: level percentage and volume for each enabled current loop tank.
• Availability status so Home Assistant can show unavailable entities when a station, sensor, or optional plugin is disabled or not responding.

In-app help and settings notes

The following notes are generated from the help page shipped with this plug-in. Field names are also explained directly in the OSPy settings page.

About the MQTT HASS Plugin

The MQTT HASS plugin implement MQTT Discovery for Home Assistant (HASS), including report and control of some OSPy system settings and valves (stations) over MQTT. MQTT Discovery enables automatic devices and entities enrolment from HASS user interface configuration panel, including plug-and-play availability detection, status and control.

Using MQTT HASS plugin

This plugin is disabled by default. If you are reading this, the mqtt_hass plugin is probably enabled on your system. Otherwise, you can enable it using the plugin manager.

Requirements

• An MQTT broker such as Mosquitto is required to be accessible by OSPy device and HASS. This broker can be on different parts of the local network, on a remote network, or installed on either OSPy or HASS system.

• A working HASS system with an MQTT Integration such as Mosquitto broker

• A OSPy system with the base mqtt plugin installed and configured (see below).

• This plugin installed and configured on the same OSPy system as the base mqtt plugin (see below).

Setup

On OSPy - base MQTT plugin setup

• Install eclipse paho if not already on the Pi: sudo apt install python3-paho-mqtt

• Install the base MQTT plugin

• Configure base MQTT plugin

• MQTT Broker Host: This will be the URL of the MQTT broker or localhost if the broker is running on OSPy

• MQTT Broker Port: Default is 1883 but may be different depending on your MQTT broker

• MQTT Broker Username: Default is mosquitto but depends on your setup.

• MQTT Broker Password: Depends on your setup. Use pass as default

• MQTT Client ID: A unique name for OSPy system. Default is OSPy System name but can be changed on Options webpage.

On OSPy - MQTT HASS plugin setup

• Install Python python-slugify package if not already on the pi: sudo apt install python3-slugify

• Configure MQTT HASS plugin.

• Topic prefix: This prefix is used for OSPy system parameters and zones published to the MQTT broker. Leave this option empty to use a slugified OSPy System name. This setting will be slugified when saved. (Default: System name or "OSPy" if System name is empty).

• Name prefix: Used as prefix for all HASS devices and entities names. Leave this option empty to use a OSPy System name as prefix. For entities, this setting will be slugified. (Default: System name or "OSPy" if System name is empty).

• OSPy FQDN: OSPy network name or IP address. Used to compose the URL link to OSPy web interface displayed in HASS devices settings. Leave this option empty to use OSPy hostname or IP address used to connect with the MQTT broker. (Default: OSPy hostname).

• Device is Station name: if checked, use station name as part of HASS Device name. Changes to OSPy station name will update HASS Device name. (Default: unchecked)

On Home Assistant - MQTT setup

• Follow Home Assistant instructions to add MQTT integration via the user interface. MQTT discovery feature is enabled by default. MQTT integration will detect OSPy settings parameters and zones as devices and entities.

• Follow Home Assistant instructions to configure and use the newly added devices and entities.

Multiple OSPy systems connected to the same MQTT broker or Home Assistant instance

To integrate multiple OSPy systems, on each OSPy:

• Use different "System name" as set on OSPy Options webpage. Default OSPy System name is "OSPy"

• For each MQTT HASS plugin use different Topic prefix and Name prefix.

Home Assistant - available OSPy Devices and Entities

Devices and associated Entities made available with this plugin are:

• System device: rain delay control, water level adjustment, scheduler enable switch, manual operation switch, and rain sensor state.

• Station devices: one switch entity for each enabled OSPy station, allowing the station to be switched on or off from Home Assistant.

• Program devices: one button entity for each OSPy program, allowing the program to be started from Home Assistant.

• Stop buttons: button entities for stopping all stations from the station and program device groups.

• Temperature and humidity extension entities, when enabled: DHT temperature, DHT humidity, and DS1 to DS6 temperature sensors from the air temperature and humidity plugin.

• DS18B20 error filtering, when enabled in settings: DS error values such as -127 can be sent or suppressed before publishing to Home Assistant.

• Water tank extension entities, when enabled: tank level percentage and tank volume from the ultrasonic tank monitor plugin.

• Current loop tank extension entities, when enabled: level percentage and volume for each enabled current loop tank.

• Device availability status is published so Home Assistant can show unavailable entities when a station, sensor, or optional plugin is disabled or not responding.

Support

Check OSPy → Diagnostics first and remove passwords, tokens, private addresses and other secrets before sharing logs. Report reproducible plug-in problems in the OSPy-plugins issue tracker.

Back to the plug-in catalog