I2C Hardware Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The I2C Hardware Integration in the swimctl project enables the swimming pool automation controller to interact with physical hardware sensors and actuators via the Inter-Integrated Circuit (I2C) protocol. This integration is designed to run within a containerized Kubernetes environment (specifically k3s) on Raspberry Pi hardware, utilizing a specialized device manager to bridge the gap between host hardware and isolated containers.
Sources: README.md:1-5, values.yml:6-12
The architecture relies on the smarter-device-manager to expose host /dev/i2c-* nodes as requestable resources within the Kubernetes cluster. This allows the core automation logic, implemented via Node-RED, to access specific I2C buses with appropriate permissions and resource guarantees.
Sources: smarter-device-manager.yaml:1-10, values.yml:15-26
Architecture and Device Management
Hardware Enablement
Before the software stack can interact with I2C devices, the Raspberry Pi hardware must be configured to enable the I2C interface. This is performed using the raspi-config non-interactive tool.
Sources: README.md:16-18
Smarter Device Manager
The project utilizes the smarter-device-manager deployed as a DaemonSet in the device-manager namespace. It monitors the host's /dev directory and registers I2C devices as Kubernetes resources.
The diagram shows how the Smarter Device Manager discovers host I2C devices and makes them available to the application pods.
Sources: smarter-device-manager.yaml:7-60, 00-namespaces.yaml:1-6
Device Configuration
The device manager is configured via a ConfigMap to match specific I2C device patterns. It uses a regular expression to identify devices and limits the maximum number of devices that can be allocated to a single consumer.
| Configuration Parameter | Value | Description |
|---|---|---|
devicematch | ^i2c-[0-9]+$ | Regex to match I2C device nodes in /dev |
nummaxdevices | 1 | Max number of instances per resource type |
Sources: configMaps.yaml:1-10
Resource Allocation and Security
Pod Resource Limits
The application pod explicitly requests specific I2C buses as extended resources. This ensures that the scheduler places pods only on nodes with available I2C hardware and provides exclusive access to the specified bus.
Sources: values.yml:6-14
Security Context and Permissions
To interact with I2C hardware, the application pod must run with specific group memberships. The swimctl deployment configures a podSecurityContext that includes GID 994, which corresponds to the I2C group on the host system.
| Context Field | Value | Purpose |
|---|---|---|
runAsUser | 1000 | Standard user UID |
runAsGroup | 1000 | Standard group GID |
supplementalGroups | [994] | Grants access to I2C device nodes |
Sources: values.yml:17-23
Deployment Logic
Hardware Access Flow
The following sequence illustrates the lifecycle of an I2C request from deployment to hardware access:
Sequence of events enabling containerized access to the physical I2C bus.
Sources: values.yml:6-14, values.yml:21-23, smarter-device-manager.yaml:50-55
Configured I2C Resources
The system is configured to handle multiple I2C buses, as defined in the resource requests and limits:
smarter-devices/i2c-1smarter-devices/i2c-20smarter-devices/i2c-21
Sources: values.yml:8-14
Summary
The I2C Hardware Integration in swimctl provides a robust method for accessing low-level hardware within a Kubernetes cluster. By leveraging smarter-device-manager, the system treats I2C buses as first-class Kubernetes resources. Combined with specific security context configurations (GID 994) and hardware-level enablement via raspi-config, the Node-RED based automation system can reliably control pool hardware through standard I2C interfaces.
Sources: README.md:16-18, values.yml:8-23, smarter-device-manager.yaml:45-60