Getting Started with Fan SHIM

In this short tutorial, you'll learn how to assemble, mount, and use Fan SHIM, the seriously cool fan for Raspberry Pi. We'll take you through how to install the Python library, and how to run the background script that automatically starts and stops the fan when temperature thresholds are crossed.

Assembling Fan SHIM

Your Fan SHIM comes with the following:

  • Fan SHIM PCB (the black/white circuit board)
  • 30mm fan with cable and connector
  • 2x M2.5 nylon bolts
  • 5x M2.5 nylon nuts (there's one spare)

Take the Fan SHIM PCB, with the side with the components on (the little white connector and tactile switch) facing upwards.

Push the two M2.5 nylon bolts up from underneath, through the two holes on the narrow spokes, and screw two of the nuts on to hold the bolts in place and to act as spacers for the fan, which we'll add next.

Take the fan, with the side with the writing on facing up, and the cable at approximately 7'o'clock. Push the fan down onto the bolts and then secure with another two M2.5 nuts. Make sure that you've tightened the nuts as much as possible to prevent the fan from vibrating or rattling.

Last of all, push the fan cable connector into the socket on Fan SHIM, noting the orientation of it in the photo below (black wire left/red wire right when the header is at the top). There should be enough give in the cable to bend it round the bottom left bolt/nut and then push the connector in with a fingernal or pointy end of a pencil.

Mounting Fan SHIM on your Raspberry Pi

Do this next part with your Pi shut down and powered off, i.e. with the power supply not plugged in, just in case you make a mistake when you're mounting it.

Fan SHIM uses a clever friction-fit header that means that you don't have to do any soldering! All you have to do is to carefully slip the Fan SHIM down onto the GPIO pins on your Pi.

If your Pi is sitting with the power cable and HDMI cable/s at the bottom edge towards you, and the GPIO header at the top, then you should mount your Fan SHIM on the top left 12 pins, as in the photo below.

Make sure that get the Fan SHIM on the correct pins and that you don't accidentally shift them over one pin to the left or one row down, or you're highly likely to damage your Fan SHIM and possibly your Pi.

If you're not using a case, the push your Fan SHIM all the way down onto the GPIO pins. If you're using Fan SHIM in one of our Pibow Coupé 4 cases, then you can just push it down part way onto the GPIO pins so that you can still access the right-angle tactile switch.

If you're happy that the Fan SHIM is mounted properly, then plug in your power supply and boot up your Pi now.

Installing the Fan SHIM software

For this part of the tutorial, you'll need a micro-SD card that's been set up with the Raspbian operating system, and to be connected to Wi-Fi. It's also really handy to have a display, keyboard, and mouse connected to your Pi for these next bits.

Open a terminal (press control-alt-t or find it in the Raspberry Pi menu) and then type the following to install the Fan SHIM Python library:

git clone https://github.com/pimoroni/fanshim-python
cd fanshim-python
sudo ./install.sh

That installs the Python library itself, but we've put together a nice Python script that sets temperature thresholds (along with a couple of other options) and then turns the fan on automatically when it reaches a threshold and back off when it drops back below a second threshold.

The installer accepts three values, the first for the on threshold temperature at which the fan kicks in, the second for the off threshold temperature at which the fan stops again, and the third for the delay between each temperature reading.

In our testing, an on threshold of 65°C, an off threshold of 55°C, and a delay of 2 work pretty well. Type the following in the terminal to run the installer for the automatic script:

cd examples
sudo ./install-service.sh --on-threshold 65 --off-threshold 55 --delay 2

This installer will run the automatic script in the background, and it should even start running again if you shutdown and boot up again, or reboot.

The LED indicates the CPU temperature, with green being cooler and red being hotter. A long press on the button put the fan into manual mode and then a short press will stop or start the fan. Long pressing again will re-enable automatic mode.

If you ever need to stop the script running in the background, you can type in the terminal:

sudo systemctl stop pimoroni-fanshim.service

If you want to change the thresholds, e.g to change the on temperature to 75, the off temperature to 60, and the delay to 5 seconds, then you can type the following in the terminal:

sudo systemctl stop pimoroni-fanshim.service
sudo ./install-service.sh --on-threshold 75 --off-threshold 60 --delay 5

If you want to permanently disable the background script, you can type in the terminal:

sudo systemctl stop pimoroni-fanshim.service
sudo systemctl disable pimoroni-fanshim.service

Or to re-enable it:

sudo systemctl enable pimoroni-fanshim.service
sudo systemctl start pimoroni-fanshim.service

More examples

We've provided a few other examples that demonstrate the functionality of the Fan SHIM Python library, i.e. the RGB LED, and the tactile switch/button.

You can find the examples here, along with short descriptions of what each one does: https://github.com/pimoroni/fanshim-python/tree/master/examples.

That's all folks!

Search above to find more great tutorials and guides.

Plasma 2040

Swathe everything in rainbows with this all-in-one, USB-C powered controller for WS2812/Neopixel and APA102/Dotstar addressable LED strip.