Introduction to Swimctl

Swimctl is a swimming pool automation controller designed to run on a Raspberry Pi infrastructure. It leverages container orchestration via k3s to manage pool-related logic, hardware interfaces, and network services. The system primarily uses Node-RED for flow-based automation and utilizes specialized device management to interact with physical hardware.

The platform is built to be deployed as a set of Kubernetes manifests and Helm charts, providing a cloud-native approach to home automation. It integrates with GitHub for flow management and utilizes mDNS for local service discovery, ensuring that the controller is easily accessible within a local network environment.
Sources: README.md:1-5, values.yml:2-10

System Architecture

The Swimctl architecture is composed of several layers: the physical hardware (Raspberry Pi), the orchestration layer (k3s), and the application layer (Node-RED). The system relies on specific kernel configurations and device managers to bridge the gap between containers and physical I2C sensors or controllers.

Core Components

The following diagram illustrates the high-level relationship between these components:

Hardware Integration and Device Management

Swimctl requires direct access to the Raspberry Pi's I2C bus to interface with pool hardware. This is achieved through a combination of host-level configuration and the Smarter Device Manager.

Host Preparation

Before deployment, the host must have cgroups enabled for memory management and the I2C interface activated via raspi-config.
Sources: README.md:7-18

I2C Resource Allocation

The system uses the smarter-device-manager to discover and expose I2C character devices to the Kubernetes pods. The configuration specifically targets devices matching the pattern ^i2c-[0-9]+$.
Sources: configMaps.yaml:8-10, smarter-device-manager.yaml:65-75

Specific resource limits are defined in the application deployment to ensure exclusive or controlled access to the I2C buses:

• smarter-devices/i2c-1
• smarter-devices/i2c-20
• smarter-devices/i2c-21
  Sources: values.yml:8-16

Automation Engine (Node-RED)

Node-RED serves as the central logic processor. It is configured to run with a specific project named swimctl-flows.

Git Integration and Synchronization

The system employs an initContainer to clone the automation flows from a GitHub repository during startup. It also configures a post-commit hook that triggers a GitHub Action to apply patches back to the repository when changes are made within the Node-RED UI.

Configuration Environment

Key environment variables manage the Node-RED environment and its connection to external services:

• NODE_RED_ACTIVE_PROJECT: Set to swimctl-flows.
• MQTT_PASSWORD: Retreived from a Kubernetes secret for messaging.
• GITHUB_TOKEN_FLOWS: Used for the post-commit synchronization logic.
  Sources: values.yml:45-75

Networking and Security

Swimctl uses an Ingress controller and external-mdns to make the service reachable on the local network at http://swimctl.local.

Security Context

The application runs with specific security constraints:

• UID/GID: 1000
• Supplemental Groups: 994 (i2c group membership) to allow the containerized process to read/write to the mapped device files.
  Sources: values.yml:25-35

Namespaces

The system utilizes dedicated namespaces for organization:

• default: Typically used for the main application.
• device-manager: Used for hardware interface components.
• kube-system: Used for mDNS and network services.
  Sources: 00-namespaces.yaml:1-6, external-mdns.yaml:2, smarter-device-manager.yaml:5

Deployment Summary

To deploy Swimctl, the user follows a structured workflow involving host setup, secret creation, and manifest application.

The use of Helm with values.yml allows for flexible configuration of the container image (retrieved from ghcr.io/bgshacklett/swimctl) and persistent volume mounts for Node-RED data and project settings.
Sources: values.yml:2-6, values.yml:120-125