Extending Node-RED Flows
Relevant source files
The following files were used as context for generating this wiki page:
The swimctl project leverages Node-RED as its core automation engine for swimming pool control. Extending Node-RED flows within this environment involves a git-centric workflow where flows are managed as version-controlled projects, automatically synchronized from external repositories, and integrated with physical hardware interfaces via Kubernetes-managed device plugins.
The system is designed to be highly modular, using Kubernetes ConfigMaps for settings and Git-based synchronization for flow persistence. This allows developers to extend functionality by updating the swimctl-flows repository, which the controller automatically pulls and integrates into the running environment.
Sources: README.md:1-5, values.yml:45-50, configMaps.yaml:31-42
Flow Management and Git Integration
The architecture utilizes the Node-RED "Projects" feature to manage flows. Flows are not stored locally within the container's ephemeral storage but are instead treated as a Git repository.
Initial Provisioning
At startup, an initContainer named clone-repo handles the initial setup of the flow environment. It clones the specific flows repository and checks out the designated version.
The diagram shows the sequence of events performed by the initialization container to ensure the latest flows are available before the main application starts.
Sources: values.yml:95-132
Automated Synchronization (Post-Commit)
To support a seamless development experience, the system installs a Git post-commit hook. This hook automatically triggers a GitHub Action workflow (apply-patch.yml) whenever a commit is made within the Node-RED editor, sending a base64-encoded patch of the changes back to the source repository.
Sources: values.yml:118-132
Configuration and Project Settings
Node-RED's behavior is extended and modified through a series of Kubernetes ConfigMaps. These configurations enable the project's feature and set the active workspace.
| Component | Configuration File | Purpose |
|---|---|---|
| Settings Merge | settings.js | Merges custom settings like activeProject with default Node-RED settings. |
| Project Config | .config.projects.json | Explicitly defines the swimctl-flows project and disables credential secrets. |
| Environment | values.yml | Sets NODE_RED_ENABLE_PROJECTS to true. |
Sources: configMaps.yaml:13-42, values.yml:45-49
Project Metadata Configuration
The project structure is defined in a JSON configuration mounted as a subpath to the Node-RED data directory.
{
"projects": {
"swimctl-flows": {
"credentialSecret": false
}
},
"activeProject": "swimctl-flows"
}
Sources: configMaps.yaml:34-42, values.yml:87-89
Hardware Extension via I2C
Extending flows often requires interacting with physical pool hardware. The project uses the smarter-device-manager to expose I2C interfaces from the Raspberry Pi host to the Node-RED container.
Device Mapping
The smarter-device-manager ConfigMap defines which host devices are available. Node-RED then requests these specific resources via its deployment specification.
| Resource Name | Host Device Match | Max Devices |
|---|---|---|
smarter-devices/i2c-1 | ^i2c-[0-9]+$ | 1 |
smarter-devices/i2c-20 | N/A | 1 |
smarter-devices/i2c-21 | N/A | 1 |
Sources: configMaps.yaml:6-10, values.yml:10-20, smarter-device-manager.yaml:1-10
Security Context
To interact with these devices, the Node-RED pod is configured with specific group memberships, notably the i2c group (GID 994).
Sources: values.yml:23-30
External Communication and Discovery
For extending flows that interact with other local network services, the system deploys an external-mdns service.
This diagram illustrates how the external-mdns deployment allows Node-RED services to be discoverable on the local network via standard mDNS/ZeroConf.
Sources: external-mdns.yaml:45-63, values.yml:76-81
mDNS Capabilities
The external-mdns service account is granted cluster-wide permissions to watch ingresses and services, allowing it to dynamically broadcast hostnames like swimctl.local to the local network.
Sources: external-mdns.yaml:13-35
Summary of Flow Extension Workflow
- Develop: Use the Node-RED UI (accessible via
swimctl.local) to modify or create new flows. - Commit: Commit changes within the Node-RED Project UI.
- Sync: The
post-commithook pushes changes to theswimctl-flowsrepository via GitHub API dispatches. - Deploy: On the next pod restart, or via manual intervention, the
initContainerpulls the latest code from Git. - Interact: Use defined I2C resources (
i2c-1, etc.) within flows to control pool hardware.
Sources: values.yml:100-132, README.md:65-75