System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The swimctl system is a swimming pool automation controller designed to run on a Raspberry Pi-based Kubernetes cluster (k3s). It leverages Node-RED as its core logic engine to manage hardware interfaces and pool automation flows. The architecture focuses on containerized deployment, hardware device management via I2C, and automated configuration synchronization with remote repositories.
Sources: README.md:1-5, values.yml:1-5
Core Infrastructure
The system is deployed on a Raspberry Pi using k3s, a lightweight Kubernetes distribution. The host environment requires specific configurations, including enabling cgroups and I2C interfaces, to support containerized hardware access.
Sources: README.md:7-21
Kubernetes Components and Namespaces
The architecture utilizes multiple namespaces to isolate system management from application logic.
| Component | Description | Namespace |
|---|---|---|
| Node-RED | The primary automation engine and UI. | default (via Helm) |
| Smarter Device Manager | Manages hardware device exposure to containers. | device-manager |
| External mDNS | Provides service discovery for the local network. | kube-system |
Sources: 00-namespaces.yaml:1-6, external-mdns.yaml:4-6, smarter-device-manager.yaml:4-6
Hardware Interface and Device Management
Hardware interaction is facilitated through the I2C protocol. To allow Kubernetes pods to interact with physical I2C buses, the system employs the smarter-device-manager.
Smarter Device Manager
This component runs as a DaemonSet and monitors the host's /dev directory to export I2C devices as Kubernetes resources. It identifies devices matching the pattern ^i2c-[0-9]+$ and makes them available for request in pod resource limits.
Sources: configMaps.yaml:6-9, smarter-device-manager.yaml:1-12
Resource Allocation
The Node-RED deployment requests specific I2C buses (i2c-1, i2c-20, and i2c-21) to interact with pool hardware.
The diagram above illustrates how physical I2C hardware is mapped through the Smarter Device Manager to the Node-RED application pod.
Sources: values.yml:8-16, smarter-device-manager.yaml:57-73
Application Logic: Node-RED
Node-RED serves as the automation hub. It is configured to run with "Projects" mode enabled, allowing version-controlled flow management.
Configuration and Persistence
Node-RED settings are managed via ConfigMaps that define settings.js and project metadata. The system is configured to automatically load the swimctl-flows project.
| Parameter | Value | Source |
|---|---|---|
NODE_RED_ENABLE_PROJECTS | true | values.yml:32-33 |
NODE_RED_ACTIVE_PROJECT | swimctl-flows | values.yml:35-36 |
Credential Secret | false | configMaps.yaml:42-43 |
CI/CD and Flow Synchronization
The system implements an automated synchronization mechanism using an init container. Upon startup, the container clones the flow repository and installs a post-commit git hook. This hook triggers a GitHub Action to apply patches whenever flows are modified within the Node-RED UI.
Sources: values.yml:68-107
Networking and Service Discovery
The system provides local network access through an Ingress controller and mDNS broadcasting.
External mDNS
The external-mdns service watches Kubernetes Ingresses and Services to broadcast their hostnames over mDNS. This allows the user to access the pool controller at swimctl.local without manual DNS configuration.
Sources: external-mdns.yaml:55-73, values.yml:55-58
Security and Secrets
Sensitive information, including GitHub tokens and MQTT passwords, is managed through Kubernetes Secrets and injected into the Node-RED environment as variables.
| Environment Variable | Secret Key Reference |
|---|---|
GITHUB_TOKEN_FLOWS | swimctl:gh_token |
GITHUB_OWNER_FLOWS | swimctl:gh_owner |
GITHUB_REPO_NAME_FLOWS | swimctl:gh_repo_name |
MQTT_PASSWORD | swimctl:mqtt_password |
Sources: values.yml:38-60, README.md:38-44
Conclusion
The swimctl architecture provides a robust environment for pool automation by combining standard IoT hardware (Raspberry Pi/I2C) with modern DevOps practices (k3s/GitOps). The use of Smarter Device Manager ensures clean hardware abstraction, while the Node-RED project integration allows for seamless flow updates and versioning.