V3 SmartLINK Wi-Fi MQTT Setup
MQTT
To enable MQTT you must have our Version 3 SmartLINK Wi-Fi module, with the latest firmware. Press here to learn how to update your V3 SmartLINK module firmware.
The MQTT protocol provides a lightweight method of carrying out messaging using a publish/subscribe model. This makes it suitable for Internet of Things messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers.
Broker
The SV-Wifi-V3.1 can be configured as an MQTT client to connect to an MQTT broker. An MQTT broker is a crucial component in the MQTT communication architecture, and it plays a central role in facilitating communication between MQTT clients. Here’s an overview of what an MQTT broker does:
- Message Routing and Distribution: The MQTT broker receives messages (also called publications) from MQTT publishers (clients that send messages) and routes them to the appropriate MQTT subscribers (clients that receive messages) based on predefined topics. Topics act as channels or subjects to which clients can subscribe or publish messages.
- Topic-based Filtering: Clients subscribe to specific topics, and the broker ensures that messages are delivered only to clients interested in those topics. This allows for a flexible and scalable communication model where clients can selectively receive information.
- Message Queuing: The broker can queue messages for clients that are temporarily offline or unable to process messages at the moment. When a client becomes available, the broker delivers the queued messages.
- Quality of Service (QoS) Handling: MQTT supports different levels of QoS to ensure message delivery reliability. The broker manages the QoS levels requested by publishers and subscribers, making sure that messages are delivered according to the specified QoS.
- Connection Management: The broker handles the establishment and termination of connections between clients. It manages client sessions, ensuring that a client can seamlessly disconnect and reconnect without losing critical information.
- Security: MQTT brokers often provide security features such as authentication and authorization mechanisms. This ensures that only authorized clients can connect to the broker and access specific topics.
- Retained Messages: The broker can store retained messages associated with specific topics. When a new client subscribes to a topic, it receives the most recent retained message for that topic. This feature is useful for providing the latest state or information to new subscribers.
Popular MQTT brokers include Mosquitto, HiveMQ, RabbitMQ, and others. MQTT has gained widespread adoption in the Internet of Things (IoT) domain due to its lightweight nature, efficient communication model, and support for various QoS levels
SpaLink App Setup
MQTT – Settings
Details required to setup
💡 Setting up the MQTT broker is outside the scope of this document and we will assume that the customer has setup the server and created a specific user account with password for use with the Wi-Fi module, before continuing.
- Server Address
- Takes the format of mqtt://[ip address]:[port] (port is optional, if omitted the default port is used) e.g. mqtt://192.168.1.
- Username
- Username of the MQTT user setup on the MQTT broker e.g. mqttuser
- Password
- Password of the MQTT user setup on the MQTT broker e.g. mqttpwd
💡 Only basic authentication is currently supported, without the use of encryption certificates. Having encryption is not critical as it is expected that communication will happen on the local network only.
Once MQTT is configured it will attempt to make a connection to the broker and start to publish messages to predefined topics.
Deployment
MQTT ID
We make use of our own MQTT ID for making sure message topics are unique per Wi-Fi module, the number is derived from the Wi-Fi mac address. Here is an example c049ef3ad208. This ID is used as the basis of all topics.
All MQTT topics in this example will begin with spanet/c049ef3ad208/ i.e. [mqtt_id] = c049ef3ad
Diagnostic Topics
spanet/[mqtt_id]/mqtt_id – Outputs the MQTT ID.
spanet/[mqtt_id]/status/
spanet/[mqtt_id]/controller_fault/
spanet/[mqtt_id]/rediscover/
spanet/[mqtt_id]/version/
spanet/[mqtt_id]/type/
Control Topics
Water Heater
spanet/[mqtt_id]/mode/state/
spanet/[mqtt_id]/mode/control/
spanet/[mqtt_id]/water/set/state/
spanet/[mqtt_id]/water/set/control/
spanet/[mqtt_id]/water/temperature/state/
Pumps
spanet/[mqtt_id]/pump/ 1 /availability/
spanet/[mqtt_id]/pump/ 1 /state/
spanet/[mqtt_id]/pump/ 1 /control/
spanet/[mqtt_id]/pump/ 1 /speed/state/
spanet/[mqtt_id]/pump/ 1 /speed/control/
Blower
spanet/[mqtt_id]/blower/availability/
spanet/[mqtt_id]/blower/state/
spanet/[mqtt_id]/blower/control/
spanet/[mqtt_id]/blower/speed/state/
spanet/[mqtt_id]/blower/speed/control/
spanet/[mqtt_id]/blower/mode/state/
spanet/[mqtt_id]/blower/mode/control/
Sensors
Home Assistant
Refer to this document to setup a Home Assistant Green for testing
Home Assistant Setup
About
Home Assistant is an open-source home automation platform that focuses on privacy and local control. It is designed to be an all-in-one solution for managing and automating smart home devices. Home Assistant allows users to integrate and control a wide range of smart devices and services from different manufacturers, providing a unified interface for home automation.
MQTT Auto-Discovery
Home Assistant MQTT auto-discovery is a feature in Home Assistant that simplifies the integration of MQTT-enabled devices into the Home Assistant platform.
It allows Home Assistant to automatically discover and configure devices that support MQTT without manual intervention.
This feature streamlines the process of setting up and managing devices within the Home Assistant ecosystem.
The SV-Wifi-V3.1 makes use of this Home Assistant feature to auto configure various sensors, controls and diagnostics via MQTT. Once MQTT is configured on the Wi-Fi module it will publish the Home Assistant configuration on boot up each time.
Configuration of the MQTT integration in Home Assistant is required. How to do that is outside the scope of this document, but can be found at this link Home Assistant MQTT
A device listing will appear the MQTT devices list for each Wi-Fi module configured on the broker, there can be more than one.
The SV Controller via the Wi-Fi module will now be able to be controlled via Home Assistant as an integrated device, which includes being used in automations.
MQTT Message Flow
MQTT Entities Used
The following Home Assistant entities have been used for spa control
- Climate – for the heat pump
- Water Heater – for the element heater
- Fan – for the blower
- Light – for the lights
- Select – for the pumps, heater mode, light effect speed and keypad lock
- Switch – for sanitise
- Number – for set temperature and variable pump speed
- Binary Sensor – for auto, heating and sleep LED’s
- Sensor – for current water temperature, sanitise time, faults and diagnostic information
Default Panel
Not Running Home Assistant
💡 If you are using Home Assistant then this all gets automatically configured for you if you enable MQTT discovery..
But if you are running some other setup, then manually checking the settings in the topic homeassistant/[device] is the way to find out what commands to send. These are not SV Commands, but the commands we have setup in MQTT. The user does not see that actual commands to the controller.
If you use a tool like MQTT Explorer https://mqtt-explorer.com/ and connect to the MQTT Broker, then all the config is supplied to you in that topic.
Something else to note when not using Home Assistant is clients trying to find state and control topics in this homeassistant topic, which is used for MQTT discovery MQTT – Home Assistant
You have to look for a topic that starts with spanet/[unique_id] for the actual states and control.
See this screenshot showing an example.
