pwm-gpio-fan-overlay.dts

/*
 * Overlay for a GPIO connected PWM cooling fan controlled by software GPIO PWM
 *
 * Optional parameters:
 *  - "fan_gpio"	BCM number of the pin driving the fan, default 18 (GPIO18)
 *
 *  - "fan_temp0"	CPU temperature at which fan is started with low speed in millicelsius,
 *			default 55000 (55 °C)
 *  - "fan_temp1"	CPU temperature at which fan is switched to medium speed in millicelsius,
 *			default 60000  (60 °C)
 *  - "fan_temp2"	CPU temperature at which fan is switched to high speed in millicelsius,
 *			default 67500  (67.5 °C)
 *  - "fan_temp3"	CPU temperature at which fan is switched to max speed in millicelsius,
 *			default 75000  (75 °C)
 *  - "fan_temp0_hyst"	Temperature hysteris at which fan is stopped in millicelsius,
 *			default 5000 (resulting in 50 °C)
 *  - "fan_temp1_hyst"	Temperature hysteris at which fan is switched back to low speed
 *			in millicelsius, default 5000 (resulting in 55 °C)
 *  - "fan_temp2_hyst"	Temperature hysteris at which fan is switched back to medium speed
 *			in millicelsius, default 5000 (resulting in 62.5 °C)
 *  - "fan_temp3_hyst"	Temperature hysteris at which fan is switched back to high speed
 *			in millicelsius, default 5000 (resulting in 70 °C)
 *  - "fan_temp0_speed"	Fan speed for low cooling state in range 0 to 255,
 *			default 114 (45% PWM duty cycle)
 *  - "fan_temp1_speed"	Fan speed for medium cooling state in range 0 to 255,
 *			default 152 (60% PWM duty cycle)
 *  - "fan_temp2_speed"	Fan speed for high cooling state in range 0 to 255,
 *			default 204 (80% PWM duty cycle)
 *  - "fan_temp3_speed"	Fan speed for max cooling state in range 0 to 255,
 *			default 255 (100% PWM duty cycle)
 *
 * N.B.
 *  - Uses the software GPIO PWM kernel module instead of the Pis hardware PWMs (PWM0/PWM1).
 *    This will allow for an undisturbed concurrent usage of the Pis analogue audio output.
 *
 * Requires:
 *  - A PWM controlled cooling fan connected to the GPIO, such as an
 *    Argon mini-fan, HighPi Pro Fan or Waveshare FAN-4020-PWM-5V
 *  - Raspberry Pi OS Bookworm with kernel 6.6.62 or above
 *
 * Build:
 *  - sudo dtc -I dts -O dtb -o /boot/firmware/overlays/pwm-gpiofan.dtbo pwm-gpiofan-overlay.dts
 *
 * Activate:
 *  - sudo nano /boot/firmware/config.txt add "dtoverlay=pwm-gpiofan"
 *
 */
/dts-v1/;
/plugin/;

/ {
	compatible = "brcm,bcm2835";

	fragment@0 {
		target = <&gpio>;
		__overlay__ {
			pwm_gpio_pins: pwm_gpio_pins {
				brcm,pins = <18>; /* gpio-pin = 18 */
				brcm,function = <1>; /* gpio function = output */
				brcm,pull = <0>; /* gpio pull up/down = off */
			};
		};
	};

	fragment@1 {
		target-path = "/";
		__overlay__ {
			pwm_gpio: pwm_gpio {
				compatible="pwm-gpio";
				#pwm-cells = <2>;
				pinctrl-names = "default";
				pinctrl-0 = <&pwm_gpio_pins>;
				gpios = <&gpio 18 0>; /* gpio-pin = 18 */
			};
		};
	};

	fragment@2 {
		target-path = "/";
		__overlay__ {
			fan0: pwm-fan {
				compatible = "pwm-fan";
				#cooling-cells = <2>;
				/* in ns = 20ms = 50 Hz */
				pwms = <&pwm_gpio 0 20000000 0>;

				cooling-min-state = <0>;
				cooling-max-state = <4>;
				/* PWM duty cycle values in a range from 0 to 255 */
				/* which correspond to thermal cooling states 0 to 4 */
				cooling-levels = <0 114 152 204 255>;
			};
		};
	};

	fragment@3 {
		target = <&cpu_thermal>;
		__overlay__ {
			/* in ms = poll every 2s */
			polling-delay = <2000>;
		};
	};

	fragment@4 {
		target = <&thermal_trips>;
		__overlay__ {
			/* below temperatures in millicelsius */
			trip0: trip0 {
				temperature = <55000>; /* 55 °C */
				hysteresis = <5000>;   /*  5 °C */
				type = "active";
			};
			trip1: trip1 {
				temperature = <60000>; /* 60 °C */
				hysteresis = <5000>;   /*  5 °C */
				type = "active";
			};
			trip2: trip2 {
				temperature = <67500>; /* 67.5 °C */
				hysteresis = <5000>;   /*  5 °C */
				type = "active";
			};
			trip3: trip3 {
				temperature = <75000>; /* 75 °C */
				hysteresis = <5000>;   /*  5 °C */
				type = "active";
			};
		};
	};

	fragment@5 {
		target = <&cooling_maps>;
		__overlay__ {
			map0 {
				cooling-device = <&fan0 0 1>;
				trip = <&trip0>;
			};
			map1 {
				cooling-device = <&fan0 1 2>;
				trip = <&trip1>;
			};
			map2 {
				cooling-device = <&fan0 2 3>;
				trip = <&trip2>;
			};
			map3 {
				cooling-device = <&fan0 3 4>;
				trip = <&trip3>;
			};
		};
	};

	__overrides__ {
		fan_gpio =		<&pwm_gpio>,"gpios:4",
					<&pwm_gpio_pins>,"brcm,pins:0";
		fan_temp0 =		<&trip0>,"temperature:0";
		fan_temp0_hyst =	<&trip0>,"hysteresis:0";
		fan_temp0_speed =	<&fan0>,"cooling-levels:4";
		fan_temp1 =		<&trip1>,"temperature:0";
		fan_temp1_hyst =	<&trip1>,"hysteresis:0";
		fan_temp1_speed =	<&fan0>,"cooling-levels:8";
		fan_temp2 =		<&trip2>,"temperature:0";
		fan_temp2_hyst =	<&trip2>,"hysteresis:0";
		fan_temp2_speed =	<&fan0>,"cooling-levels:12";
		fan_temp3 =		<&trip3>,"temperature:0";
		fan_temp3_hyst =	<&trip3>,"hysteresis:0";
		fan_temp3_speed =	<&fan0>,"cooling-levels:16";
	};

};