Third-Party Integrations (Home Assistant)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The swimctl system is designed as a swimming pool automation controller that leverages Node-RED as its primary logic engine. While the core control logic resides within Node-RED, the architecture supports third-party integrations—most notably with Home Assistant ecosystem components—through standardized communication protocols such as MQTT and mDNS.
The integration strategy focuses on exposing the pool controller's services and endpoints to the local network, allowing external home automation platforms to discover and interact with the pool hardware. This is achieved through a combination of Kubernetes-native networking, specialized device management, and secure credential handling.
Sources: README.md:1-5, values.yml:1-10
Communication Protocols
The system utilizes two primary methods for integrating with third-party platforms like Home Assistant: MQTT for messaging and mDNS for service discovery.
MQTT Connectivity
The controller is configured to interact with an MQTT broker, which is the standard protocol for Home Assistant integrations. Credentials for the MQTT broker are managed via Kubernetes secrets and injected into the Node-RED environment.
| Variable | Description | Source |
|---|---|---|
MQTT_PASSWORD | Secure password for MQTT broker authentication | values.yml:68-73 |
swimctl Secret | Generic secret containing mqtt_password | README.md:46-51 |
Sources: README.md:46-51, values.yml:68-73
Service Discovery via mDNS
To facilitate seamless integration without manual IP configuration, the system deploys external-mdns. This component allows third-party systems on the local network to discover the swimctl services.
The external-mdns deployment uses the host network to broadcast service availability to the local network, specifically targeting resources defined by Ingress and Service manifests.
Sources: external-mdns.yaml:47-65, values.yml:76-81
Hardware and Device Integration
For third-party systems to monitor or control physical pool hardware, swimctl provides a structured way to expose I2C devices from the host Raspberry Pi into the containerized environment.
I2C Device Management
The smarter-device-manager is utilized to map physical I2C buses to the automation engine. This allows the logic layer to interface with sensors or actuators that might be reflected in a Home Assistant dashboard.
| Resource Name | Mapping | Purpose |
|---|---|---|
smarter-devices/i2c-1 | Physical I2C Bus 1 | Hardware Communication |
smarter-devices/i2c-20 | Virtual/Additional Bus | Extended Hardware Support |
smarter-devices/i2c-21 | Virtual/Additional Bus | Extended Hardware Support |
Sources: values.yml:9-17, configMaps.yaml:7-9
Security and Permissions
To ensure the automation engine can communicate with these devices, specific security contexts and group memberships are applied. The system uses GID 994 for I2C group membership to grant the necessary permissions.
Sources: values.yml:20-27, smarter-device-manager.yaml:38-44
External Service Exposure
The primary interface for third-party tools is provided through a defined Ingress, which establishes a local hostname.
ingress:
enabled: true
hosts:
- host: swimctl.local
paths:
- path: /
pathType: ImplementationSpecific
Sources: values.yml:76-83
Data Flow for External Updates
The system includes a Git-based workflow for updating its logic (flows). When a commit is made to the logic repository, a post-commit hook can trigger external actions, which could be extended to notify Home Assistant or other CI/CD pipelines.
Sources: values.yml:94-131, configMaps.yaml:29-37
Summary
Integration with third-party systems like Home Assistant is achieved in swimctl through a decoupled architecture. By leveraging external-mdns for discovery, MQTT for state messaging, and standardized Ingress for API access, the controller functions as a transparent node within a broader home automation ecosystem. The use of smarter-device-manager ensures that the physical pool hardware remains accessible to the containerized logic that serves these external integrations.