BrewPi Hardware

There’s two very important points I need to share about this:

  • Without the start FuzzeWuzze gave us on the “Mega Thread” on, a lot of us would never have successfully made our first rig. The first post is dated, the thread incredibly long (but still full of AWESOME info), the various fan Wiki’s also dated, so I wanted to persist for as long as I could how a person can put together the hardware
  • There are as many ways to do this as there are people doing it. This is ONE WAY it can be done. If you are smart enough to deviate from this, you should be smart enough to figure it out yourself. Please don’t ask me why your new idea doesn’t work

This post will share how to put the hardware supporting BrewPi together in the most basic way with which I believe a person can be successful. It is not meant to be “production ready”, it’s meant to show how it works on the bench so that the DIYer can add a case, etc., and use it on their fermentation chamber.

What you need

I’m not going to suggest which ones of these to buy, but I will give you some pictures that, along with the name/description, should be about all you need to find them on the Internet. I’ll give you a hint: I got all of these pictures except for the thermowell off Amazon. For the thermowell, seek out Brewers Hardware:

A fridge that you can “hack”. This can be as simple as keeping a fridge’s thermostat all the way on cold and plugging it into the system so that it only turns on by the BrewPi system. Most modern refrigerators use timers and such which make using them a little less straightforward. If you have what is commonly sold as a “kegerator”, it will work pretty well as it lacks auto-defrost, etc. This article will not detail how to hack a fridge (maybe some future article will), it will assume you are using one of those “kegerator” style boxes.

A working Raspberry Pi. This article will not detail how to setup the Raspberry Pi, nor address the software part of the build – that’s done elsewhere.

An Arduino Uno. I recommend not trying to get the cheapest one possible straight from China, and until you know why; avoid the ones that state they have a “CH340”. You can get a genuine Arduino Uno R3 on Amazon for $20, and decent clones for about $11. Get a USB A to B cable while you are at it if it does not come with one.

A 2-channel 5-volt relay, commonly the “SainSmart 2-Channel Relay Module” or a similar model.

A 15A 115v electrical outlet (if you are not in North America, modify this accordingly).

A “euro-style” wire connector strip, three stations will be needed. You can do this with anything, a breadboard, wire nuts, go wild. The first time I made this, this is what I used and it worked well.

One 4.7k Ω 1/4 watt axial resistor (sometimres you see this called a 4k7 Ω ). You are unlikely to find a single of these for purchase, they are pennies a piece. Pretty much anything you find that says 4.7k Ω 1/4 watt that looks remotely like the ones on the left will be fine.

Some 22 gauge Dupont jumper wires in male to female and male to male. You can generally get an assortment of gender combinations in various colors for a few bucks.

Some 16 or 18 gauge stranded wire, in black and red. You won’t need much of this, maybe a foot each. You can even cannibalize some from the next item.

A 16 or 18 gauge (16/3 or 18/3) grounded power cord. An old computer cord is a pretty good item for this if you have one.

(Optional) a “Ceramic Heat Emitter” in 60 or 75 Watts, commonly sold as a reptile heater bulb. Many indoor implementations will never need a heater, but if you have this in an unheated garage or shed in a cold climate, some form of heating will be required. Some folks have used a “personal heater” but even 100w is pretty hefty for this application – a light bulb is enough heat but you don’t want light in the chamber to prevent skunking your beer.

You’ll also need a lamp/cord/receptacle to support a lamp inside the fridge (if you decide to use one.)

(Optional) a small “personal sized” fan for inside the fridge to eliminate dead spots. Nothing large, whatever you have and will fit will work.

At least two DS18B20 sensors (called “one-wire”). Getting “waterproof” sensors with leads is important. Make sure they are directly powered and not parasitic. Searching the reviews and/or BrewPi threads will help you get known good items. Also make note of the wiring/color scheme from the manufacturer. You will need this. It’s nearly always listed with the item’s description.

(Optional but HIGHLY recommended) a stainless-steel thermowell. You won’t need this for bench-testing this of course, but using a thermowell for the “beer” sensor is much better than any of the other methods for getting a good beer temp. Make sure the sensors fit in the well.

Putting it Together

I could blather on about how to put this together, but I think a picture is worth a thousand words. This is a diagram done by 100Amps on Homebrewtalk that suffices for those 1000 words:

Arduino Electrical Connections

There are few things that while clear on this diagram I have managed to screw them up or allowed them to confuse me (or allowed me to confuse myself):

  • You can tie all of the One-Wire sensors together as shown since they are digital and have their own internal addresses
  • The “data” leg of the one-wire sensors go to the A4 terminal on the Arduino, power the terminal marked “5v” and the ground to “GND”. Each manufacturer of the sensors seems to change the colors around, so you will have to refer to the manufacturer for which color is which
  • A one-wire sensor (or many of them tied together) requires a single 4.7k Ω resistor between power and data in order to function correctly. This is called a “pull-up resistor” if you want to Google it. It looks strange but it’s necessary
  • There is a jumper on the hot side of the outlet that can be broken off with a pair of pliers which allows them to be powered separately – we use this to independently turn on and off the heat and cool

Step by Step Wiring

Refer to the wiring image above as you go through these instructions. The colors need not be the same, but if you keep them consistent you will thank yourself for it later. Print the pic (in color) to make it even easier to reference as you follow along.

Low Voltage Wiring

  1. Get your Raspberry Pi running, get logged in, play with it if you want. You can follow these instructions in the Raspberry Pi pages. You need not make it headless, do it however you want. The videos on the Raspberry Pi website are really good as well. All you need is the Raspberry Pi running, and able to connect to the Internet.
  2. Connect your Arduino to your Raspberry Pi with a USB A to B cable. This serves for both communications and power. Nothing will really happen yet other than an LED lighting up on the Arduino.
  3. Install BrewPi Remix just to make sure your primary pieces are working correctly. Doing it now avoids any confusion later on when you add the rest of the wiring. You’ll know it works before you end up adding more “stuff.” When you are done, the screen will tell you the URL you may use to access your new BrewPi installation. Open it up in a web browser and enjoy it for a moment! When you are satisfied it works enough to open up the page, you can come back here and worry about the rest of the hardware.
  4. Unplug your Arduino from your Raspberry Pi (you do not need to power down the Raspberry Pi first) before you proceed.
  5. You are now going to use your Dupont wires. Grab three different colors of your male to male wires and plug one each in the Arduino’s 5V, GND and A4 (this is your “data” port). These are all on the same side of the Arduino, on the same side as the black power inlet. Pick separate terminals on your Euro-connector, whichever ones you like, and run them there. No need to tighten things up right now.
  6. Take a couple of Dupont wires, male to female, which match your 5v and GND wires. Put the male ends into the corresponding Euro-connector terminals (obviously easier here if you use the same colors as your first two wires.) Again, just snug, no need to tighten.
  7. Take your 4.7k Ω 1/4 watt resistor and connect it between your A4 (data) connector and your power (5V) connector.
  8. You should now have two wires coming into the ground (GND) terminal, two wires plus one side of the resistor into your power (5V) terminal, and one wire plus the other end of the resistor into your data terminal (A4). You can snug them down now if you wish.
  9. Now take at least one (I recommend two) of your temp sensors and referencing the manufacturer’s layout, connect all of the ground leads into the other side of the GND terminal. Connect all of the power leads (may be referenced as VCC) to the other side of the power (5V) terminal. Connect all of the data leads to the other side of the data (A4) terminal. One sensor will be your “beer” sensor and the other the “chamber” sensor.
  10. Now you will connect your 2-channel relay. Take a look at the low-voltage side first. It will have two small male pin strips; one three pins and one four. The three pin strip should have a jumper (probably a small blue or black cap) between JD-VCC and VCC on the strip of three pins. This allows the relay to be powered by the Arduino.
  11. Now you will connect your leads from power (5V) and ground (GND) out of the terminal block to the relay. 5V goes to VCC, GND goes to GND.
  12. Take two more Dupont jumpers, male to female, of differing colors. These will represent heat and cool so maybe blue and orange would be good. Connect one to digital pin 5 and one to digital pin 6 (likely marked ~5 and ~6) on the opposite side of the other connections (USB connector side). At this point it doesn’t matter which is which, you will be able to set the pins later.
  13. The other ends of these jumpers will go to the IN1 and IN2 terminals on the 4-pin strip on the relay.

Your low-voltage wiring is now complete. You can go ahead and plug your Arduino back into your Pi. Refer to the instructions to set up your probes and relay pins and get to know your system. Experiment and test now before proceeding. I recommend a digital multi-meter to test the continuity at the high-voltage side of the relays so you can get the hang of how things work before actually applying high voltage. You can also view the LEDs on the relay card.

There’s nothing about any of the low voltage we’ve done so far which will be harmful to you. You might short some of the circuit logic if you are careless and allow things to touch each other, but I’ve had a lot of these systems laying around, in my lap, on a coffee table, even laying on the carpet, while I test.

High Voltage Wiring

This is where you can destroy your equipment, home wiring, start a fire, harm or kill yourself. BE CAREFUL and if you do not understand what you are doing find someone to help. This is something most home brewers will find trivial, but if there’s any doubt; don’t.

  1. Look at the “hot” side of your outlet. On North American outlets with the ground terminal towards the bottom, this will be on the right side of the outlet between the two terminals. These terminals are generally gold. There is a jumper there which you can grab with a pair of pliers and break off. Do so. This allows you to power each outlet separately, one for heat and one for cool. If you do not do this, you will be running your heater and your fridge at the same time and wondering WTH is going on.

    This is called a “split receptacle” or sometimes a “switched receptacle.” When you buy your outlet at the local big box store, the people that work in electrical (if you can ever find one) can point this out for you as well.
  2. Take two lengths of stranded wire, 16-18 gauge and preferably red. These will go between the relays and the outlet so maybe a foot or two long. Some crimp-on terminals (called “spade” connectors) would help here but are not absolutely necessary. If you do not use spade terminals, it would be better to use solid core wire for this part. Connect them one each to the hot terminals on the side of the outlet (where you broke off the jumper.)
  3. Connect the other ends of those wires to the “NO” (this doesn’t mean “don’t do it”, it means “Normally Open”) side of the two terminal blocks on the high-voltage side of the relay board. I’d recommend crimping on what’s called “bootlace ferrules” or tinning the ends of the wire (melting solder on the end) if you are using stranded wire. You can do without the ferrule or tinning for testing, but for production use, it’s highly recommended.
  4. Take a piece of black stranded (tinned or ferrules on the ends) or solid-core wire and run it between the NC (Normally Closed) terminal of relay number one (on the top as you look at the relay board with the high-voltage on the right) and the COM terminal on relay number two. Refer to the diagram above for clarification.
  5. Take your power cord and strip enough of the main insulation to work with the three leads. Strip the tips of the three leads. A spade terminal would be good on the ground (green) and the common/neutral (white) leads. The hot lead (normally black) should get tinned or a ferrule.
  6. Connect the ground to the ground lug on the outlet. Connect the common/neutral lead to the neutral side of the outlet.
  7. Run the hot lead from the power cord to the COM terminal on relay number one.
  8. If you are using a metal box for your outlet, run an additional (preferably green) lead between the ground lug on the outlet to the ground lug on the box.

At this point your high voltage side is complete, at least enough for testing. Test BEFORE you plug in your power cord! I am not responsible for anything that goes wrong here so make sure you know what you are doing or have a licensed electrician do the work or check your work. One outlet is going to be controlled for heat, one for cool. Your (optional) fan can be plugged in any convenient outlet – it should run 100% of the time.

I’d highly recommend you mount the outlet to something that’s not going to move, put it in an outlet box, something to protect you and your belongings from the high voltage terminals.

As one final step before plugging in your refrigerator or heater, grab a couple of cheap outlet testers with lights, or even a couple of table lamps, and test some more to make sure things work like you expect.

Work Complete

The work above, and putting the “guts” into a suitable box, are all I did for my fermentation chambers. I plug my kegerator (set on 100% cold) into the “cool” outlet, and my heater (a 60w lightbulb in a paint can) in the “heat” outlet, and let magic happen.

From here there are many ways to go … 3-D printed cases are getting pretty popular. I’ve also seen folks come up with really nice setups from just a trip to the big-box hardware store. The sky is the limit!

“Hacking a Fridge”

This sort of setup relies on being able to directly turn on and off the compressor on the refrigerator. Normal modern fridges often are “frost free” which is accomplished by using a timer and a small heater on the coils to defrost the tubes. It should be obvious that this would not work well for this application. As described here we use what ends up being a “switched power cord” and leaving the fridge wiring intact. There are MUCH more elaborate ways to do this. One of the best write-ups is on the original BrewPi website under Fridge Hacking Guide.

If you do follow the instructions here, you will need a way to get the wiring for the sensors, heater and fan inside the fridge. These methods range from obvious (a kegerator has a hole on the top for the beer lines which may be used for our purposes) to the exceedingly elaborate (some people drill through the sides and use surface-mount electrical connectors.) If you do drill your fridge, make sure you know where the coolant lines are. Piercing one of these is a one-way ticket to the junkyard.

For the Masochists (or the truly paranoid)

(This article is written for BrewPi Legacy Remix version, it likely applies to other versions but there may be some differences.)

You’re here for one of a few reasons:

  • You’re just curious about how things work
  • You hate easy things and want to do this the most difficult way possible
  • You are exceeding (perhaps justifiably) paranoid and refuse to run scrips as root. Maybe starting at the bottom of this article is a good place to start?
  • You are one of those people that find some twisted satisfaction in running something named BrewPi on something other than a Raspberry Pi

We’re not here to judge (or am I silently judging you right now?), we’re just here to help. Just like the government. Here’s what you have to go through to replicate most of the scripting in the BPR tool set. Note that this only addresses a single-chamber setup. I’m not sure I feel like describing what has to be done to do multi-chamber but a smart person can figure it out from the information that’s out there for the Legacy BrewPi.

Finally before we dig in, these instructions are written for Debian-based Linux distributions (of which Raspbian is one.) If you use something else, chances are you already understand the differences.


The bootstrap especially does some checking which may not specifically be strictly required, but is highly recommended:

  • Check to see if the default password of ‘raspberry’ is still current for the ‘pi’ user. If so, prompt to change it.
  • Prompt to set the proper timezone. Since BrewPi works on schedules and the graph is of course time-based, having the proper system time is important. Yes, I could do some work to allow UTC and display in the user time zone … but why?
  • If the hostname is still ‘raspberrypi’, prompt to change it. More than a few folks have more than one Raspberry Pi, and being able to use a nice name like “brewpi.local” to get to the system is handy. Plus, you should never have two machines with the same name on the same network segment. It confuses anything with an ARP table (like your router.)

APT Repositories

Manipulation of APT repositories is required to support this product. This obviously needs to be done as root, however the repos are GPG signed so in theory there’s an added level of security.

As with any other apt packages, it is always good practice to refresh your local apt indexes before doing any installs, updates, or uninstalls. This command will re-synchronize the package index files from their sources. The indexes of available packages are fetched from the location(s) specified in /etc/apt/sources.list.

sudo apt update

There are some packages known to conflict with the solution as well; namely nginx and anything related to php5. This should not be a surprise since we use apache2 as a web server and nginx is a web server itself. Yes a crafty person can make them coexist, if you’re that crafty you don’t need my tutorials. Some of the packages I suggest to reinstall will be reinstalled again with apache2 and that’s fine. The process may also suggest removing other packages which are included by dependency; remove those as well. To uninstall nginx, use the following command:

sudo apt remove libgd-tools, fcgiwrap, nginx-doc, ssl-cert, fontconfig-config, fonts-dejavu-core, libfontconfig1, libgd3, libjbig0, libnginx-mod-http-auth-pam, libnginx-mod-http-dav-ext, libnginx-mod-http-echo, libnginx-mod-http-geoip, libnginx-mod-http-image-filter, libnginx-mod-http-subs-filter, libnginx-mod-http-upstream-fair, libnginx-mod-http-xslt-filter, libnginx-mod-mail, libnginx-mod-stream, libtiff5, libwebp6, libxpm4, libxslt1.1, nginx, nginx-common, nginx-full

To uninstall php5, I could give you a script but you’re here because you either don’t trust my scripts or you can’t use them for some reason. You can use the following command to find php5 packages which may be installed:

dpkg --get-selections | awk '{ print $1 }' | grep 'php5'

You would have to uninstall each of the returned package names with:

sudo apt remove {package name}

Now you need to install a series of APT repos. Here’s the command you would run to install all repos used in this product:

sudo apt get git arduino-core git-core pastebinit build-essential apache2 libapache2-mod-php php-cli php-common php-cgi php php-mbstring python-dev python-pip python-configobj php-xml

Pip Installs Packages (pip)

In addition to the apt packages, several additional python packages will be necessary. These are installed with pip:

 sudo pip install pyserial psutil simplejson configobj gitpython --upgrade 

User Setup

BrewPi runs as its own (now passwordless) user. Here we create the brewpi user and add it to the dialout, sudo and www-data groups:

useradd brewpi -m -G dialout,sudo,www-data

Next we add the ‘pi’ user (or whatever user you normally use to the www-data and brewpi groups:

usermod -a -G www-data,brewpi pi

Clone git Repositories

There’s four repositories that make up this product:

  • BrewPi-Tools-Remix – The toolset that this article replaces, so we won’t clone it here
  • BrewPi-Script-Remix – The core Python scripts which communicate with the Arduino and website
  • BrewPi-WWW-Remix – The PHP website which forms the user interface
  • BrewPi-Firmware-Remix – This repository does not need to be cloned, one need only download the current compiled firmware

Make sure the /home/brewpi directory exists and is empty. Clone the scripts as the brewpi user with the following command:

sudo -u brewpi git clone -b master --single-branch /home/brewpi

The web root should be /var/www/html but new versions may change that. Clean out that directory (it probably has a default index.html file there) and clone the website as the www-data user with the following command:

sudo -u www-data git clone -b master --single-branch /var/www/html 

Set Permissions

One of the more common solutions to a whole slew of issues is setting the permissions correctly. There is a script for this in:


If you are still needing or wanting to proceed manually, the following commands are issued:

chown -R www-data:www-data /var/www/html
find /var/www/html -type d -exec chmod 2770 {} \;
find /var/www/html -type f -exec chmod 640 {} \;
find /var/www/html/data -type f -exec chmod 660 {} \;
find /var/www/html -type f -name ".json" -exec chmod 660 {} \;
chown -R brewpi:brewpi /home/brewpi
find /home/brewpi -type d -exec chmod 775 {} \;
find /home/brewpi -type f -exec chmod 660 {} \;
find /home/brewpi -type f -regex "..(py|sh)" -exec chmod 770 {} \;
find /home/brewpi/logs -type f -iname "*.txt" -exec chmod 777 {} \;
find /home/brewpi/settings -type f -exec chmod 664 {} \;

Arduino Firmware

You can download the precompiled firmware (sorry, not going to go into how to compile it on your own here) from the GitHub repo. For instance here’s how to download the latest Arduino Uno firmware:

curl -O

You would now flash your connected Arduino with the following command. Be sure to update the port (following the ‘-P’) with the port where your Arduino resides:

avrdude -F -e -p atmega328p -c arduino -b 115200 -P /dev/ttyACM1 -U flash:w:"brewpi-arduino-uno-revC-0_2_10.hex" -C /usr/share/arduino/hardware/tools/avrdude.con

Daemon Unit Files

BrewPi and a checker for the WiFi connection run as a systemd daemon. The following files must be placed in the /etc/systemd/system directory. The first is named brewpi.service and contains the following text:

Description=BrewPi service for: brewpi

ExecStart=/bin/bash /home/brewpi/utils/ -d


Change permissions on the file, enable and start the service with the following commands:

sudo chown root:root /etc/systemd/system/brewpi.service
sudo sudo chmod 0644 /etc/systemd/system/brewpi.service
sudo systemctl daemon-reload
sudo systemctl enable brewpi
sudo systemctl start brewpi

The (optional) WiFi check file should be saved as wificheck.service and it contains:

Description=BrewPi service for: wificheck
ExecStart=/bin/bash /home/brewpi/utils/ -d

And as with the brewpi daemon, set permissions, install and start it with the following commands:

sudo chown root:root /etc/systemd/system/wificheck.service
sudo sudo chmod 0644 /etc/systemd/system/wificheck.service
sudo systemctl daemon-reload
sudo systemctl enable wificheck
sudo systemctl start wificheck

Work Complete & Final Thoughts

In theory, you should now have a working BrewPi Remix running in single chamber mode. I will however leave you with some final thoughts.

If you are one of those folks who got here and followed these instructions out of some sense of increased security by not running my install scripts I’ve got bad news for you. You are still running scripts from some random person on the Internet and some start as root.

With thanks to the folks at, I’m going to paraphrase a few of their sentences:

Using curl|bash or curl|sudo bash certainly seems insecure. To anyone with a basic understanding of Unix, the construction makes it really obvious: This command will give the named web site direct access to your system, with the ability to do anything that you could do. This feels very wrong: We should be able to install software without giving the developers full access to our systems, right?

I would be the first to agree that software you install should not be automatically fully trusted. Unfortunately, however, traditional Unix software is always granted the full authority of the user who runs it (and in the case of a stock Raspbian OS this implies passwordless sudo). When you install software on Linux, no matter what package manager you use, you are giving that software permission to act as you. Most package managers will even execute scripts from the package at install time – as root. So in reality, although curl|bash looks scary, it’s really just laying bare the reality that applies to every popular package manager out there: anything you install can pwn you.

If you wish to install any software without giving it full access to your system, you must install it on a dedicated machine, VM, or (perhaps, with caveats) an isolated user account. In truth it’s more work than a lot of people want to deal with and in my experience people spend a lot more time complaining about it than actually taking steps to be secure.

The reality is this:

  • This is free software and you are invited to not run it if you are that concerned. I’d argue however that even the most paranoid among you have downloaded and run applications from the Internet with no additional security. At best, maybe you scanned it for viruses, but I’d be willing to bet a normal home user would not perform a source-code scan. If you are a person who really does a source-code scan, this is all written in bash, PHP, Python and the firmware in a proprietary C-ish language. It’s all there and all able to be downloaded freely and handled however you wish under the terms of the GNU General Public License.
  • This is intended to be run on dedicated hardware. A Raspberry Pi is really perfect for this and a Pi Zero W is about $20. There’s no reason to try to run this on some other rig on which you do other things that could be compromised by rogue code.
  • The last significant vector at risk here is the network to which the BrewPi machine is attached. If you have IoT devices, surely you have a separate wireless LAN segment for them? Put this there. Tom has a great article about IoT security. You can also choose to not have your BrewPi connected to your home network at all. Sure you lose some functionality, but you can always disconnect the network and just use it with a local keyboard, mouse and monitor.

I’m not making fun of people displaying a healthy dose of paranoia. At last count I am tracking 552 website credential pairs, all using unique highly complex passwords. Yes that’s right, I have over 500 passwords to keep track of. In addition I use two-factor whenever possible. Believe me when I say I am a fan of security. Sometimes though you gotta pick your fights and mitigate risk when you do.

One last word: As a fan of security I do have several ideas how to make this application more secure. I don’t have a schedule and nobody is paying for this so who knows what I’ll get done. Stay tuned though, surely the battle will be won in small skirmishes.

BrewPi Remix Install

This is my fork of the original BrewPi Project. If you are looking for the original, please click here.

BrewPi Legacy Remix runs on a Raspberry Pi, communicating with an Arduino. Despite the original creators no longer actively supporting BrewPi on Arduino, and despite the Arduino being arguably one of the least capable controllers on the market, BrewPi on Arduino still has an amazing following among home brewers. When I last checked there were 7473 posts in this thread on since March 19, 2014 when @FuzzeWuzze started the thread.

Before we proceed, a huge thank you to Elco Jacobs, without whom none of this would be possible.

Please also check Assumptions and Proceedings before continuing if you are not starting with a bone-stock fresh install of Raspbian on your Raspberry Pi.

To begin installing BrewPi, you need only issue the following command in a terminal window or via ssh on your Internet-connected Raspberry Pi:

curl -L | sudo bash

or the underlying link:

curl -L | sudo bash

Both of these are the same, I just created a short URL to make it easier for you. Some folks prefer not to be redirected, so the regular link is there as well

If you have a broken installation and/or need to run the uninstaller without BrewPi being installed correctly for some reason, you may use:

curl -L | sudo bash

If you’d like even more, here’s a YouTube video showing the entire process on version 0.5.1:

If you have questions, please read the FAQ.

Step by step instructions, with descriptions of each step, are being developed. I do however think each step has enough instructions to get the average person going if you just slow down and read them.

If you hate the idea of doing something the easy way, or if you for some reason need to install manually, see my post: “For the Masochists.”

Known issues

You can view or log new issues via the links below (when in doubt, just use the first link):

NameKnown Issues
Install and uninstall toolsIssues List
Python scripts supporting BrewPi
Issues List
Website filesIssues List
Arduino firmwareIssues List

Headless Raspberry Pi

Note: If you are here for instructions related to the “Headless Pi” application for preparing SD cards, you can skip down to that section.

What is “headless?” A headless computer that has been configured to operate without a keyboard, monitor and mouse. If you are a typical home computer user, you might wonder how this is possible, and why a person would want to do that.

Well, the Raspberry Pi is unique in it’s form factor. A fairly standard case creates a package that’s a whopping 5.5 x 5.1 x 1.4 inches. I have old rollerball mice that are larger than that. Something of this size is perfect for many applications and projects including media centers and console gaming. But, if you have to add a monitor, mouse and keyboard; it’s no longer so small and unobtrusive. Some people have been very creative with cases for the Pi; one person even put a Raspberry Pi Zero in a Tic Tac® box.

A Raspberry Pi Zero in a Tic Tac® case

There is no need to have a monitor, mouse and keyboard plugged into the Raspberry Pi; it can be operated quite easily and effectively as a headless system. In days past, large Unix systems sat in a room the end user would never hope to see, and they were accessed from a terminal like this one:

The DEC VT100, a widely emulated computer terminal

That’s pretty sexy, right? I’d actually love to have one of those as a conversation piece.

Seasoned users of Unix/Linux/variants use a program called a terminal emulator to access their servers from their workstations. The most well known (and FREE) terminal emulator for Windows users is PuTTY. It allows you to access your Raspberry Pi over the network, in a secure fashion, without needing to tear apart your gaming rig for a monitor, mouse or keyboard.

I can hear you thinking right about now: “But I don’t know how to type all those commands and stuff, I’m not a Unix person!” Fear not. I led you here, sir, for I am Spartacus. I can step ANYONE through this. Still don’t believe me? How about if I tell you that you can use a graphical interface on your Raspberry Pi instead while still on a headless Raspberry Pi? Graphical application access is done using what’s called the X window (not “Windows”) system – and is available over the network. More geekery that you don’t understand? I will make it easy for you to understand.

A modern example of a graphical user interface using X11 and KDE

I can see now you want to believe. When I am done you WILL believe.

The only physical connection that is absolutely required for your Raspberry Pi is power. Everything else is optional and we will do without any of that needless clutter. Let’s get started!

Required Hardware

You don’t need much to get started, and it’s not going to be very expensive. Here are some recommendations:

  • A Raspberry Pi bare board – I recommend the new Raspberry Pi 3 B+ unless you already have one laying around.
  • A suitable power supply – The CanaKit 2.5A Raspberry Pi 3 B+ Power Supply with PiSwitch is a good one. Many old phone chargers will work after a fashion, but they are often not capable of delivering the full power without a voltage drop. This can cause unexpected reboots and sometimes SD card corruption. Do NOT use a power switch like this (or heavens forbid unplug your Pi) without issuing the system a shutdown command. You have been warned.
  • A good micro SD card – You will only need a 4GB card if you are doing this for a BrewPi and will not use a graphical interface. I recommend at least an 8GB card if you will use the full Raspbian distribution. You want one from a reputable manufacturer rated as Class 10 UHS 1. They are getting so cheap now, there’s few reasons not to get a larger one like this Samsung 32GB. This one also comes with a standard SD card adapter which will allow you to directly plug it in many computers with a standard SD Card slot.
  • An SD USB adapter – If your computer does not have an SD Card slot, you will need a way to connect your SD card to your computer. I have and like this Rocketek Aluminum USB 3.0 Portable Memory Card Reader Adapter for Micro SD Card. It’s small, and it’s aluminum which helps it to dissipate heat (these things heat up when writing.)
  • (Optional) A Case for your Raspberry PI – When we say “bare board” that’s exactly what we mean. A case is almost a must-have, but some people get very creative (like the Tic Tac® box shown above) or whatever they have laying around. I actually came up blank when looking for a “entry-level” case for the Pi 3 B+. As you shop, just be aware there are differences between the boards, and you need to get the right one for the board you have/are buying.

If you don’t have any of the above and you are just looking for a kit to get you started, CanaKit sells the Raspberry Pi 3 B+ Starter Kit for $79.99, which includes:

  • Made in UK Raspberry Pi 3 B+
  • 32 GB Samsung EVO+ Micro SD Card (Class 10)
  • 2.5A Raspberry Pi 3 B+ Power Supply with PiSwitch
  • Raspberry Pi 3 B+ Case
  • HDMI Cable
  • 2 x Heat Sinks

Want to start even smaller? The Raspberry Pi Zero W is a single-processor (versus the 3 B+ having a quad-core processor) WiFi-enabled board that’s perfect if you just want to dip the tip of your big toe in. Amazon has the CanaKit Raspberry Pi Zero W (Wireless) Complete Starter Kit – 16 GB Edition for $32.99 which includes a case, SD card, power supply, everything you need to get going.

Aside from my expectation that you have a computer to start with (you are reading this somehow), and that you either have wireless (preferred) or wired Ethernet available; that’s really it.

Required Software

The software you will need comes in two types: software for your current computer which I will call “client;” and the OS for your Raspberry Pi which from now on we’ll call “server.”

Client Software

There’s two required software packages you will need, and one optional. I am listing Windows versions of these tools because that’s what I am using. If you use a Mac you are already used to figuring out some things on your own. Sorry, but you’re probably better at it than I am. Here’s your shopping list:

  • PuTTY – Terminal Emulator – You will use this to communicate with and control (at least at first) your new Raspberry Pi. Download it from the author’s website and install it on your PC. There are other Terminal Emulators, but I’m not going to go into them because this one really is the de facto standard as far as I’m concerned. There are a lot of different packages listed on that page. Up top, it says “MSI (‘Windows Installer’)”, grab one of those. If you don’t know if you need 32 or 64-bit, just grab 32-bit. For our purposes, there are no differences.
  • SD Card Writer – Here I’ll list a few choices;
    • Raspberry Pi Imager – My new preferred imaging solution for a Raspberry Pi. Well-integrated into the Raspberry Pi ecosystem, as a product from should be. No need to download the OS image separately when using this product.
    • balenaEtcher – A very well-thought-out program and easy to use. The tutorial will be written following the process for this piece of software. Optionally, you can use:
    • Win 32 Disk Imager – This is an older program and not as fully-featured. It also has some “quirks” to its use. Between the two, however, it’s the one which you can use to back up your SD card later on. I suggest even if you want to do this (and there are good reasons to do so,) that you start with balenaEtcher for your first go at it.
  • (optional) RealVNC Viewer – Connects to the Raspberry Pi to use a graphical interface.

Download and install PuTTY, Raspberry Pi Imager, and (optionally) VNC Viewer and we can move on.

Server Image

This is written around the Raspbian OS. Just like there are different versions of Windows 10 (Home, Pro, Enterprise), there are different versions of Raspbian. The current release is called “Buster” and the Raspbian Buster distributions are based on Debian Linux 10 (Buster). Three different flavors of Raspbian Buster are available for the Raspberry Pi. All are available from the same download page.

Note: If you are using the Raspberry Pi Imager, you can skip this step and head down to Software Installation and Configuration.

Your choices on the image download page will be

  • Raspbian Buster Full – Stretch with a full-featured desktop interface and a handful of applications you may be interested in. If you will be using your Pi for something other than just BrewPi for instance, or just want to play around, you can start with this. It’s a little over 5GB so you will want a larger SD card with this one. I recommend at least 8GB and chances are you will want more.
  • Raspbian Buster with desktop – Same PIXEL desktop with less ancillary applications. I’ve never actually figured out the differences because I never use a graphical desktop. It’s a little over 3GB in size so you can use a smaller card.
  • Raspbian Buster Lite – The slimmest of all the distributions at just under 2GB. I use this distribution effectively even on my 4GB cards. You do not need a graphical interface to run the BrewPi server

Unless you know what “Torrent” is, chose the “Download Zip” option for the package you chose.

Get one of these downloaded and we’ll get going. To follow this to the end and use a graphical interface, you will want either the “Raspbian with Desktop” or “Full.” Honestly, I rarely use a graphical desktop anymore since it consumes resources and I don’t ever actually work on the Raspberry Pi (I use it as a web server most often.) You take care of your needs and I’ll get you there.

Software Installation and Configuration

So now you have your Raspbian image, you have PuTTY and Raspberry Pi Imager (and probably VNC Viewer) installed, right? You are as prepared as you will get, might as well jump in before you chicken out.

Addundum for RPi Disk Imager

Since writing this article, the Raspberry Pi Imager has released support to set the following items:

  • Hostname
  • Enable SSH
  • Change password
  • Configure Wifi
  • Set locale

Simply hold down Shit + Control and press the “X” key to view this menu. I have NO idea why this is not more prominently featured.

Create the Boot Media

Go ahead and execute Raspberry Pi Imager You are presented with a window that should look a lot like this one:

Raspberry Pi Imager at startup

There’s not a lot of options here, which is good:

  • Step 1: Operating System – Choose OS – Here you will select your preferred flavor. I recommend the first selection; Raspbian. You are free to choose Raspbian (other) and select between Full and Lite.
  • Step 2: SD Card – Choose SD Card – If your SD card is not plugged in, go ahead and plug it in now. You may see a pop-up about the card not being formatted (here and further in the instructions.) In all cases just hit “Cancel” and move on. You will see that unless you have more than one drive the software will just select it for you. You can change the selection if you really do have more than one plugged in, or go to the next step.
Example Pop-Up during process
  • Step 3: Write – Really, that’s it. The software will go through, flash the drive and then verify it. You may hear some “dings” from your computer as the new drive(s) are detected and mounted. You will likely see those pop-ups again. Just hit “Cancel” if they do pop up and wait for the process to be complete.
Raspberry Pi Imager during the SD write process

When writing the drive has been completed, you will see a window like this:

Writing Complete.

It is safe at this point to eject/remove the SD card. If you are hell-bent on not going headless, you are done. Plug the SD card into your Raspberry Pi connected to a keyboard, monitor and mouse, and plug it in. If you really want to hang out with the cool kids, keep reading ….

Configure the Boot Media

(This is deprecated since updating the imaging tool. See: Addundum for RPi Disk Imager above.

The SD card is in your hand, plug it right back into your computer again. Again you will likely see a pop-up about an unformatted drive, again hit “Cancel” and move on. (If you did not remove and re-insert the card, you need to do so now.)

At this point, you may open Windows File Explorer. This is informational only, you need not do anything yet.

In the list of drives on the left (you may have to scroll down, and/or expand the choices under “This PC”, you sill see two additional drives called “USB Drive” and “boot.” The drive letters may be different but you definitely want to select the one named “boot.” This is one of the two partitions created on the SD card; “boot” is an MS-DOS type partition and “USB Drive” shows as unformatted but is actually a Linux partition.

Files in the ‘boot’ Partition of a Raspbian SD Card

Within the “boot” partition (here the E: drive, may be different on your computer), you are going to create two files in a little bit:

  • ssh – A file with no file extension named “ssh.” It can be and should be left empty. It gets deleted during the first boot process. It serves to tell Raspbian to turn configure the ssh daemon (similar to a Windows service) which is how we will connect.
  • wpa-supplicant.conf – This one is semi-optional. If you are using an actual Ethernet cable then it’s not needed at all. If you plan to use WiFi it’s less optional. It will contain the configuration for your wireless networking, allowing Raspbian to connect on first boot.

Now, referring to the window up there, note that some of the files have extensions of “.dtb” and “.bin.” Windows, by default, hides file extensions for files it thinks it knows like text files (*.txt) and Microsoft Word documents (*.doc). There’s a couple ways to go about creating these two files we need, one of which has no extension at all and one of which has an extension of .conf. There’s more than a few ways to do this, I’ll give you a couple:

There are two ways to proceed now. Either choose the easy way, immediately below or the hard way further down the page.

The Easy Way – Using “Headless Pi”

I created a small application which will help you with this. You may download it here (for free of course):

  • Headless Pi – A Windows application to assist setting up a new Raspberry Pi SD card for headless operation.
  • Headless Pi Source Code – Visual Basic 2017 project released under the GNU GPL (you only need this if you would like to compile the above file for yourself).

With your SD card inserted, go ahead and execute the Headless Pi executable. If you have issues, check the release page for an installer-based version. It should run without installation on current versions of Windows. There are only a couple ways to mess this up:

No card inserted – You will see this error if you have not inserted a Raspberry Pi SD card. If you just finished writing the card, you forgot to pull it out and re-insert it. Do so, then re-run the application:

No Card Detected

Multiple cards detected – You will see this error if you have more than one Raspberry Pi SD card inserted. Remove all but one and re-run the application:

Multiple Cards Detected

When you execute the program it will auto-detect your SD card. Look at the “Target Device” label towards the bottom and visually verify that this is correct. This program should err on the side of safety, but this is free software and you get what you pay for so this one is on you.

After you have verified the application is pointing towards the correct mount point, you have two items to configure:

Headless Pi UI Screen
  • SSH – This is a checkbox to enable (or not) SSH on the Raspberry Pi. When you check the box the application will write a file named “ssh” on the /boot partition which enables ssh on first boot. When you un-check the box, this file will be removed. Unless you don’t need ssh (and if that’s the case I have no idea why you are reading this) you will want to check this.
  • On the Go – This checkbox will enable configuration for On The Go (OTG) functionality. This allows a Raspberry Pi Zero or Zero W to be configured as an Ethernet device. It connects to (and is powered by) the host system, using the host’s networking. More details can be found here.
  • Wireless – When you check this box the remaining configuration items will become enabled. You need to configure the following:
    • Country Code – Select the proper country code for where you live. For instance, if you are in the US, scroll down to “United States” or begin typing your country name and the list will scroll.
    • SSID – This stands for “Service Set Identifier” and is the name of your wireless network. This must be typed correctly in order for it to work so be double sure it is correct. The SSID is a case-sensitive text string that can be as long as 32 characters consisting of letters and/or numbers. Within those rules, the SSID can say anything. You will need to refer to your wireless router manufacturer or broadband provider for this information.
    • Password – Your wireless network password, obviously if this is not correct you will not connect. The password is not blanked out so you will be able to verify it as you type.
    • Known Networks (new in 3.1.0) – This box will list locally configured wireless networks, and if it is able, to populate the UI with that information to save you some typing (and possible mistakes.)
  • Write Supplicant File – Once you have these four fields filled out and you are sure they are correct, the “Write Supplicant File” button will be enabled. Clicking this button will write out a properly formatted wpa_supplicant.conf file to your SD card. Clicking multiple times will simply overwrite the file so if you make a mistake you can correct it and try again. If you un-check the box again it will remove the file.

If you use the “Eject and Exit” button, the program will attempt to eject the USB card programmatically so you may safely remove it. If you do not with to do this, use the red “X” on the top-right corner. If you do that, be sure to use the Windows controls to eject the card before you remove it to prevent corruption.

The Hard Way – Using “Notepad++”

You can download the free program “Notepad++” which is a replacement for the Windows Notepad. It is quite a bit more capable however. I won’t review anything other than what you will need to know in order to get through this particular set of instructions, but a little review of it will probably result in you never using Windows Notepad ever again.

Go ahead and start up Notepad++ and close the first tab you see which is the changelog for the current version. Then, change the end of line (EOL) type to “Unix” by selecting Edit > EOL Conversion > Unix (LF).

Change File Type to Unix

Since you are currently looking at a blank file, and the “ssh” file does not need anything in it. select File > Save As> and navigate to the SD card’s boot partition. For a name use ssh. (notice the trailing period, this is critical) and click “Save.”

Save ‘ssh’ File

Next, you can paste in the following text as a start point for your wpa_supplicant.conf file:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev


Change the following items to values appropriate for your use:

  • Country – Change the country code to the proper two-letter code for your country. You can find a list of country codes here.
  • SSID – This stands for “Service Set Identifier” and is the name of your wireless network. This must be typed correctly in order for it to work so be double sure it is correct. The SSID is a case-sensitive text string that can be as long as 32 characters consisting of letters and/or numbers. Within those rules, the SSID can say anything. You will need to refer to your wireless router manufacturer or broadband provider for this information.
  • PSK – Your wireless network password, obviously if this is not correct you will not connect.

Be sure that you retain the double-quote mark around SID and PSK. There should be no spaces between the keywords, the equals sign, and the value. Go ahead and File > Save As and save the file as “wpa_supplicant.conf” to the same place as you saved the “ssh” file.

Save ‘wpa_supplicant.conf’ File

Eject Media

Whenever you remove any USB storage, you should always eject it when you are finished. This allows Windows to flush any write cache and close any files it has open. Failing to do this will eventually result in a corrupt device.

To do this, look over in your system tray (the right side of your start bar where the clock is) and look for the USB device icon. Generally you will have to hit the little up arrow (^) to see it.

USB Control Icon

Click on the icon, and select the line that allows you to eject the card reader.

Eject Card Reader

At this point you have your SD card in your hand, all prepped, and ready to go.

Start It Up

At this point you should insert the SD card into your Raspberry Pi, and go ahead and start it up. If you have done things correctly, it will show up on the network and allow you to connect via SSH.

First-Time Connect

Now that your Raspberry Pi is sitting there with it’s little LEDs lit up, it really is doing something. We’ll now go ahead and connect via PuTTY which you should already have downloaded. Go ahead and start up PuTTY and you will see something like the following:

PuTTY Opening Screen

Type in the name of the computer to which you will connect in the “Host Name” field. Since this is the first time you are touching your Pi, the hostname is “raspberrypi.” Follow that with “.local” so that your computer will know how to find it. Optionally, you can prepend the hostname with the username you wish to use. A Raspberry Pi only has one user by default, named “pi.” So, the full entry in the “Host Name” field will be “pi@raspberrypi.local”.

You may optionally give your connection settings a name by typing that name in the “Saved Sessions” box, then clicking “Save.” When you are ready click “Open” to make your first connection. Since this is the first time you will have connected to your Pi, PuTTY will complain that it does not recognize the SSH key. This is a safety item; once saved the first time PuTTY will compare the saved key to the key the server presents in order to make sure your connection is not hijacked by some bad actor. (A bad actor in this context is “anyone on the Internet who means to do you harm”, not a reference to Keanu Reaves.)

PuTTY Security Alert

If you read the very scary text, it will tell you the only safe choice is to “Cancel.” If you hit cancel, you will for sure be safe, but you will also not connect. This first time go ahead and hit “Yes” and the new key will be entered into the system to be checked against next time. Do that, and PuTTY will connect and show you the terminal window.

When presented with the login screen enter the username “pi” (if you did not put the username in the connection string) and then the password. The default password for Raspbian is “raspberry”. If you have followed along correctly, you’ll now be looking at the prompt, logged into your new Pi. The future is looking bright!

Raspberry Pi Initial Login Screen

Optional – Enable RealVNC (graphical) Access

If you selected one of the desktop distributions (anything but “lite”) you can now enable RealVNC access to the Raspbian Desktop. To do this, enter:

sudo raspi-config

Go to “Interfacing Options” > “VNC” > When presented with the question “Would you like the VNC server to be enabled?” select “Yes“. At this point you may or may not need to actually start the daemon (Linux-speak for a service). You can do that now and it won’t hurt if it’s already running:

sudo systemctl start vncserver-x11-serviced

I should point out here that there actually needs to be a desktop running, even if you are not using it (like, no monitor plugged in.) If you are not sure about this, get back in Raspberry Pi Config:

sudo raspi-config

Select: “Boot Options” > “Desktop / CLI” > “Desktop Autologin” or “Desktop” (which will prompt for a login.) This change requires a reboot most often, so go ahead and do so just to be sure:

sudo reboot

Now, go ahead and run the local copy of RealVNC Viewer you downloaded and installed previously (probably just called “VNC Viewer” on your computer).

RealVNC Viewer Window

On the top of the window in the address bar, enter the host name to which we will connect. Just as with the PuTTY connection, use the name raspberrypi.local and hit “enter.” You will see a security notification if this is the first time you have tried to connect to the Pi:

VNC Server Not Recognized Pop-Up

On the chance you are following this tutorial after having gone through it before, you may see an even more scary pop-up because the signature of your new pi will not match the signature of “raspberrypi” from the last time. You can accept that and continue past if you know that to be the case.

Next, you will be presented with the Authentication prompt. Enter “pi” as your username, and the default “raspberry” for the password. Optionally, you can check the box to remember the password. When you hit “Ok” you should see the new desktop.

Authentication Pop-Up

If you see a black box telling you that “Cannot currently show the desktop”, it means that you need to enable the desktop as detailed a few blocks above.

On your first connect if you had not previously changed the password via SSH, you will de a warning that you have SSH enabled and the default Pi password. At some point you will want to change this. If you are reading this for a BrewPi setup, no need to worry about that right now.

Raspberry Pi Desktop

When you clear that screen, again, if this is your first time, you will see a prompt to set some additional items up.

Initial Setup Screen

Here you may choose to go through the setup screens, or if you will be moving on to install BrewPi for instance you can close the window. If you do go through these screens, you will be guided through setup for:

  • Localization settings
  • Changing default Password
  • Wireless setup
  • Updating software
  • Reboot

Be careful about the wireless setup which it will attempt to take you though. If you mess it up, and if you are only connected via the network, you will lose control of your Pi and have to start over (or go find a keyboard, monitor and mouse to connect.)

Work Complete

You’re done! I told you this was not going to be hard. It takes way longer to read these instructions than it takes to implement them.

Setting up Raspberry Pi (Stretch)

Note:  This page is largely deprecated, but I am leaving it here just in case.  To get BrewPi running now, follow these two pages:

  • Off With Her Head! – Headless Raspberry Pi setup.  You can just follow along and skip the wpa_supplicant.conf and .ssh setup if you don’t care about headless operation.
  • BrewPi Remix Install – Instructions to set up the new remix of BrewPi which supports contemporary Raspbian versions.

These instructions were created for the new Raspbian Stretch image. They assume intermediate knowledge of your chosen home computing system, as well as familiarity with using SSH and other networking tools.  These instructions assume a “headless” operation – that no monitor, keyboard, or mouse are needed.

These are the general steps I follow when preparing a new Raspberry Pi image for use with BrewPi (these are specifically deprecated. See the headless setup section in Off With Her Head! The sections below which are struck through may be skipped after following the instructions on that page.)

  • Download your new Raspbian image: (get the full version if this is your first time, not the “Lite” one)
  • Install the image on your SD card:
  • While the SD Card is still connected to your computer, configure the image for headless operation:
    • Locate the /Boot/ partition on the SD Card.  In Windows this will be a new drive letter with the volume name “boot (X:)” where “X” is the new drive letter.
    • Create a new file in the root of this drive named “ssh” (no extension.)   This will enable SSH so that you can connect to the RaspberryPi immediately upon first boot.
    • Create a file called “wpa_supplicant.conf” on the root of the boot partition of the SD card.  In it, place the following information:

Replace “SSID” with the SSID of your local wireless network (leave it in quotes), and “PASSWORD” with your wireless network (leave it in quotes also) .  This will connect your Raspberry Pi to your wireless network automatically upon startup so double-check the SSID and password.

NOTE:  If you do not have Windows Explorer configured to show file extensions, it is possible to have a hidden “.txt” or other extension on the files.

  • Insert the SD card and boot.  Your Raspberry Pi should now be accessible on the network via PuTTY.
  • Use PuTTY to SSH to “raspberrypi.local” with the username “pi” and password “raspberry”.

NOTE:  If you receive an error stating that the host could not be found, it may be that Bonjour services are not installed on your local computer (assuming you use Windows.)  You can obtain Bonjour either by installing iTunes or with the stand-alone installer found here. Bonjour also enables accessing the BrewPi web page with  “{servername}.local” without having to apply a static IP or remember an IP address.  If you use Linux you will need libavahi; under Mac, Bonjour should be installed with the base OS.

  • Enter the command “sudo raspi-config” to execute Raspbian configuration as the root user.
  • Complete configuration:
    • Immediately “Change User Password” to a secure one.
    • Change “Hostname” (I suggest: “brewpi”, this will be assumed through all documentation on this site.)
    • “Localisation Options”
      • “Change Timezone” to proper timezone for your area.
      • “Change Wi-Fi Country” to proper country fr your area.
  • Select <Finish> and reboot.
  • After the Pi reboots, SSH to “brewpi.local” with the username “pi” and password you set previously.
  • Issue the following commands to ensure your software is up to date:
sudo apt-get update && sudo apt-get upgrade -y
  • Issue the following commands to clean local repositories, deleting space used by downloaded archives:
sudo apt-get clean && sudo apt-get autoclean
  • Issue the following command to update the firmware of your Raspberry Pi:
sudo PRUNE_MODULES=1 RPI_REBOOT=1 rpi-update

If the command updated your firmware it will reboot automatically. If not; go ahead and reboot anyway with:

sudo reboot

That’s it!

Add Reboot and Shutdown Buttons

Note: I do not recommend this approach. It requires granting higher than typical permissions to a user which is generally very limited.

Concept originally posted by “MBasile” at:

As you know or will soon learn, the Raspberry Pi does not deal well with being powered off without first being shut down.  These minor changes will give you the ability to reboot or shutdown your Raspberry Pi through the BrewPi web interface rather than needing to ssh in.

  1. Grant access to the web user to perform shutdown and reboots:
    sudo sh -c "echo \"www-data ALL=NOPASSWD: /sbin/reboot, /sbin/shutdown\" >> /etc/sudoers"
  2. Create two new PHP pages which will perform the shutdown and reboot functions:
    sudo echo "<?php system('sudo /sbin/reboot'); ?>" > "/var/www/html/reboot.php"
    sudo chmod 674 /var/www/html/reboot.php
    sudo chown www-data:www-data /var/www/html/reboot.php
    sudo echo "<?php system('sudo /sbin/shutdown -h now'); ?>" > "/var/www/html/shutdown.php"
    sudo chmod 674 /var/www/html/shutdown.php
    sudo chown www-data:www-data /var/www/html/shutdown.php
  3. Add the buttons to the Maintenance Panel (maintenance-panel.php) file:
    • At line 66 you will see this:
      <li><a href="#reprogram-arduino"><span>Reprogram <span class="boardMoniker">controller</span></span></a></li>

      Below that line add this:

      <li><a href="#shutdown"><span>Shutdown</span></a></li>
    • Append this block to the end of the file:
      <div id="shutdown">
       <script type="text/javascript">
       function shutdownonclick()
       shutdown_window ="shutdown.php",
       setTimeout("shutdown_window.close()", 2000);
       function rebootonclick()
       reboot_window ="reboot.php",
       setTimeout("reboot_window.close()", 2000);
       <button><a href="javascript: shutdownonclick()">Shutdown</a></button>
       <button><a href="javascript: rebootonclick()">Reboot</a></button>
  4. Test.

Removing Sulfur Smells from Perlick 650SS Faucets

by Lee Bussy; “LBussy” on

Update 7/20/20: A gentleman from Perlick reached out to me about this post. He’s informed me that as of May 2017, faucets in stock at Perlick were all 304 SS which eliminated this issue. To identify the newer 304SS taps, he shared:

There should be a date code laser-etched underneath the faucet body, so the date codes ending with “17C”, “18C”, “18D”, “19D”, or “20D” will be the all 304 stainless steel construction.

Perlick staff member (personal communication, July 20, 2020)

I want to thank Perlick for reaching out to provide this information.

What follows is the original article written circa 2016 when people were having this issue. Occasionally I have to re-passivate my taps, and it’s valuable as a method to passivate other items. What follows is the original post for reference purposes.

You will not wonder if it happened to you.  You will walk up to your tap, excited after a long day at work to pull a pint of your favorite cider or other beverage.  What comes out may knock you over.  The sulfur smell some people are experiencing from their Perlick 650SS taps is real, is unmistakable, and thankfully is avoidable.

What I present here is not new.  I learned about it in a thread on where members “agrazela” (Agrazela, 2016) and “sctcts” (C., 2016) summarized very succinctly what a lot of people had been discovering and sharing.  While these summaries were very good, I believe they were somewhat more technical in nature and assumed some advanced capabilities or knowledge at the very least of terminology not generally used by homebrewers.  I wanted to present in no uncertain terms exactly what a person needed to know to get rid of the issue once and for all.  If you can follow a cookbook, you can get rid of the smell following this write-up.

The Issue

With a characteristic rotten egg smell, hydrogen sulfide is a poison.  It is detectable at extremely low levels, with 50% of the population able to detect it at 0.47 parts per billion in the air (Iowa State University Extension, 2004).  With lethal doses beginning at 320 to 530 ppm (Lindenmann, et al., 2010), or 681 to 1128 times higher than the detectable level, it is exceedingly unlikely that anyone need worry about toxicity of H2S from their taps.

Our taps are made of stainless steel; a few of the parts are made of 303 stainless steel (C., 2016) [See note at beginning of article].  This is a form of stainless which is specially formulated to be easy to machine by virtue of an addition of sulfur and phosphorous (ESPI Metals, 2016).   All stainless steel is passivated after machining.  Passivating is a process intended to allow a thin film of oxidation to form on the surface which in turn protects the steel.  When this type of stainless steel is passivated with nitric acid, manganese is etched from the surface while allowing elemental sulfur to be retained (Shen, 2004).

This elemental sulfur on the surface of the stainless steel and within crevices formed by etching of the manganese is assumed to be the root of our issue.  Empirical evidence strongly backs this theory.   The theory continues that when a highly acidic liquid such as a some wines, kombucha, cider, or cleaners like Star San are left in contact with these surfaces, the elemental sulfur (S2-) combines with the free hydrogen ions (H+) provided by the acid to form H2S, to greatly offend our sensibilities.  Generally a few ounces through the tap are all that is required to flush the smell away.  The smell will continue to come back after the system has time to sit with the acidic liquid again.  Some suppliers have even gone so far as to recommend not using the 650SS for more acidic beverages (Adventures in Homebrewing, 2016).

Trial and error has led to the common belief that a single part, the handle lever, may be the only part responsible for all the trouble (Agrazela, 2016).  Since reports of the sulfur smell come only from the owners of the 650SS faucets, the parts unique to this faucet design are reasonable suspects.  We will target three parts within the faucet to be sure of our efficacy (C., 2016).

In order to rid the parts of the issue once and for all, the parts must be thoroughly cleaned, the sulfur deposits removed and the parts re-passivated.  These steps can be followed easily in one’s kitchen with a minimum of special equipment and ingredients.  Most homebrewers should possess the tools needed to get the job done.  The chemicals are available locally.

The Process

The faucets will be disassembled, cleaned, passivated and cleaned again.  The original process used to passivate the parts during manufacturing is assumed to have used nitric acid.  We will follow a process based on the citric acid passivation methods outlined in ASTM A967 (specifically, citric I) along with the recommendations by Shen (Shen, 2004).


You will want to procure the following in addition to normal household utensils:

In addition to these items you will need several non-reactive spoons or other utensils for portioning and stirring.  Most all tableware these days are stainless steel.  If you have any doubts about your utensils, gather glass or other lab grade pieces suitable for the task at hand.


Figure 1 (Perlick, 2014)

Do not completely disassemble the faucet.  Some of the O-rings and seals are more difficult to remove and will be damaged if you remove them.  Perlick recommends replacement of several of the O-rings if they are removed.  If your faucet has been in use, soak the faucet in warm cleaning solution for 1-2 minutes to help free the parts. If it is new, a dunk in warm water will help.

Refer to Figure 1 below.  Remove the tap handle if you still have one on the faucet.  Next, remove the handle jacket (1) from the handle lever.  Unscrew the compression bonnet (2) and remove it and the bearing cup (4) from the handle lever.  Lift upward on the handle lever (5a) and push back slightly to remove it from the faucet.  Set the handle lever aside, this is one of the parts you will be passivating.

The entire flow control assembly is referred to by callout 11 in the diagram.  Unscrew the flow control lever from the control barrel.  Unscrew the compression bonnet and remove.  Gently pull the control barrel from the body, noting the relationship between the pin on the end of the control barrel and the corresponding hole in the flow control compensator.

The control barrel has two O-rings.  These may be gently removed to ensure the entire surface of the control barrel is accessible for passivation. There are two schools of thought on removing these O-rings.  Some will remove them and some will recommend not risking damage to the O-rings believing that the solution will reach anywhere the beer will.  This is a personal decision and the implications and risks should be considered.

Set the flow control barrel aside, this is the second piece to be passivated.  At this point the flow-control compensator (9) should freely slide out of the rear of the faucet.  Removal of the coupling gasket (8) is not necessary.  The flow-control compensator is the third and final piece to be set aside to be passivated.

The Mix

Lye solution, especially as it gets hot, will cause severe burns to skin, eyes, and mucous membranes (Certified Lye, 2013).  It is a severe caustic substance and will ruin your day.  It is used in soap making and a lot of people use it safely every day with reasonable precautions, so have a look on the Internet for Lye Safety and have a good read before messing with it.  One such article is the Soap Queen’s Back to Basics: Lye Safety Guide (White, 2015).  Regardless, it is pretty nasty stuff so do yourself a favor and make this a beer-free endeavor.  You can RDWHAHB afterwards.

If you have at least two containers, prepare them ahead of time to make things go more smoothly.  If not there’s no time-critical nature to the process and you can do it as you go along.  In one of the containers prepare a 5% lye solution, in one prepare a 10% citric acid solution.  To prepare either solution, follow these steps:

  1. Don your safety gear (glasses & gloves at a minimum).
  2. Mark your container with the name of the solution you intend to make (5% Lye or 10% Citric).
  3. Place your container on your scale and tare the scale.
  4. Pour ~300 grams of distilled water into the container. The exact amount is not important, measuring it is.
  5. Multiply that weight by 0.05 if you are making the lye solution, and 0.10 if you are making the citric acid solution. g.: if you poured 312 grams of water and you are making the 5% lye solution:
    312g * 0.05 = 15.6g
  6. Tare the scale with a dry cup or plate. Measure that amount of the dry chemical (in this case 16g of lye) into the cup or plate.
  7. Pour the chemical into the water (NOT the other way around, EVER!) and stir until it is in solution. Lye dissolving into water will create heat.  Do not let the undissolved lye rest on the bottom of the container or it will create localized heat and potentially crack the container.  If stirred, this amount of lye will not create enough heat to cause a problem.  Do this in/over the sink in case of accidental spillage or breakage.
  8. Set the marked containers back from the edge of the counter to prevent accidents, and proceed.

You’ve completed the hardest part of the entire process.  You can reward yourself with a pat on the back and a deep breath of relief.  The rest is easy.

The Cook

First, give the parts a good cleaning with dishwashing detergent.  The initial lye wash is more than likely going to remove almost anything that is on the parts, but I don’t know if it will remove keg lube for instance.  Taking a few extra seconds is pretty cheap insurance.  Use a brush to get the nooks and crannies.  Once the parts are clean, place them in a dish or other container with your cheap alcohol which is used as a wetting solution.

Next, raise the temperature of your first 5% lye solution to between 160° and 180° F (70° and 80° C).  I found this easiest to do in a double-boiler setup.  I first raised a pot of water to boiling and then placed the flask containing the solution in the pot while turning the heat to low.  Keep the outer water at 170° F (75° C) and swirl occasionally.   It will take a few minutes for the temperatures to equalize so you can either measure the inner container, or give it about 5 minutes arbitrarily.  After it has reached temp (or after 5 minutes) set your timer for 30 minutes and drop in the parts carefully to avoid splashing.  Stir or swirl occasionally.

After 30 minutes has passed, fish or strain out your parts and give the parts a quick rinse with distilled water.  Drop them back in the alcohol wetting solution as you prepare the next bath.  Repeat this process with the 10% citric acid solution at 150° F (65° C) for 30 minutes, rinse and rest in the wetting solution while bringing the lye solution back to heat.  Bathe in the 5% lye solution again at 160° to 180° F (70° to 80° C) for 30 minutes.  After completing all three baths, you will have completed the process to remove the sulfur deposits and re-passivate your faucet parts.

You will also note that the second bath, the 10% citric acid, may generate some odor.  This is a good thing.  The odors we generate here are smells we will not get when we pull a beer.  I did not notice the smell was as strong as it was when I had a cider on tap, but it was definitely noticeable so you will want to make sure you have the windows open or an exhaust fan running.

When it comes time to dispose of these solutions:  Pouring the solutions down the drain poses no issues to your drains.  Lye is commonly used to clear drains, and citric acid is generally regarded as safe (U.S. Food and Drug Administration, 2015).  Be sure to check local regulations of course, and be sure to flush with plenty of cool water.


Refer to Figure 1 above for an exploded diagram.  Slide the flow-control compensator (9) in from the rear of the faucet.  The open end goes in with the rounded end out.  Note that there is a single hole in the smooth part on the side of the compensator that corresponds with the pin on the flow control barrel.  This hole should be visible through the hole in the faucet body for the flow control assembly.

Replace the O-rings on the flow-control barrel.  Slide the barrel into the side of the faucet.  A thin coat of keg lube on the O-rings will help assembly.  The post on the end of the barrel must engage the hole in the side of the flow-control compensator.  Replace the compression bonnet hand tight on the valve assembly and tighten until snug.  Replace the flow-control lever and verify operation of the flow-control valve.  Turning the level should cause the flow-control compensator to move in and out of the rear of the faucet.

Slide the handle lever (5a) back into the faucet body with a slight forward motion and then to the back until it seats against the front seat (7).  Ensure the flat sides of the threaded portion of the handle lever are oriented to the sides of the faucet, slide the bearing cup (4) concave surface down over the handle lever.  The bearing cup fits into a recess into the faucet body when properly installed.

Re-install compression bonnet (2) hand tight only over the faucet body and handle lever.  Re-install handle jacket (1) onto handle lever.


Again I want to be clear I’m not presenting data that is new.  I’m not an expert at this and I don’t presume to be breaking news.  I would not be able to share this were it not for the people who came before me.  I wanted only to allow someone who might not yet follow what’s going on to be able to fix their faucets.  Frankly it sucks to have to go through this and I think Perlick ought to own up to it.  Until then, this is what we have.


Adventures in Homebrewing. (2016). Perlick 650SS flow control faucet. Retrieved from Adventures in Homebrewing:
Agrazela. (2016, March 10). Examining possible solutions to issue of sulfur smell from Perlick 650ss faucets. Retrieved from
C., S. (2016, March 13). Examining possible solutions to issue of sulfur smell from Perlick 650ss faucets. Retrieved from
C., S. (2016, March 16). Examining possible solutions to issue of sulfur smell from Perlick 650ss faucets. Retrieved from
Certified Lye. (2013, May 1). Material Safety Data Sheet: Sodium hydroxide. Retrieved from Certified Lye:
ESPI Metals. (2016, April 17). Stainless Steel 303 – Alloy Composition. Retrieved from Welcome to ESPI Metals:
Iowa State University Extension. (2004). The science of smell part 1: Odor perception and physiological response. Iowa State University Extension.
Lindenmann, J., Matzi, V., Neuboeck, N., Ratzenhofer-Komenda, B., Maier, A., & Smolle-Juettner, F. M. (2010, December). Severe hydrogen sulphide poisoning treated with 4-dimethylaminophenol and hyperbaric oxygen. Diving and Hyperbaric Medicine: the Journal of the South Pacific Underwater Medicine Society, 40(4), pp. 213–217.
Magee, J. H., & Mohr, R. K. (2016). Passivating and Electropolishing Stainless Steel Parts. Retrieved from Carpenter Technology Corporation.
Perlick. (2014). Perlick Forward Sealing Beer Faucets. Retrieved from Perlick Corporation:
Shen, T. H. (2004, April 22). The Cleaning of 303 Stainless Steel. Retrieved from Lawrence Livermore National Laboratory:
U.S. Food and Drug Administration. (2015, April 1). CFR – Code of Federal Regulations Title 21. Retrieved from U.S. Food and Drug Administration:
White, E. (2015, July 20). Back to basics: Lye safety guide. Retrieved from Soap Queen:

[1] Things to consider with these containers:  Lye will generate a good amount of heat when added to water.  Borosilicate labware is ideal for something like this.  Mason jars are capable of withstanding quite a bit of heat however.   If the lye is stirred in without letting it sit on the bottom of the jar for too long, it will be fine.  Do not use Pyrex measuring cups for reasons that take too long to explain here.  Erlenmeyer flasks such as you use for yeast starters are great for swirling, but harder for fishing parts out.  Read through the guide and think about how you will work through each step before buying anything.
[2] Tap water may be suitable if it is very low in minerals.  It is safest to use distilled water especially given the very low cost for a gallon of it compared to the cost of one of these faucets.

New Install under Raspbian Jessie or Stretch

(This article is being re-written for BrewPi Legacy Remix.  Expect an update within a week or so – LCB on 1/9/19)

This will detail step by step instructions for installing BrewPi for an Arduino Uno.  We start with a clean Jessie or Stretch install, prepped according to my previous articles.

  1. Install Arduino Core as root:
    sudo apt-get install arduino-core -y
  2. Clone the BrewPi tools into your home directory:
    git clone ~/brewpi-tools
  3. Execute the install script as root:
    sudo ~/brewpi-tools/
  4. When prompted, install to /home/brewpi.
  5. When prompted, copy the BrewPi web files to /var/www/html.  The script will warn you that the directory is not empty, this is normal and ok to proceed.
  6. Accept all prompts for crontab entries.
  7. When complete, change password for brewpi:
    sudo passwd brewpi
  8. Run the updater script to change the installation back to the Legacy branch for Arduino support:
    sudo ~/brewpi-tools/ --ask
  9. When prompted, select [1] Legacy for the branch you wish to update.
  10. Select [Y] to update even though it is not your current branch.
  11. When prompted, select [3] Legacy for the branch you wish to update.
  12. Select [Y] to update even though it is not your current branch.
  13. When prompted to install firmware on your controller, ensure the Arduino is plugged into your Raspberry Pi’s USB port and select [Y].
  14. If you are prompted about whether your controller is unresponsive, select [Y].
  15. If you are prompted to restore settings or devices select [N].
  16. When prompted for the release to install, select [0] 0.2.10.
  17. Change “KeepAliveTimeout 5” to “KeepAliveTimeout 99” in /etc/apache2/apache2.conf (command is a single line):
    sudo sed -i -e 's/KeepAliveTimeout 5/KeepAliveTimeout 99/g' /etc/apache2/apache2.conf
    sudo service apache2 restart

Arduino setup is complete.  Browse to your BrewPi with your web browser and follow instructions for device configuration.

Setting up Raspberry Pi

These are the general steps I follow when preparing a new Raspberry Pi image for use with BrewPi:

  1. Download your new Raspbian image: (get the full version, not the “Lite” one)
  2. Install the image on your SD card:
  3. Insert the SD card, connect keyboard, mouse, monitor, and boot to graphical desktop. (1)
  4. Set up Wireless LAN:
    • Click on Wireless graphic in top-right taskbar
    • Select your network by name
    • Enter your pre-shared key
  5. Complete configuration:
    • Select Menu > Preferences > Raspberry Pi Configuration
      • System Tab
        • Expand Filesystem, Do Not Reboot (2)
        • Change Password
        • Change Host name (suggest: BrewPi)
      • Localization Tab
        • Set Locale (Assuming a US user:)
          • Language: en (English)
          • Country: US (USA)
          • Character Set: UTF-8
        • Set Timezone (Change zone to proper one for your area:)
          • Area: America
          • Location: Chicago
        • Set WiFi Country (Assuming a US user:)
          • Country: US United States
      • Select OK and reboot

After the Pi reboots, open a terminal window:

  1. Issue the following commands to ensure your software is up to date:
    sudo apt-get update
    sudo apt-get upgrade -y
  2. Install support for Microsoft Terminal Server Client connections*:
    sudo apt-get install xrdp
  3. Issue the following commands to clean local repositories, deleting space used by downloaded archives:
    sudo apt-get clean
    sudo apt-get autoclean
  4. Issue the following command to update the firmware of your Raspberry Pi:
    sudo PRUNE_MODULES=1 rpi-update
  5. Menu > Shutdown > Reboot; or:
    sudo reboot

Your Raspberry Pi should now be accessible on the network via PuTTY and with Microsoft Terminal Server Client (mstsc) as “{servername}.local”.   To validate name resolution, open a command prompt on another computer on the network and type:

ping {servername}.local

You should see something like:

C:\>ping brewpi.local

Pinging brewpi.local [] with 32 bytes of data:
Reply from bytes=32 time=418ms TTL=64
Reply from bytes=32 time=197ms TTL=64
Reply from bytes=32 time=27ms TTL=64
Reply from bytes=32 time=681ms TTL=64

Ping statistics for
 Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
 Minimum = 27ms, Maximum = 681ms, Average = 330ms

If you receive an error stating that the host could not be found, it may be that Bonjour services is not installed on your local computer assuming you use Windows.  You can obtain Bonjour either by installing iTunes, or with the stand alone installer found here. Bonjour also enables accessing the BrewPi web page with  “{servername}.local” without having to apply a static IP or remember an IP address.  If you use Linux you will need libavahi; under Mac, Bonjour should be installed with the base OS.

RDP Errors

There is a new desktop interface called “Pixel” released with the latest Jessie, dated 2016-09-23. There is a bug between this and xrdp which a lot of us use to connect to our Raspberry Pi’s desktop with Microsoft Terminal Server Client (mstsc). It will connect to the familiar X window and hang, displaying something like this:

connecting to sesman ip port 3350
sesman connect ok
sending login info to sesman
login successful for display 10
started connecting connecting to 5910
error - problem connecting

If you press “ok” it will present you with a credentials prompt and if you re-enter credentials it will give the same error.

To fix this, issue the following commands:

sudo apt-get --purge remove xrdp
sudo apt-get --purge realvnc-vnc-server

sudo apt-get install tightvncserver tightvnc-java
sudo apt-get install xrdp
sudo reboot


    1. A “headless” install is now possible.  Previously one needed to boot the Raspberry Pi in order to connect to wireless networking.   This is no longer necessary.  To do this, perform the following two steps while the SD card is mounted after flashing the boot image:
      • Create a file called “ssh” (without any extension) on the root of the boot partition of the SD card.  This allows SSH to work on first boot, circumventing new behavior in Raspbian which disables SSH by default.
      • Create a file called “wpa_supplicant.conf” on the root of the boot partition of the SD card.  In it, place the following information:
        ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev

        Replace “SSID” with the SSID of your local wireless network, and “PASSWORD” with your wireless network password.

  1. Raspbian will now automatically expand to use all of the available space on the SD card during the initial boot.