Hardware Requirements & Setup
Relevant source files
The following files were used as context for generating this wiki page:
The swimctl project is a swimming pool automation controller designed to run on Raspberry Pi hardware within a Kubernetes environment (specifically k3s). The setup involves configuring the underlying operating system to support containerized hardware access, deploying a device manager to expose physical interfaces to pods, and establishing networking and secret management for the application.
The hardware interface is primarily focused on I2C communication, which allows the software to interact with external pool equipment sensors and controllers.
Host Preparation
Before deploying the swimctl application, the Raspberry Pi host must be configured to support Kubernetes resource constraints and hardware bus communication.
Operating System Configuration
The project requires Linux control groups (cgroups) to be enabled for memory management and the I2C interface to be active.
- Enable Cgroups: The
/boot/firmware/cmdline.txtfile must be modified to includecgroup_memory=1andcgroup_enable=memory. - Enable I2C: The I2C interface is enabled using the non-interactive
raspi-configtool.
Sources: README.md:7-17
Kubernetes Installation
The system is built on k3s, installed via k3sup. The installation targets a specific hostname and merges the resulting configuration into the local user's kubeconfig.
k3sup install \
--host "${hostname}" \
--user pi \
--context "${hostname}" \
--merge \
--local-path ~/.kube/config
Sources: README.md:21-31
Hardware Device Management
Access to physical hardware (I2C buses) within the Kubernetes cluster is facilitated by the smarter-device-manager. This component runs as a DaemonSet and maps host devices into container namespaces.
Device Manager Architecture
The smarter-device-manager monitors the host's /dev directory and exports identified devices as allocatable resources.
The diagram shows how physical I2C devices are mapped from the host to the Node-RED pod through the device manager.
Sources: smarter-device-manager.yaml:1-68, values.yml:10-18
Hardware Configuration Specs
The project explicitly defines which I2C buses are expected and managed.
| Resource Name | Purpose | Configuration Source |
|---|---|---|
smarter-devices/i2c-1 | Standard I2C Bus | values.yml:11 |
smarter-devices/i2c-20 | Extended I2C Bus | values.yml:12 |
smarter-devices/i2c-21 | Extended I2C Bus | values.yml:13 |
devicematch: ^i2c-[0-9]+$ | Regex for device discovery | configMaps.yaml:9 |
Permissions and Security Context
To interact with hardware, the application pods require specific security configurations and group memberships.
- User/Group IDs: Pods run with UID 1000 and GID 1000.
- I2C Access: The pod is assigned to supplemental group
994, which corresponds to the I2C group on the host OS. - Volume Permissions: An
fsGroupof 1000 is used for volume permissions.
Sources: values.yml:21-27
Network and Service Discovery
The system uses mDNS for local service discovery, allowing the controller to be reached via a .local hostname without complex DNS infrastructure.
external-mdns
A deployment of external-mdns runs with hostNetwork: true to broadcast service and ingress information on the local network. This enables the swimctl.local ingress host defined in the configuration.
Interaction between the Ingress controller and the mDNS responder for local name resolution.
Sources: external-mdns.yaml:45-64, values.yml:78-83
Software and Secret Setup
Once the hardware and cluster are ready, the application secrets must be provisioned.
Secret Requirements
The following secrets are required for the system to function, specifically for GitHub integration (fetching flows) and MQTT communication:
gh_token: GitHub Personal Access Token.gh_owner: GitHub repository owner.gh_repo_name: Name of the repository containing Node-RED flows.mqtt_password: Password for the MQTT broker.
Sources: README.md:36-42, values.yml:43-69
Summary
The setup of swimctl transforms a standard Raspberry Pi into a specialized automation gateway. By enabling cgroups and I2C at the OS level, and utilizing the smarter-device-manager within k3s, the system provides containerized applications with reliable, secure access to the physical hardware buses required for pool control. mDNS integration ensures that the hardware remains accessible on the local network via swimctl.local.