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 the fan when a temperature threshold is 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
  • 4x 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 uderneath, 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 a temperature threshold (along with a couple of other options) and then turns the fan on automatically when it reaches that threshold and back off when it drops back below it.

The installer accepts two values, the first for the threshold temperature at which the fan kicks in, and the second for something called hysteresis. The hysteresis is like a buffer that helps to prevent the fan from switching on and off really quickly as soon as it crosses the threshold temperature.

In our testing, a temperature threshold of 65°C and a hysteresis of 5°C work pretty well. Type the following in the terminal to run the installer for the automatic script:

cd examples
sudo ./install-service.sh 65 5

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 status of the fan with green being on and red being off. 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 vackground, you can type in the terminal:

sudo systemctl stop pimoroni-fanshim.service

If you want to change the threshold or hysteresis values, e.g to change the threshold to 55 and the hysteresis to 2.5, then you can type the following in the terminal:

sudo systemctl stop pimoroni-fanshim.service
sudo ./install-service.sh 55 2.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.

Shopping basket

Need something for this project? You can use the links below to add products to your Pimoroni Shop basket for easy checkout.

Fan SHIM for Raspberry Pi
£9.60
Raspberry Pi 4
1GB RAM £34.00
Raspberry Pi 4
2GB RAM £44.00
Raspberry Pi 4
4GB RAM £54.00
Want to checkout or change something? Click here to view your cart.

Tutorial
Beginner
Raspberry Pi

Sandy Macdonald

sandy@pimoroni.com
@sandyjmacdonald
http://sandyjmacdonald.github.io
Formerly, Sandy worked at the University of York, in the biology department, analysing data and telling people that they should have used more replicates. Now a fully-fledged crew member at Pimoroni - head of digital content - working on learning materials and digital chunterings. Find him on Twitter and most everywhere else, as sandyjmacdonald.