Pool Controller Dashboard
Relevant source files
The following files were used as context for generating this wiki page:
The Pool Controller Dashboard is a swimming pool automation system built on a Kubernetes (k3s) infrastructure, specifically optimized for Raspberry Pi hardware. It leverages Node-RED as its core logic and visualization engine to manage pool operations through automated flows.
The system integrates hardware-level device management via I2C interfaces with high-level automation flows. It utilizes a GitOps-style synchronization for automation logic and provides local network accessibility through mDNS and Ingress controllers.
Sources: README.md:1-3, values.yml:100-110
Infrastructure and Deployment Architecture
The dashboard and controller are deployed as a containerized application within a Kubernetes cluster. The environment is partitioned using namespaces, with hardware management residing in the device-manager namespace and networking components in kube-system.
The diagram above illustrates the relationship between the different namespaces and core components within the cluster.
Sources: 00-namespaces.yaml:1-6, smarter-device-manager.yaml:4-10, external-mdns.yaml:44-50
Hardware Resource Management
The system uses the Smarter Device Manager to expose Raspberry Pi I2C devices to the Kubernetes pods. This allows the dashboard logic to interact directly with hardware sensors and controllers.
| Device Name | Description | Configuration |
|---|---|---|
i2c-1 | Primary I2C Bus | Requested and limited to 1 instance |
i2c-20 | Secondary I2C Bus | Requested and limited to 1 instance |
i2c-21 | Tertiary I2C Bus | Requested and limited to 1 instance |
Sources: values.yml:8-17, configMaps.yaml:8-10
Automation Engine (Node-RED)
The core logic of the dashboard is driven by Node-RED, which is configured to run specifically for the swimctl project.
Flow Management and Git Integration
Automation logic is managed through a Git-based workflow. An initContainer clones the automation flows from a remote repository before the main dashboard starts.
This sequence shows how the dashboard logic is retrieved and prepared during the pod lifecycle.
Sources: values.yml:102-132, configMaps.yaml:31-38
Environment Configuration
The dashboard requires several environment variables and secrets to operate and synchronize state.
| Environment Variable | Source (Secret Key) | Purpose |
|---|---|---|
NODE_RED_ACTIVE_PROJECT | Static (swimctl-flows) | Sets the default active project in Node-RED |
GITHUB_TOKEN_FLOWS | gh_token | Authentication for GitHub API operations |
GITHUB_OWNER_FLOWS | gh_owner | Owner of the flows repository |
GITHUB_REPO_NAME_FLOWS | gh_repo_name | Name of the flows repository |
MQTT_PASSWORD | mqtt_password | Credentials for MQTT communication |
Sources: values.yml:43-77, README.md:46-52
Networking and Access
The dashboard is accessible on the local network via the hostname swimctl.local. This is facilitated by two primary components:
- Ingress Controller: Routes HTTP traffic from
swimctl.localto the Node-RED service. - External mDNS: A service that monitors Kubernetes Ingresses and Services to broadcast their presence on the local network using Multicast DNS.
The diagram describes how a user on the local network discovers and connects to the dashboard.
Sources: values.yml:82-90, external-mdns.yaml:70-75
Security and Permissions
The dashboard runs with specific security contexts to ensure it has the necessary permissions to access hardware while maintaining standard container security. It operates under UID 1000 and requires membership in supplemental group 994 to access I2C devices.
Sources: values.yml:20-27
Conclusion
The Pool Controller Dashboard is a hardware-integrated automation platform that combines the flexibility of Node-RED with the robustness of Kubernetes. By treating automation flows as code (stored in Git) and hardware as managed cluster resources, it provides a scalable and maintainable solution for pool management.