MQTT Messaging Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The MQTT Messaging Integration within the swimctl project provides the communication layer for swimming pool automation. This integration is primarily managed through Node-RED, which acts as the central logic engine, and is supported by a Kubernetes-based infrastructure on Raspberry Pi. The system leverages MQTT to facilitate data exchange between pool sensors, controllers, and the automation interface.
The integration relies on secrets for secure communication and is configured to work within a containerized environment. It connects the high-level flow logic defined in Node-RED with the physical hardware (I2C devices) and external services, ensuring that pool states are monitored and controlled efficiently.
Sources: README.md, values.yml:45-73
Architecture and Configuration
The MQTT messaging system is part of a larger deployment strategy involving Helm and Kubernetes (k3s). The messaging logic is encapsulated within Node-RED flows which are synchronized from a dedicated GitHub repository.
Infrastructure Components
The following diagram illustrates how the messaging components interact within the Kubernetes cluster to facilitate MQTT communication and device control.
The Node-RED pod consumes an MQTT_PASSWORD from a Kubernetes secret named swimctl. This password is used by the flows to authenticate with the MQTT broker.
Sources: README.md:37-44, values.yml:68-73, configMaps.yaml:14-25
Secret Management
MQTT credentials and GitHub integration tokens are stored as Kubernetes secrets. These are injected into the Node-RED environment as environment variables.
| Environment Variable | Source Secret Key | Purpose |
|---|---|---|
MQTT_PASSWORD | mqtt_password | Authentication for the MQTT broker |
GITHUB_TOKEN_FLOWS | gh_token | Access to the flows repository |
GITHUB_OWNER_FLOWS | gh_owner | GitHub organization/user for the repo |
GITHUB_REPO_NAME_FLOWS | gh_repo_name | Name of the repository containing flows |
Sources: values.yml:48-73, README.md:37-44
Node-RED Integration
Node-RED serves as the primary consumer and producer of MQTT messages. It is configured to run projects specifically for pool control.
Flow Management and Synchronization
The system uses an init container to clone the swimctl-flows repository before the main Node-RED container starts. This ensures that the MQTT-enabled flows are always up to date with the main branch of the repository.
Sources: values.yml:92-132, configMaps.yaml:31-41
Messaging Settings
The Node-RED settings are customized via a ConfigMap to enable project support, which is critical for managing version-controlled MQTT flows.
- Active Project:
swimctl-flows - Credential Secret: Disabled in projects config to allow repository-based management.
Sources: configMaps.yaml:17-29, configMaps.yaml:33-41
Hardware and Network Interaction
While MQTT provides the messaging layer, the system interacts with physical hardware via I2C, managed by the smarter-device-manager. This allows Node-RED to translate MQTT messages into physical actions (like turning on a pump) or sensor readings into MQTT messages.
Device Mapping
The smarter-device-manager maps host I2C devices into the container, allowing the messaging logic to access hardware:
^i2c-[0-9]+$devices are matched and exposed.- Node-RED requests specific resources such as
smarter-devices/i2c-1,i2c-20, andi2c-21.
Sources: configMaps.yaml:6-8, values.yml:10-20, smarter-device-manager.yaml:1-73
Network Discovery
To facilitate communication, external-mdns is deployed to provide mDNS/Bonjour service discovery. This ensures that the swimctl.local address (defined in the Ingress) and potentially the MQTT broker can be resolved within the local network without static IP configurations.
Sources: external-mdns.yaml:1-62, values.yml:78-82
Summary
The MQTT Messaging Integration in swimctl is a robust system that bridges cloud-hosted logic (GitHub) with local hardware (Raspberry Pi I2C). By utilizing Node-RED as a message processor and Kubernetes for secret management and device orchestration, the system provides a secure and scalable way to automate swimming pool functions via MQTT.