Getting Started

Requirements

Raspberry Pi 5 with a Freenove Computer Case Kit Pro (any non-display variant: FNK0107A through FNK0107L)
Python 3.11 or later
I2C enabled on your Pi

Compatible Models

casectl works with the non-display variants of the Freenove Computer Case Kit Pro (FNK0107 series):

Model	NVMe Slots	SSD Included	Compatible
FNK0107A	1	No	Yes
FNK0107B	2	No	Yes
FNK0107C	4	No	Yes
FNK0107H	1	Yes	Yes
FNK0107K	2	Yes	Yes
FNK0107L	4	Yes	Yes
FNK0107P-W	1-4	Varies	No (display variants)

The display variants (FNK0107P through FNK0107W) include a 4.3" IPS touchscreen that casectl does not currently support. The fans, LEDs, and OLED on these models use the same STM32 expansion board and may still work, but this is untested.

Installation

Clone the repository and install with hardware support:

git clone https://github.com/cadfan/casectl.git
cd casectl
pip install -e ".[hardware]"

For development (includes test tools and linting):

pip install -e ".[all]"

Enable I2C

The STM32 expansion board communicates over I2C. Enable it if you haven’t already:

sudo raspi-config nonint do_i2c 0
sudo usermod -aG i2c $USER
# Log out and back in, or reboot

First Run

Check that your hardware is detected:

casectl doctor

You should see all 9 checks passing:

 Check                               Result     Details
 Python >= 3.11                      PASS       3.13.x
 smbus2 importable                   PASS
 /dev/i2c-1 exists                   PASS
 /dev/i2c-1 permissions              PASS
 I2C probe 0x21 (STM32)             PASS       Device responding
 I2C probe 0x3C (OLED)              PASS       Device responding
 CPU temp sysfs readable             PASS       46.3 °C
 luma.oled importable                PASS
 Pillow importable                   PASS

Start the Daemon

Launch the casectl daemon to enable the web dashboard and plugin system:

casectl serve

The daemon starts on http://localhost:8420 with the HTMX web dashboard. Open it in your browser to control fans, LEDs, and the OLED display.

For LAN access (e.g. from your phone):

casectl serve --bind 0.0.0.0

This auto-generates an auth token printed to the console.

Basic CLI

Control hardware directly from the command line:

# Fan control
casectl fan status
casectl fan mode follow-temp    # temperature-curve PWM
casectl fan mode manual        # switch to manual control
casectl fan speed 0 75         # set fan 0 to 75%

# LED effects
casectl led color arctic-steel  # named colour (or use #8AAAC4 or 138 170 196)
casectl led mode rainbow
casectl led mode breathing

# OLED display
casectl oled screen 0 --enable
casectl oled screen 1 --disable

# System monitoring
casectl monitor

# Interactive terminal dashboard
casectl top                # live-updating TUI with fan/LED/temp/memory
casectl top --once         # single snapshot for scripts

Configuration

casectl uses a YAML config file at ~/.config/casectl/config.yaml. All settings have sensible defaults – edit only what you want to change.

# View current config
casectl config get fan

# Set a value
casectl config set fan mode 0   # config stores integer enum values

Troubleshooting

I2C not detected: Make sure I2C is enabled in raspi-config and you’ve rebooted. Check with i2cdetect -y 1 – you should see devices at addresses 0x21 (expansion board) and 0x3C (OLED).

Permission denied on I2C: Add your user to the i2c group: sudo usermod -aG i2c $USER then log out and back in.

Expansion board not found: Check the ribbon cable connection between the Pi and the expansion board. It should be firmly seated at both ends.

OLED blank: The OLED defaults to off. Run casectl oled screen 0 --enable to activate the first screen.