Raspberry Pi Preparation
Relevant source files
The following files were used as context for generating this wiki page:
The preparation of the Raspberry Pi is a foundational step in deploying the swimctl swimming pool automation system. This process ensures that the underlying hardware is correctly configured to support containerized workloads and hardware-level communication required for pool equipment control.
The preparation scope includes enabling specific Linux kernel features for memory management, activating the I2C bus for peripheral communication, and establishing the Kubernetes environment (k3s) necessary to orchestrate the system's microservices.
OS Level Configuration
Before installing the orchestration layer, the Raspberry Pi OS must be modified to support Kubernetes resource limits and hardware interfacing.
Control Groups (cgroups)
Kubernetes requires cgroups to manage and isolate resource usage. Specifically, memory cgroups must be explicitly enabled in the boot configuration to allow the kubelet to track memory usage accurately. This is achieved by appending cgroup_memory=1 cgroup_enable=memory to the /boot/firmware/cmdline.txt file.
Sources: README.md:9-15
I2C Interface Activation
Since swimctl interacts with hardware devices via the I2C protocol, the interface must be enabled at the system level. This is performed using the raspi-config non-interactive interface, ensuring the /dev/i2c-* device nodes are available for the container runtime.
Sources: README.md:19-21
| Action | Command / Configuration | Purpose |
|---|---|---|
| Enable cgroups | cgroup_memory=1 cgroup_enable=memory | Enable memory resource tracking and limits |
| Enable I2C | sudo raspi-config nonint do_i2c 0 | Activate hardware I2C bus for peripheral communication |
Sources: README.md:9-21
Cluster Deployment and Security
Once the hardware is prepared, the node is integrated into a Kubernetes cluster and configured with the necessary credentials.
K3s Installation
The project utilizes k3sup (ketchup) for a streamlined installation of k3s over SSH. This process configures the Pi as a Kubernetes node and merges the resulting configuration into the local ~/.kube/config.
Sources: README.md:25-36
Secrets Management
A Kubernetes secret named swimctl must be created to store sensitive integration tokens and credentials. These secrets are later injected into the Node-RED environment as environment variables.
Sources: README.md:39-45, values.yml:45-72
The diagram above illustrates the sequential steps required to move from a fresh Raspberry Pi OS install to a ready-to-deploy swimctl node.
Sources: README.md:9-48
Hardware Device Mapping
To allow containers to access I2C hardware, the system employs the smarter-device-manager. This component runs as a DaemonSet and maps physical device nodes into the Kubernetes resource manifest.
Smarter Device Manager
The device manager monitors /dev on the host and exposes devices matching specific patterns (e.g., ^i2c-[0-9]+$) as allocatable resources.
Sources: configMaps.yaml:1-10, smarter-device-manager.yaml:1-74
Resource Requests
Workloads such as Node-RED request access to these devices via the resources section of their pod specification. The swimctl configuration specifically targets I2C buses 1, 20, and 21.
Sources: values.yml:9-18
| Resource Name | Host Device Path | Usage |
|---|---|---|
smarter-devices/i2c-1 | /dev/i2c-1 | Primary I2C Bus |
smarter-devices/i2c-20 | /dev/i2c-20 | Secondary/Virtual Bus |
smarter-devices/i2c-21 | /dev/i2c-21 | Secondary/Virtual Bus |
Sources: values.yml:10-18, configMaps.yaml:8-9
Network and Access Control
Proper preparation includes setting up the networking environment to ensure the Pi is discoverable and that processes have the correct permissions.
mDNS and Ingress
The external-mdns service is deployed to the kube-system namespace. It allows the cluster to broadcast its services and ingresses (like swimctl.local) via Multicast DNS, enabling local network discovery without a dedicated DNS server.
Sources: external-mdns.yaml:1-60, values.yml:75-81
User and Group Permissions
The containers are configured to run with specific UID/GID (1000) and are added to supplemental group 994. This group membership is critical for providing the containerized process permission to read/write to the I2C character devices.
Sources: values.yml:21-30
This sequence shows how the prepared hardware is exposed through the Kubernetes layer to the application.
Sources: smarter-device-manager.yaml:50-70, values.yml:9-30, configMaps.yaml:1-10
Conclusion
Preparing the Raspberry Pi for swimctl involves a transition from standard OS configuration to a specialized hardware-aware Kubernetes node. By enabling cgroups, configuring the I2C bus, and deploying the smarter-device-manager, the system ensures that the automation software has reliable and secure access to the physical interfaces required for pool control.