pifanctl: A Raspberry Pi Fan Controller

🥧 A CLI for PWM Fan Controlling of Raspberry Pi

🐳 pifanctl is a CLI tool for PWM fan control on Raspberry Pi. It can be easily run via Docker and Kubernetes and is optimized for ARM64 architecture. The project features a CI/CD pipeline using GitHub Actions with Actions Runner Controller (ARC), ensuring all builds are tested in actual Raspberry Pi environments. Please enjoy it!

---

1. Run

1.1. Requirements

• Raspberry Pi (ARM64)
• Python 3.8+

You should access the Raspberry Pi (ARM64) to run the following commands.

1.2. OPTION 1: Install CLI like a package

curl -fsSL https://raw.githubusercontent.com/jyje/pifanctl/main/install.sh -o install-pifanctl.sh
chmod +x install-pifanctl.sh
./install-pifanctl.sh
rm install-pifanctl.sh

## Uninstall
# rm -rf $HOME/.pifanctl

After installation, you can use the following command to control the fan, pifanctl --help

1.3. OPTION 2: Using Docker

docker run -it ghcr.io/jyje/pifanctl python main.py --help

Then you can use the following command to control the fan:

And you can run the following command to start the fan:

docker run --privileged -it ghcr.io/jyje/pifanctl python main.py start

Currently, --privileged is required to access and control the GPIO pins. We will try to find a better solution in the future.

1.4. OPTION 3: On Kubernetes

Run the following command to install the pifanctl on Kubernetes with Raspberry Pies and a PWM Fan.

kubectl create namespace pifanctl
kubectl apply -n pifanctl -f https://raw.githubusercontent.com/jyje/pifanctl/main/k8s/manifests/deployments.yaml

You can check the status of the pifanctl with the following command:

kubectl get pods -n pifanctl

You can check the logs of the pifanctl with the following command:

kubectl logs -n pifanctl -l app=pifanctl

1.5. OPTION 4: Run Source Code

git clone https://github.com/jyje/pifanctl ~/.pifanctl
cd ~/.pifanctl/sources
pip install --upgrade -r requirements.raspi.txt
python ~/.pifanctl/sources/main.py --help

---

2. Build

If you want to build it yourself, you can do the following:

Important

The package RPi.GPIO is available on the Raspberry Pi OS or Linux OS tuned by Raspberry Pi Foundation. So you should run following command on Raspberry Pi.

git clone https://github.com/jyje/pifanctl ~/.pifanctl
cd ~/.pifanctl/sources
pip install --upgrade -r requirements.raspi.txt

Then you can debug the source code with the following command:

python ~/.pifanctl/sources/main.py --help
python ~/.pifanctl/sources/main.py --version
python ~/.pifanctl/sources/main.py status

---

3. CI/CD Pipeline

This project uses GitHub Actions with Actions Runner Controller (ARC) for ARM64-based CI/CD pipeline. The builds are executed on self-hosted Raspberry Pi runners, ensuring native ARM64 compatibility.

You can check the environment of CI/CD pipeline in app.jyje.live#stack

3.1. Workflow Structure

• Main Branch (build-image-main.yaml)

  • Builds and publishes to ghcr.io/jyje/pifanctl:latest
  • Tags with commit SHA
  • Runs on production-ready code

• Develop Branch (build-image-develop.yaml)

  • Builds and publishes to ghcr.io/jyje/pifanctl-dev:latest
  • Used for development and testing

• Issue Branches (build-image-issue.yaml)

  • Builds and publishes to ghcr.io/jyje/pifanctl-issue:latest
  • Builds feature branches with pattern issue-**
  • Tags only with commit SHA for temporary testing

3.2. Key Features

• Native ARM64 builds using self-hosted runners (r4spi-microk8s)
• Automatic version tagging using commit SHA
• Skip CI option with --no-ci flag in commit messages
• GitHub Container Registry (ghcr.io) integration
• Automated testing of built images

3.3. Build Process

1. Initialize and check for CI skip flag
2. Build Docker image for ARM64 platform
3. Push to GitHub Container Registry
4. Run automated tests on the built image

---

4. Trouble Shooting

Is there any problem? see trouble-shooting.md

---

5. References

• Official: Raspberry Pi Foundation
• Blog: Using Raspberry Pi to Control a PWM Fan and Monitor its Speed