Node-RED Automation Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Node-RED Automation Engine serves as the central control logic for the swimctl swimming pool automation system. It is deployed as a containerized application within a Kubernetes (k3s) cluster, typically running on Raspberry Pi hardware. The engine leverages Node-RED's flow-based programming to manage hardware interfaces, process automation logic, and provide a user interface for pool management.
The engine integrates closely with physical hardware via I2C interfaces and utilizes a Git-based workflow for synchronizing automation flows. External access is facilitated through Kubernetes Ingress and mDNS for local network discovery.
Sources: README.md:1-5, values.yml:1-10, external-mdns.yaml:1-5
Deployment Architecture
The automation engine is deployed using Helm onto a k3s cluster. It utilizes a specific security context to allow interaction with hardware groups and manages data persistence through volume mounts.
Resource and Security Configuration
The deployment specifies resource limits and requests for specialized hardware devices, specifically I2C buses used for peripheral communication. The pod runs under a specific non-root user and group (UID/GID 1000) but includes supplemental group 994 to grant necessary permissions for I2C access.
The diagram illustrates the path from external ingress through the Kubernetes pod to the physical I2C hardware devices.
Sources: values.yml:8-25, values.yml:71-77, README.md:27-35
Hardware Device Management
Hardware access is managed by the smarter-device-manager, which runs as a DaemonSet in the device-manager namespace. It detects and exposes I2C devices to the Kubernetes scheduler, allowing the Node-RED pod to request them as resources.
| Device Resource | Configuration Match | Max Devices |
|---|---|---|
smarter-devices/i2c-1 | ^i2c-[0-9]+$ | 1 |
smarter-devices/i2c-20 | ^i2c-[0-9]+$ | 1 |
smarter-devices/i2c-21 | ^i2c-[0-9]+$ | 1 |
Sources: smarter-device-manager.yaml:7-15, configMaps.yaml:8-11, values.yml:8-16
Configuration and Project Management
Node-RED is configured to use a "Projects" workflow, where flows are treated as version-controlled repositories.
Environment Variables
The system uses environment variables to define the active project and provide credentials for external services like GitHub and MQTT.
| Variable | Source | Purpose |
|---|---|---|
NODE_RED_ENABLE_PROJECTS | Literal ('true') | Enables the Project feature in Node-RED |
NODE_RED_ACTIVE_PROJECT | Literal ('swimctl-flows') | Sets the default active project name |
GITHUB_TOKEN_FLOWS | Secret (swimctl:gh_token) | Auth token for GitHub API interactions |
MQTT_PASSWORD | Secret (swimctl:mqtt_password) | Credentials for the MQTT broker |
Sources: values.yml:33-65, configMaps.yaml:18-25
Git Integration and Synchronization
An init container is used to clone the automation flows from a remote repository (swimctl-flows.git) before the main Node-RED container starts. Furthermore, a post-commit hook is automatically created to trigger a GitHub Action whenever changes are made within the Node-RED editor, ensuring bidirectional synchronization.
This sequence shows the automated synchronization of flows from the local editor back to the remote GitHub repository.
Sources: values.yml:95-128, configMaps.yaml:35-46
Network and Connectivity
The engine is accessible within the local network via the swimctl.local hostname.
Ingress and mDNS
Local network discovery is handled by the external-mdns service, which watches Kubernetes Ingress resources and broadcasts them via mDNS. This allows users to access the Node-RED interface without needing to know the specific IP address of the Raspberry Pi.
- Host:
swimctl.local - Path:
/ - mDNS Source: Ingress and Service resources
Sources: values.yml:71-77, external-mdns.yaml:49-59
System Settings Implementation
Custom settings are injected via a ConfigMap named node-red-settings. This configuration merges default Node-RED settings with environment-specific overrides, such as the activeProject variable.
const defaults = require("/usr/src/node-red/node_modules/node-red/settings");
const customSettings = {
activeProject: process.env.NODE_RED_ACTIVE_PROJECT || null,
}
module.exports = Object.assign({}, defaults, customSettings);
Sources: configMaps.yaml:18-30, values.yml:81-83
Summary
The Node-RED Automation Engine in swimctl provides a robust, containerized environment for pool control. By combining Kubernetes orchestration with Node-RED's flexible flow logic, Git-based versioning, and direct hardware access via the smarter-device-manager, the system achieves a highly maintainable and scalable automation platform tailored for edge hardware like the Raspberry Pi.