Adding Additional Hardware Devices
Relevant source files
The following files were used as context for generating this wiki page:
This document describes the process and architecture for integrating additional hardware devices into the swimctl automation system. The system primarily utilizes the Smarter Device Manager to expose host-level hardware—specifically I2C devices—to containerized workloads running within a Kubernetes cluster.
Hardware integration involves configuring host-level permissions, defining device matching patterns in the device manager configuration, and requesting specific hardware resources within the application deployment.
Sources: README.md:1-25, smarter-device-manager.yaml:1-10
Hardware Management Architecture
The architecture relies on a specialized DaemonSet that manages hardware access across the cluster nodes. It maps physical device paths from the host's /dev directory into a format that Kubernetes can schedule as requested resources.
Component Interaction Flow
The following diagram illustrates how hardware devices are discovered and made available to the application containers.
The Smarter Device Manager monitors host devices based on regex patterns defined in a ConfigMap and registers them as schedulable resources with the Kubelet.
Sources: smarter-device-manager.yaml:49-65, configMaps.yaml:8-12
Device Discovery Configuration
To add a new hardware device, it must first be identified by the smarter-device-manager. This is controlled through the smarter-device-manager ConfigMap in the device-manager namespace.
Regex Matching
Devices are matched using the devicematch key. The current implementation targets I2C buses using a regular expression.
| Configuration Key | Purpose | Current Example |
|---|---|---|
devicematch | Regex for host /dev path | ^i2c-[0-9]+$ |
nummaxdevices | Maximum instances per node | 1 |
Sources: configMaps.yaml:9-12
Resource Mapping
Once matched, the devices are exposed as Kubernetes resources under the smarter-devices/ prefix.
Sources: values.yml:10-14
Host-Level Prerequisites
Before hardware can be utilized by the cluster, the physical hardware must be enabled and permissions must be granted at the operating system level on the Raspberry Pi nodes.
- I2C Interface: The I2C interface must be enabled via
raspi-config.sudo raspi-config nonint do_i2c 0 - Cgroup Support: Memory cgroups must be enabled in
/boot/firmware/cmdline.txtto allow Kubernetes to manage resource limits effectively. - Group Permissions: The application pods must run with the appropriate supplemental groups (e.g., GID 994 for I2C access) to interact with the device files.
Sources: README.md:11-25, values.yml:21-26
Application Resource Requests
For a pod (such as Node-RED) to access the hardware, it must explicitly request the device in its resource specification. This ensures the scheduler places the pod on a node with the available hardware and sets up the necessary device mounts.
Resource Definition Example
Resources are requested in the values.yml file, which are then passed to the Helm chart.
resources:
limits:
smarter-devices/i2c-1: 1
smarter-devices/i2c-20: 1
requests:
smarter-devices/i2c-1: 1
smarter-devices/i2c-20: 1
Sources: values.yml:10-18
Security Context
Accessing hardware requires specific user and group IDs to match host permissions.
| Setting | Value | Description |
|---|---|---|
runAsUser | 1000 | UID for the container process |
runAsGroup | 1000 | GID for the container process |
supplementalGroups | 994 | GID required for I2C device access |
Sources: values.yml:21-26
Summary of Integration Steps
To integrate a new type of hardware (e.g., a serial device), the following sequence is required:
The integration ensures that hardware is treated as a first-class citizen within the Kubernetes environment, allowing for pool automation logic to interact directly with physical sensors and controllers.
Sources: README.md:20-25, configMaps.yaml:7-12, values.yml:10-26, smarter-device-manager.yaml:1-10