XScript HAOS

Overview

This page provides a fan control tutorial for NASPi, NASPi Gemini 2.5, NASPi CM4-M2 and NASPi CM4-2.5 on Home Assistant OS.

Due to various limitations, we were unable to run tests on Home Assistant OS, so guidance for this setup was previously missing from our tutorial - XScript. Recently, a community member generously shared their configuration workflow - see the original comment - Fan control on Home Assistant / HAOS. This contribution greatly completes and improves our tutorial. We extend our sincere gratitude to this friend, and his guide is now included on this page for anyone in need of reference.

Fan control on Home Assistant / HAOS

Goal	Set up PWM fan speed control on Home Assistant OS. The fan automatically adjusts its rotating speed based on CPU temperature. A hysteresis mechanism is adopted to prevent frequent start-stop cycles, implementing intelligent temperature-controlled variable-speed heat dissipation.
Devices	Raspberry Pi 4B, Geekworm NASPi Kit
OS	Home Assistant

Step 1: Read CPU Temperature in HAOS

To control the fan, we first need to monitor the temperature.

• Go to Settings > Devices & Services in Home Assistant.
• Click on Add Integration in the bottom right corner and search for System Monitor.
• Add the integration and ensure the processor temperature sensor (usually sensor.processor_temperature) is enabled.

Step 2: Install the "pigpio" Add-on

To allow HAOS to communicate with the GPIO pins on a hardware level, we need a small background daemon.

• Go to Settings > Add-ons > Add-on Store.
• Click the three dots in the top right corner and select Repositories.
• Add this updated community repository: [1](https://github.com/Poeschl-HomeAssistant-Addons/repository)
• Reload the page, search the list for the pigpio add-on, and install it.
• Important: Enable the toggles for Start on boot and Watchdog, then start the add-on.

Step 3: Install the PWM Integration via HACS

• Open HACS (Home Assistant Community Store) from your sidebar.
• Click the three dots in the top right corner and select Custom repositories.
• Paste the URL [2](https://github.com/RedMeKool/HA-Raspberry-pi-GPIO-PWM) into the input field.
• Select Integration as the category and click Add.
• Now, search for Raspberry Pi GPIO PWM in HACS, download the integration, and completely restart Home Assistant.

Step 4: Configure the Fan

Next, we tell Home Assistant that there is a PWM device connected to GPIO pin 18.

• Open your configuration.yaml (e.g., via the "File editor" or "Studio Code Server" add-on).
• Add the following code:

light:
 - platform: rpi_gpio_pwm
   leds:
     - name: NASPi Cooler
       pin: 18

• Save the file and restart Home Assistant once more.
• Hardware Note: You now have an entity called light.naspi_cooler. You can toggle it on your dashboard and increase the "brightness" to test it.

Caution: Due to the hardware design, the included Geekworm fan often requires at least 60–65% power (brightness) just to start spinning!

Step 5: The Automation

Finally, we link the CPU temperature to the "brightness" of our pseudo-light, using hysteresis to prevent the fan from constantly turning on and off.

• Go to Settings > Automations and create a new automation.
• Click the three dots in the top right corner and switch to Edit in YAML mode.
• Overwrite everything with this:

alias: "System: NASPi Fan Control"
mode: restart
trigger:
  - platform: state
    entity_id: sensor.processor_temperature
action:
 - choose:
     # LEVEL 2 (100%): When temp rises ABOVE 60°C
     - conditions:
         - condition: numeric_state
           entity_id: sensor.processor_temperature
           above: 60
       sequence:
         - service: light.turn_on
           target:
             entity_id: light.naspi_cooler
           data:
             brightness_pct: 100
     # LEVEL 1 (70%): When temp is between 53°C and 60°C
     # 53°C acts as the turn-on hysteresis!
     - conditions:
         - condition: numeric_state
           entity_id: sensor.processor_temperature
           above: 53
         - condition: numeric_state
           entity_id: sensor.processor_temperature
           below: 60
       sequence:
         - service: light.turn_on
           target:
             entity_id: light.naspi_cooler
           data:
             brightness_pct: 70
     # TURN OFF: Only when temp drops BELOW 48°C (turn-off hysteresis)
     # AND the temperature has been that low for at least 1 minute (time filter)
     - conditions:
         - condition: numeric_state
           entity_id: sensor.processor_temperature
           below: 48
         - condition: template
           value_template: "{{ (now() - states.sensor.processor_temperature.last_changed).total_seconds() > 60 }}"
       sequence:
         - service: light.turn_off
           target:
             entity_id: light.naspi_cooler
   # Default behavior: Do nothing, keep current state
   default: []

‎

​