{"id":16520061,"url":"https://github.com/pageauc/pifan","last_synced_at":"2025-10-28T07:31:32.275Z","repository":{"id":74954772,"uuid":"204769436","full_name":"pageauc/pifan","owner":"pageauc","description":"Control Raspberry Pi case fan on/off using CPU temperature","archived":false,"fork":false,"pushed_at":"2023-12-23T19:23:17.000Z","size":26,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T12:45:32.562Z","etag":null,"topics":["bcm-gpio","control-fan","cpu-temperature","curl-install","gpio-diagram","gpio-scan","npn-transistor","off","on","python","raspberry-pi","resistor","rpi","rpi-case","service","systemd","temperature-control","temperature-monitoring","temperature-setpoint","wire"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pageauc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-08-27T18:52:58.000Z","updated_at":"2024-12-07T15:07:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"cfbffc04-a596-43d1-8186-509cd8cf62df","html_url":"https://github.com/pageauc/pifan","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageauc%2Fpifan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageauc%2Fpifan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageauc%2Fpifan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pageauc%2Fpifan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pageauc","download_url":"https://codeload.github.com/pageauc/pifan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238614553,"owners_count":19501479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bcm-gpio","control-fan","cpu-temperature","curl-install","gpio-diagram","gpio-scan","npn-transistor","off","on","python","raspberry-pi","resistor","rpi","rpi-case","service","systemd","temperature-control","temperature-monitoring","temperature-setpoint","wire"],"created_at":"2024-10-11T16:49:26.847Z","updated_at":"2025-10-28T07:31:31.954Z","avatar_url":"https://github.com/pageauc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pifan\n### Control a Raspberry Pi case cooling fan on/off using CPU temperature\n\n### Quick Install or Upgrade\n**IMPORTANT** - It is suggested you do a Raspbian ***sudo apt-get update*** and ***sudo apt-get upgrade***\nbefore curl install\n\n***Step 1*** With mouse left button highlight curl command in code box below. Right click mouse in **highlighted** area and Copy.\n***Step 2*** On RPI putty SSH or terminal session right click, select paste then Enter to download and run script.\n\n    curl -L https://raw.github.com/pageauc/pifan/master/pifan-install.sh | bash\n\nThe command above will download and Run the GitHub ***pifan-install.sh*** script.\nAn upgrade will not overwrite ***config.py*** file.\n\n### Description\nControl a Raspberry 5v or 3.3v case cooling fan so it turns on\nat a high temperature setpoint and off at a lower temperature setpoint.\nThis avoids running the fan when it is not required.  Might also help reduce\ndust bunnies collecting in RPI case if you do not have a lint filter over cooling intake.\n\nThe pifan scripts utilizes an NPN transistor to switch fan power on and off based on temperature.\nTransistors can be ***S8050***, ***2N4401*** or equivalent plus approx ***100-300 ohm resistor***.\nI had a variety and some are close to 300 ohms and worked without problem.\nI simply soldered the project together using short coloured famale jumper wires per the wiring diagram below and used\ntwo small shrink wraps to cover resistor solder connections and the second for one fan connection wire solder connection.\nI then used one larger shrink wrap to encase the transistor, resistor and all three soldered jumper wires to insulate them.\nElectrical tape can also be used.\n\nOn the ***pifan.py*** script I did some extra programming as a learning excercise. The extra features are\nnot necessary for operation but I enjoyed adding them. This script can be used for testing operation.\n\n### Wiring Details\nI used female jumper wires and cut one end off to a convenient length to avoid excess wire inside\nthe RPI case.\n\nThe RED fan wire is connected directly to a 3.3v or 5v gpio pin.\nSee [GPIO diagram](https://www.raspberrypi.org/documentation/usage/gpio/) for pin locations\nalso [Interactive pinout diagram](http://pinout.xyz/)\n\nThe BLACK Fan wire connects directly to one side of npn transistor.\nA second black wire connects between other side of the npn transistor\nthen to a gpio ground pin (see a gpio diagram for locations)\n\nA YELLOW wire (non black/red) is connected to the center lead of the npn transitor\nthen to one side of approx 100 - 300 ohm resistor. Other side of resistor is connected to\npin specifed by the BCM fan_GPIO variable below.\nThis pin turns the fan on/off based on appropriate setpoint temperatures.\n\n```\nWiring Diagram\n                       \u003c\u003c is a male to female jumper wire\n                          joint to allow easy fan connect, disconnect\n                 fan\n   +5V \u003e---------[X]---\u003c\u003c---NPN-----------\u003c GPIO ground pin\n    or        red   blk      |      blk\n  +3.3V                      |\n   pin                       $ approx 100-300 ohm resistor\n                             |\n                             | yellow (non black or red wire)\n                             |\n                            GPIO\n                         control pin\n```\nSee [Interactive pinout diagram](http://pinout.xyz/) for pin details.\nDefault control pin is BCM 25.  I used pin 4 for 5v power and pin 5 for ground.\nThey are beside each other so easier to locate.\n\n### pifan.py Features\nAs a programming excercise I wrote some extra ***pifand.py*** features that\nmay not necessariy be functionally required.\n\n* logging library for messaging.  This also allows redirecting output to a file.\n* argparse library implemented to allow changing some parameters from command line\n* Optional import of variables from a config.py file.\n* Added auto detection to turn off logging if being run as daemon.\n* A dictionary is used to store default variables and values.  This can\nbe used to check missing config.py settings or can replace importing from config.py\n\nprogram optional arguments\n\nusage: pifan.py [-h] [-f {on,off,auto}] [-p PINNUMBER] [-s] [-v] [-d] [-q]\n\nControl Fan using NPN transistor and Temperature Settings\n```\noptional arguments:\n  -h, --help            show this help message and exit\n  -f {on,off,auto}, --fanmode {on,off,auto}\n                        Fan Control modes. Valid values are on, off or auto\n  -p PINNUMBER, --pinnumber PINNUMBER\n                        Valid Fan BCM GPIO Control Pin Number (integer)\n  -s, --status          Checks Status of Fan and Temperature readings from\n                        pifand.service or Other Fan Control script.\n  -v, --verbose         Turn on verbose logging\n  -d, --debug           Add detailed fan and temp logging messages\n  -q, --quiet           Turn off verbose logging\n```\n\n### pifand.py\nI wrote pifand.py to be used as a systemd service daemon.  The file can be run as a\nbackground task or installed as a systemd service per instructions below.\nNote the differences between the pifan.py and pifand.py scripts.\nBoth do the same job but pifand.py is very minimalistic.\n\n### Testing\nTo test, connect the soldered NPN transistor assembly to the appropriate pins.\n***NOTE***: Power OFF the RPI just to be safe, then connect the soldered NPN transistor assembly per the following.\n\n* Red fan wire to 5v GPIO pin 4\n* Black NPN ground wire to GPIO pin 5\n* Yellow (non black,red) wire to BCM GPIO pin 25\n\nWith the RPI running, open an ssh or terminal session and start the pifan.py script in debug mode.\n\n    cd ~/pifan\n    ./pifan.py -h   # display parameter options\n    ./pifan.py -d   # Note. -v mode just displays message when fan turns ON or OFF at setpoints\n\nDebug mode will display the temperature and fan status every 10 seconds by default.\nYou can change variable settings in config.py per comments using nano editor.\n\nOpen a second ssh or terminal session. In order to increase the RPI temperature\nyou will need to run a program to stress the cpu. Install and run stress per the\nfollowing commands.\n\n    sudo apt-get install -y stress     # Installed as part of github curl install\n    stress -c 4   # runs quad core cpu's at 100% or -c 2 for dual core\n\nIn the first terminal session you should see temperature rise. Fan should turn ON\nat 65'C or greater. If not check connections and possibly solder joints.\n\nPress cntrl-c to exit stress.  The temperature should decrease and\nthe fan should stop at 55'C or less.\n\nTo display help on stress program features execute\n\n    stress\nor\n    stress --help\n\nYou can monitor cpu and other system data by opening another ssh or\nterminal sessionby running and running htop per command below\n\n   htop\n\ntype q or cntrl-c to exit htop\n\nTo check GPIO pin status while pifan.py is running you can run\n\n    ./chkpins.py\n\nselect 1 for display by board pin order or 2 or enter for BCM GPIO order.\nIf pifan.py or pifand.py are running then you should see a GPIO.OUT on the\nfan control pin (default BCM GPIO pin 25 or Board pin 22)\n\nIf everything runs OK you can install pifand.py as a systemd service.\n\n### How to Manually Create a pifand Systemd Service\n\n#### Step 1 Checks\nCheck that ***/usr/bin/vcgencmd*** command reads current RPI temperature per.\n\n    /usr/bin/vcgencmd measure_temp\n\nThis should return the current cpu temperature.\n\nIf there is a problem, find path to ***vcgencmd*** using command below.\n\n    which vcgencmd\n\nIf path is Not ***/usr/bin/vcgencmd*** Then nano edit ***config.py***\nand ***pifand.py*** change ***VCGENCMD_PATH=*** variable\n\nCheck that pifand.service file ***ExecStart=*** entry is correct path and settings.\n\n    cd ~/pifand\n    more pifand.service\n\nChange file pifand.service settings using nano if required.\n\nCheck that ***pifand.py*** variable settings are correct and change if required.\n***NOTE:*** variables are hard coded in pifand.py and do NOT read config.py settings.\nThis is done to simplify script operations while running as service.  See Alternative Below.\n\n    nano pifand.py\n\nEdit the User Variable Settings as required then ctrl-x y to save and exit nano.\n\n#### Alternative\nInstead of using ***pifand.py*** you can run ***pifan.py -q*** in the pifand.service file.\n***pifan.py*** can read variables settings from the ***config.py*** file. This makes it\nhandy to change settings if require, rather than having to edit the variables in\nthe ***~/pifan/pifand.py*** file.\n\n***NOTE:*** If ***pifan.py*** file is used in the ***pifand.service*** file,\nand a ***config.py*** file does not exist then the dictionary ***CONFIG_SETTINGS*** settings are used.\n\n    cd ~/pifan\n    nano pifand.service\n\nIn nano change ***ExecStart=/usr/bin/python /home/pi/pifan/pifan.py -q*** then ctr-x y to save and exit\n\n#### Step 2\nA template copy of the ***pifand.service*** is downloaded with github curl install of ***pifan-install.sh***\nTo install this copy perform the following\n\n    cd ~/pifan\n    sudo cp pifand.service /lib/systemd/system/pifand.service\n\nProgress to Step 3\n\nor\n\nTo manually Create or Edit the systemd pifand.service file use command below\n\n    sudo nano /lib/systemd/system/pifand.service\n\nIf ***/lib/systemd/system/pifand.service*** file is blank Cut/Paste or Add text as shown below\n(does not need to be indented).\n\n```\n[Unit]\nDescription=run fan when hot\nAfter=meadiacenter.service\n\n[Service]\nUser=root\nGroup=root\nType=simple\nExecStart=/usr/bin/python /home/pi/pifan/pifand.py\nRestart=Always\n# On OSMC use Restart=on-failure instead of Restart=Always\n\n[Install]\nWantedBy=multi-user.target\n```\n\nctrl-x y to save file and exit the nano editor\n\n#### Step 3\nAfter any changes to ***/lib/systemd/system/pifand.service*** file,\nexecute commands below\n\n    sudo systemctl daemon-reload\n    sudo systemctl enable pifand.service\n    sudo reboot\n\n#### Step 4\nEnsure the pifand.service in systemd is enabled and running, per commands below\n\n    systemctl list-unit-files | grep enabled | grep pifand\n    systemctl | grep running | grep pifand\n    systemctl status pifand.service -l\n\nIf there are any issues with starting the script using systemd,\nthen examine the journal using commands below\n\n    sudo journalctl -u pifand.service\n\n### cpu-temp.py\nIf you have pifand.py running as a systemd service or background task,\nyou can check the RPI temperature using the ***cpu-temp.py*** script per\n\n    cd ~/pifan\n    ./cpu-temp.py\n\nThis will display the temperature every 5 seconds by default.\nTo change delay edit the ***cpu-temp.py*** file using nano.\n\n    cd ~/pifan\n    nano cpu-temp.py\n\nThen change the ***sleep_seconds*** variable.  ctl-x y to save and exit\n\nAlternatively you can check fan and temperature status by running the following\ncommand\n\n    cd ~/pifan\n    ./pifan.py -s\n\n***NOTE:*** If the fan control pin is not enabled then ***pifan.py*** ***-s*** will\ndisplay a warning message and exit.\n\n### Get Help\n\nPost an [issue](https://github.com/pageauc/pifan/issues) to github pifan repo if you need help.\n\nClaude ....","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpageauc%2Fpifan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpageauc%2Fpifan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpageauc%2Fpifan/lists"}