Troubleshooting Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• smarter-device-manager.yaml
• values.yml
• configMaps.yaml
• external-mdns.yaml
• 00-namespaces.yaml

This guide provides technical instructions for diagnosing and resolving issues within the swimctl swimming pool automation system. It focuses on the integration of hardware interfaces (I2C), Kubernetes orchestration (k3s), and the Node-RED application layer.

The guide covers infrastructure preparation on Raspberry Pi hardware, device management via the smarter-device-manager, and application deployment issues related to Helm and Kubernetes manifests.

Infrastructure and Hardware Initialization

Issues in swimctl often stem from incorrect hardware initialization on the host Raspberry Pi. The system requires specific kernel configurations to support containerized memory management and I2C communication.

Cgroups and I2C Configuration

If the k3s cluster fails to manage resources or pods cannot start, verify that cgroups are enabled in the boot configuration. Additionally, the I2C interface must be active for the smarter-device-manager to expose hardware to the application.

# Verify cgroups in /boot/firmware/cmdline.txt
# Expected parameters: cgroup_memory=1 cgroup_enable=memory

Sources: README.md:6-18

Hardware Access Flow

The following diagram illustrates the dependency chain from the physical hardware to the Kubernetes pod.

The smarter-device-manager uses a regex-based configuration to match host devices (e.g., /dev/i2c-1) and provide them as allocatable resources to the cluster.
Sources: configMaps.yaml:8-10, smarter-device-manager.yaml:45-58

Device Management Troubleshooting

The smarter-device-manager is responsible for mapping host /dev nodes into the container environment. Failure to access pool sensors or controllers usually indicates a breakdown in this mapping.

Resource Allocation Failures

If a pod remains in a Pending state with "Insufficent smarter-devices/i2c-X" errors, check the following:

1. DaemonSet Status: Ensure the smarter-device-manager pod is running in the device-manager namespace.
2. Node Labels: The DaemonSet may require specific node labels to schedule correctly (though currently commented out in the manifest).
3. ConfigMap Match: Verify the conf.yaml in the ConfigMap matches the device nodes present on the Pi.

Component	Target File/Resource	Purpose
Namespace	device-manager	Isolation for hardware management
ConfigMap	smarter-device-manager	Defines regex for I2C device matching
DaemonSet	smarter-device-manager	Mounts host /dev and /sys to discover devices
Resource Request	smarter-devices/i2c-1	Pod-level request for hardware access

Sources: 00-namespaces.yaml:1-6, configMaps.yaml:8-10, values.yml:10-18, smarter-device-manager.yaml:61-75

Application Deployment and Node-RED

The Node-RED application depends on external secrets and a specific initialization sequence to clone project flows from GitHub.

Secret and Environment Variable Configuration

Missing credentials will cause the Node-RED container or the clone-repo init container to fail. Ensure the swimctl secret is populated with all required keys.

Repository Cloning Issues

The clone-repo init container performs a destructive refresh of the project directory. If flows are not appearing, check the logs of the init container.

• Path: /data/projects/swimctl-flows
• Permissions: The container runs as UID/GID 10003, while the main app runs as 1000. Volume permissions must allow cross-container access.
• Git Hook: An automatic post-commit hook is created to trigger GitHub Actions via curl. If the hook fails, ensure GITHUB_TOKEN_FLOWS has repository dispatch permissions.

Sources: values.yml:101-140

Ingress and Connectivity

Network access to the swimctl.local interface is managed by external-mdns and the NGINX Ingress controller.

• mDNS: The external-mdns service watches Ingress and Service resources to broadcast hostnames on the local network.
• Permissions: external-mdns requires a ClusterRole with permissions to list/watch services and ingresses across the cluster.

Resource	Namespace	Configuration
Ingress Host	N/A	swimctl.local
Service Account	kube-system	external-mdns
Image	kube-system	blakec/external-mdns:latest

Sources: values.yml:79-86, external-mdns.yaml:1-63

Summary of Common Resolutions

1. I2C Not Found: Check raspi-config settings and ensure the smarter-device-manager ConfigMap regex matches /dev/i2c-*.
2. Permission Denied on I2C: Ensure the pod security context includes supplementalGroups: [994] (the I2C group).
3. Flows Not Updating: Verify the clone-repo init container logs and the validity of the gh_token in the Kubernetes secret.
4. Hostname Unreachable: Confirm external-mdns is running in kube-system with hostNetwork: true.

Sources: README.md:16-18, values.yml:25-28, external-mdns.yaml:57-58