Why do you guys insist on using Linux?

There’s been some recent discussions/arguments on forums about the use of Unix variants for these DIY projects. There is no argument that Windows has a crushing lead in the desktop OS market share. Those of us who do this, with some notable (notorious?) exceptions, do this for free. In essence, we do it just for the happiness we get seeing others use our work. If that’s our goal, why not “cater to the masses?” Surely it would increase the adoption rate?

I’m going to use BrewPi Remix as an example since I’m most familiar with it. Unless someone has a better example, I believe it is the oldest surviving DIY/Open Source project, released in 2011. As such, I believe it was also the original project which brought the Raspberry Pi to our projects. While Elco did the original BrewPi work on an old router, the Raspberry Pi released in 2012 and, by February 2015, had sold more than 5 million boards. It was arguably the perfect platform for his use.

I deliver IT projects professionally. When it all comes down to it, my clients are concerned with three things: Cost, schedule, and performance. My experience is that this method of determining success and value applies to these DIY projects as well. I’ll attempt to use the same method to demonstrate the reasons behind these decisions, and hopefully explain why Elco and then the rest of us have chosen this ecosphere.

Cost

Right this moment (January 11th, 2020), the Raspberry Pi Zero W (a wireless variant) is $31.99 on Amazon (US), including a case, SD card, and power supply. That is everything you need if you already have a monitor mouse and keyboard lying around. I dare someone to show me another network-capable computer with the OS license included at that price point.

At this point in the argument, a few people generally point out that they have an old Whizbang 2000 computer with Windows 95 on it that’s perfectly capable of doing the work. This counter-argument is called “confirmation bias.” Applied to our problem, it is exceedingly easy on the Internet today to find someone to disprove any statement. That does not mean that this is true for everyone or even the majority of people. In my experience, it is quite the contrary. The most common thing I hear is, “can you give me a 1 to n list of everything I need?” People are buying this for these projects and startup cost is important.

Even if a person has an old computer, that old computer has value. Otherwise, they would not have saved it in the first place. That value necessarily needs to be applied to the equation. If it is a “perfectly good computer,” it’s likely worth more than $31. If I completely ignore that argument, I am still left with a “cost” to prepare that old computer for use. That cost is my (or my users’) time.

I’ve not stumbled across an “old but useful” computer that was not set aside for a good reason. Maybe it is slow, maybe it is out of space, but before we use it, it needs a little work. Uninstall old programs, update the antivirus, apply patches, maybe run the system recovery to revert it to factory state. That takes a few hours of one’s time. There is always a balancing act for people to determine how much value their time has. This balance is certainly a personal decision, but one that the individual should consider carefully.

Licensing is a cost. Granted, most people forget about this when they buy their PC’s, but those licenses have value. A retail copy of Windows 10 Home edition is currently about $130. A copy of Raspbian is free as in free beer. There is no cost for Raspbian.

There is also a cost for the power consumed by a computer. I do not know many people who consider this, but the impact is not insignificant. According to one person who took the time to measure, 100 watts is a good average to use for cost estimation.

If you take an average of all 50 states, 13.31 cents per kilowatt-hour (kWh) is a good number to use. That 100-watt average for the PC equals 2.4 kWh per day or 876 kWh for a year. Running that PC costs $116.60 for the year. The Raspberry Pi Zero power supply I listed above uses a maximum (the PC was a measured average) of 2.5 Amps of 5V power, which is 12.5 watts. If that humble Pi (see what I did there?) were running at full tilt for a year, it would cost $14.57 per year. The Pi comes in saving you $102.03 per year. If you only count a single year and you count your “perfectly good PC” as entirely free, you still save $70.04 a year after buying a brand new Pi.

If you only count expenses, the Raspberry Pi running Raspbian saves you ~$70.04 in your first year. That’s a rather definitive advantage to Raspberry Pi.

Schedule

Schedule is always a tough one when it comes to DIY projects. Ultimately, the success and value of these DIY projects rely upon your time being free. That said, there’s a balance between the satisfaction one gets from doing work, and the frustration that comes in when things do not go according to plan. I am going to assume that any frustration is bad, and conversely, lack of frustration is good.

To make this argument, I will compare installing Apache on Windows to installing Apache on a Raspberry Pi. Apache is a web server used by a large number of projects.

Saving myself a good deal of writing in the process, I’m going to link you to the Apache Software Foundation’s instructions to install Apache on Windows. Have a look at this and then come back.

https://httpd.apache.org/docs/2.4/platform/windows.html

Now then, the same install on a Raspberry Pi requires you to type the following into the command line and press <enter>:

sudo apt install apache2 -y

Raspbian is based upon Debian, which is a Linux variant. Linux (and it’s progenitor: Unix) generally depends upon what is called a CLI – Command Line Interface. Using this interface allows us to script various processes, and the example above is one such process. Even if that CLI is intimidating to you, (after all a mouse is more intuitive than a CLI) I think you agree that typing that line three times (to account for typos) is still easier and quicker than following the Windows instructions.

If a project ends up needing even hundreds of commands at the CLI to install and configure all of the packages required, those commands may be scripted into a single file. Here is an example of one such script used to install BrewPi Remix:

https://github.com/brewpi-remix/brewpi-tools-rmx/blob/master/install.sh

Windows allows you to download and install a file with just a few clicks. That script I showed is on GitHub. How does a person used to Windows get that file onto a Raspberry Pi and run it to even begin? Enter the strength of the CLI again:

curl -L install.brewpiremix.com | sudo bash

Entering one command downloads (curl) the file (install.brewpiremix.com) and runs it (pipe through bash) as root (sudo). I’ll admit that’s not as “pretty” as opening a web page and clicking a link, but that’s the part that’s “not as easy” as Windows, and the price we ask you to pay for all the rest.

The example I gave above to install Apache was just a fraction of the work that goes into installing BrewPi Remix. Imagine on Windows if I told you that you need to:

Run Windows update and install all patches
Install:
- Git
- Python3
- Pip3
- Arduino
- Apache2
- php
- pyserial
- psutil
- simplejson
- configobj
- gitpython
- sentry-sdk

Each of those has its website and install/configure instructions. Linux, on the other hand, has the concept of “repositories,” which are essentially a “one-stop-shop” for applications. MS Windows does not have that construct (although the Windows Store hopes to bring some of that.)

There are methods under Windows, known as bundling, by which one may create an installer to do all that work for you. Because there are no standards or rules about how Windows applications install, each may have it’s own peculiarities and conditions by which you install it. Linux does have standards. If I want to create a bundle for Apache and PHP under Windows, I essentially have to write a program that goes to each website, downloads the most current version, executes the individual installers, and then somehow clicks the right buttons for you.

If I want to do the same work, install Apache and PHP under Linux, I need only to issue a one-line command:

sudo apt install apache2 php -y

To bring this all together: When a component used by a Linux-based Open-Source project changes, the developer generally only needs to change a line or two of text within a script. When a component changes in the Windows ecosphere, the end-user needs to relive all the fun of going to individual websites.

Now, consider when a change in a component breaks things in others. All of the components need to work together. Under Windows, the best you can hope for is someone telling you: “don’t upgrade this yet, it will break other things” Under Linux, I can create dependencies in my scripts, conditional flows, which either use the proper versions together or make a different decision if another version is present.

All of this goes to “Schedule.” Your schedule and mine. You want to spend your time brewing and enjoying beer. You do not want to learn to program.

The purpose of an installer is to quickly and easily take a user from “wants to run” to “running” as quickly, efficiently, and simply as possible. In such a complex system of systems, being able to script this experience, and effectively maintain that script, is one of the most important aspects of a project.

Sadly, not all developers make an effort to use these tools to make your experience easier. That makes me sad because the installer is the very first experience people have with your work. If the installation is a mess, there is a good likelihood that you will lose users because they will just drop the whole thing. If a developer spends some time polishing the install process, there’s a much higher chance you will have people up and running and enjoying your hard work.

Finally, I can find no credible evidence that a person who ignores the user experience during the install process on Linux does any better providing a clean experience on Windows. Simply put: a pig wearing lipstick is not going to kiss any better.

Therefore, and since I’m the one writing, I give the advantage to Linux for complex system integration.

Performance

Once the user pays for a system, once the user installs a system, the user needs to operate that system. To me, that embodies performance.

I started this article with the assumption that there needed to be a separate computer to run one of these projects. I have yet to explain why. Many folks will never get to this part of the article, but hopefully, some will. I’ll explain why, when a person spends $1,000+ on a personal computer, it should not be the one to host the project.

A good deal of brewing-related projects in the ecosphere use what is called a “controller” in order to interface with the physical world. This interface may turn a refrigerator on and off to control fermentation temperature, turn on a burner to raise mash temperature, turn on a pump, or track beer as it is dispensed. That interface requires either a physical connection or what’s known as a service. The physical connection is often the decision point that necessitates a dedicated computer for users. Most people do not have a computer in their garage, den, shed, or basement.

In this case, a service or daemon is a fancy name for a program. That program runs and talks to the controller. It needs to be running while the controller is being used. In many cases, for example, BrewPi Remix, the controller is being used continuously. This necessitates a constantly available interface.

Simply put, a little Raspberry Pi (or any dedicated server) is going to be more consistently available than your home computer that is typically shared for several uses. You might be paying bills, playing games, video chatting with your parents, or playing a first-person shooter. Any of these processes may impact the availability or performance of that service.

One also needs to consider how the application is going to be accessed. As a developer, I have no idea whether my users will be running a Windows, Mac, or Linux desktop. Many users have and depend upon smartphones. This variety of user systems has led to a preponderance of applications that present a web-based user interface. A web browser is ubiquitous and, in many cases, provides a consistent application environment for the developer. The project needs to have a web server accessible by any computer on the network. Having a dedicated computer makes this easier, although admittedly, it’s not impossible to have a web server on nearly any PC. Avoiding conflicts are still a consideration. User PC’s are optimized for the user interface, not to be a server of other PC’s on the network.

Above I’ve presented arguments related to the so-called “separation of duties” theory. If you have one tool doing one job, it can be optimized to do that well. You also won’t have an issue when one of its other jobs necessitates maintenance. Spending $31 on a Raspberry Pi gives you quite a bit of flexibility in this respect.

One of the things I see often is a desire to present the web interface on the Internet. People think it’s cool, and want to show their project to people at work, or maybe follow along while on a family trip. I won’t go into the danger of exposing an endpoint to the Internet here, but rather just assume people will do it no matter what I say. If it’s going to happen, having that access method connect to a small dedicated computer is far better than having the Internet able to access the same computer with credit card information, medical records, and maybe even “those pictures” nobody else knows you have.

Finally, there’s the issue of the development environment. If I intend to present an application to the homebrew community, I need to know upon what they will be running that application. Big companies can afford to develop for two different platforms, but I’m doing this for free. Assuming one and only one environment is probably going to allow me to focus more deeply on the functionality of the application. If I have to choose one, it is more likely to be accepted if I choose one that runs on a $31 computer by itself than to require a Mac user to buy a PC.

Summary

I am one guy. There are exceptions to rules. Everyone is different. Your mileage may vary. Will not treat or prevent sexually transmitted infections. What I have shared here are only some of the arguments, but the ones which guide me. I may not convince you I am 100% right, but hopefully, I will have convinced you there are good reasons for the decisions I and others have made.

March 17, 2019July 28, 2019

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 Homebrewtalk.com, 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:

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

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.
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.
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.
Unplug your Arduino from your Raspberry Pi (you do not need to power down the Raspberry Pi first) before you proceed.
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.
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.
Take your 4.7k Ω 1/4 watt resistor and connect it between your A4 (data) connector and your power (5V) connector.
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.
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.
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.
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.
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.
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.

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.
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.)
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.
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.
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.
Connect the ground to the ground lug on the outlet. Connect the common/neutral lead to the neutral side of the outlet.
Run the hot lead from the power cord to the COM terminal on relay number one.
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.

March 10, 2019July 1, 2019

For the Masochists (or the truly paranoid)

(This article is written for BrewPi Legacy Remix version 0.5.2.0, 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.

Prerequisites

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 https://github.com/brewpi-remix/brewpi-script-rmx.git /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 https://github.com/brewpi-remix/brewpi-www-rmx.git /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:

/home/brewpi/utils/doPerms.sh

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 https://github.com/brewpi-remix/brewpi-firmware-rmx/releases/download/0.2.10/brewpi-arduino-uno-revC-0_2_10.hex

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:

[Unit]
Description=BrewPi service for: brewpi
After=multi-user.target

[Service]
Type=simple
Restart=on-failure
RestartSec=1
User=brewpi
Group=brewpi
ExecStart=/bin/bash /home/brewpi/utils/doBrewPi.sh -d
SyslogIdentifier=brewpi

[Install]
WantedBy=multi-user.target

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:

[Unit]
Description=BrewPi service for: wificheck
After=multi-user.target
[Service]
Type=simple
Restart=on-failure
RestartSec=1
User=root
Group=root
ExecStart=/bin/bash /home/brewpi/utils/doWiFi.sh -d
SyslogIdentifier=wificheck
[Install]
WantedBy=multi-user.target

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 Sandstorm.io, 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.

February 21, 2019February 21, 2019

BrewPi Remix FAQ

“What about some other scenario, when will you test that?” – Maybe never. This is not a commercial venture; chances are once I’m “done enough” making it work on the target system, I’ll be done for good. The original/current BrewPi is a far more capable system, with a wider adoption base, and excellent support. That’s probably a better choice for you if you want to venture from this path I’ve created for you.
“Do you plan to create/implement/merge {insert cool idea here} functionality?” – No I do not. I’m not a software developer by trade, and this is not a commercial venture so there’s probably little reason to implement something I’ll never use. To be embarrassingly and brutally honest, I hardly get a chance to even brew anymore. I started this initially to make it easier for a friend of mine to get going again after his Pi ate his SD card. I’ll repeat: The original/current BrewPi is a far more capable system, with a wider adoption base, and excellent support. That’s probably a better choice for you if you want expanded capabilities.
“Will you accept pull requests?” – Maybe. Here’s the honest truth however: Not being a software developer by trade means that working with typical software development tools in a collaborative environment like GitHub is new to me. I am probably doing this wrong/poorly and in a way that doesn’t easily allow such collaboration. If you’re willing to work with someone who does not have these skills in order that you may contribute your own work, it’s likely best to contact me directly before you start so we can work out the details to avoid frustration for both of us (mostly you.)
“What about older versions of the Pi or Raspbian Stretch, etc.?” – I’ve no reason to believe older versions will not work, but they’ve not been tested. In theory it should work fine, but at some point, on a platform like Raspberry Pi, you just need to say “flash a new card and get over it.” These are not desktop machines that accumulate “stuff” over the years. If you have a Pi that’s on it’s original SD card for more than a couple years you have a rare bird indeed. I’d be more than happy to discuss why it didn’t work if you run into an issue, it would be interesting I think, but it might not be something I choose to address.

Back to Installation Instructions.

February 21, 2019December 3, 2022

Security Note

My instructions tell you to copy and paste a command into your terminal window. Despite me telling you to do that, I am now going to tell you how unsafe that is. Many people browse the Internet, find the command they need, and blindly paste it into their terminal window. This one is blatantly (potentially) dangerous from a non-trusted source:

wget -qO- https://u.nu/brewpi-tools-remix | sudo bash

It’s going to download a script to your Raspberry Pi, and pipe (|) it through the command sudo bash. When you use sudo without any other arguments it will run the command which follows with root privileges. So, you basically found someone on the Internet telling you to run their code as root, without even knowing what it all does. Despite the inherent risk, installing an application as root is often necessary since some applications have to make global changes to your system.

This is how bad things happen.

Even if you think you completely understand the command you are reading and copying, there is still an opportunity for a specially crafted web page to make the command look like one thing, but be a completely different command when you paste it. That would be A Bad Thing™. For an example, copy and paste this code into your terminal (or if you are now suitable paranoid, into a text editor:

git clone /dev/null; clear; echo -n "Hello ";whoami|tr -d '\n';echo -e '!\nThat was a bad idea. Don'"'"'t copy code from websites you don'"'"'t trust! Here'"'"'s the first line of your /etc/passwd: ';head -n1 /etc/passwd git clone git://git.kernel.org/pub/scm/utils/kup/kup.git

(From this page which describes this copy/paste vulnerability.)

The lesson to be learned from this is if you are going to copy/paste a command from any source, always use an interim paste into a text editor like Notepad to make sure A Bad Thing™ doesn’t happen to you. Now you can join your previously scheduled show: Install Instructions, which is patiently waiting for you where you left it.

Wait. Now you don’t know if you should trust the setup command I provided? I’m shedding a happy tear. Security and the Internet is a rabbit hole filled with (justifiable) paranoia and bad actors. Your choices here however are:

Trust me and run it
Examine that script carefully and make sure it does nothing bad. Then, since the first one executes as root you need to follow that to the next one because it inherits that security construct. Ultimately you can drive yourself crazy when you realize the implications, or just accept that whenever you install free code from the Internet you take your chances. This is the case with any software, not just BrewPi.
Do a manual install. I’ve detailed how that might be done in a post called: “For the Masochists.”

At some point I hope to list out the manual install steps necessary to replicate this series of automated steps for the truly paranoid. That’s quite frankly not a high priority for me since the goal here is to make BrewPi Legacy Remix available to every-day people. Those of you who would choose the manual steps can probably figure it all out anyway.

Cheers!

Return to the Installation Instructions.

February 21, 2019July 1, 2019

Project Assumptions and Proceedings

This tool set adds a bootstrap to install the BrewPi Legacy Remix packages on a completely fresh install of Raspbian (codename “Stretch” at the time of this writing). I have created this bootstrap because some steps required in previous iterations were a little alien to people new to Raspbian/Linux. Additionally, some supporting software has been deprecated/upgraded which before now made the older BrewPi packages incompatible.

This bootstrap will:

Check a few things
Handle some Raspberry Pi setup steps if/as needed or recommended
Install some supporting files
Download and execute the BrewPi-Tools-RMX installation scripts
Perform some final cleanup

In order to make this work well, I have to make some assumptions about the environment in which this will be run. Here I’ll try to list some, however I am sure someone will find a way to try something I’ve not considered. Do not over-think this. Don’t fiddle around with your Pi before running the bootstrap. Turn it on, connect to your home network, and go. Here’s a list of known (or at least recalled) assumptions made during this project:

This has been developed and tested on a Raspberry Pi 3 B+ because that’s what I have laying around. I have absolutely no reason to believe it would not work on a Zero, 2B, or other versions of the Raspberry Pi line. I’ve just not tested it.
This has been developed and tested on the Raspbian OS. Raspbian is based on Debian, so using a Debian (or derivative) OS distribution may work. However, that’s not been tested. I am not at all sure that it would work on a different flavor of Linux.
This has been developed and tested on the Raspbian Stretch distribution. If a new distribution for the Raspberry Pi is released it may no longer work. I hope I’ve future-proofed it, however the original/core code may have some non future-proofed areas waiting to rear their ugly head (or I may not be as good at future-proofing as I believe.)
I’ve assumed throughout that this is the only function the Pi will handle. This is not unique to BrewPi in general. I’ve not specifically prevented it form doing anything else, I just can’t (and won’t try) to test every permutation.
This will not create a BrewPi which is secure enough to connect to from the Internet. There’s a whole host of reasons for this, but please, do not do it unless you know what you are doing. I suggest you consider Dataplicity if you really need/want to do this.
This has been developed and tested using the default user ‘pi’ which by default has password-less sudo rights. This is how Raspbian is shipped, and this is how I’ll continue to test it. If you know enough to change any of these assumptions, you know enough to figure out why this process may not work for you. If you simply MUST change this, I suggest you do it after you get BrewPi Remix running.
You need for your Pi to have access to the Internet. I think this is obvious, but the Pi needs to access GitHub and standard Raspbian repositories to download code. Generally speaking, plugging your Pi into your home network with an Ethernet cable will do this without any configuration necessary. Attaching to wireless will take a little more work that’s not in scope of this project specifically, but for which you will find some help in “Headless Raspberry Pi“.
This has been developed and tested on a bone-stock Raspbian setup, with no user or local customization implemented. The only things that has been tested which do not inherently work on a fresh setup is wireless connectivity and ssh over wireless. The bootstrap script will:
1. Check to make sure the script has executed with sudo to root (this is how the instructions will work if you follow them)
2. Provide some rudimentary instructions
3. Check for default password, and prompt to change it if so
4. Set the proper timezone
5. Prompt to optionally change the host name if it is currently the default ‘raspberrypi’
6. Check network connectivity to GitHub (this part should be a given since it’s intended to be run via wget but I’m not going to assume someone can’t break my plans)
7. Run an apt update if it’s not been run within the last week
8. Install git packages via apt get to allow the rest of the install to work
9. Install Python packages via pip.
10. Clone the BrewPi Tools RMX into the ~/brewpi-tools-rmx folder
11. Execute install.sh which is responsible for the rest of the setup

I am certain that someone will find an important assumption I did not list here. We’ll see how long that takes. Let me know what you find.

Return to Installation Instructions.

January 9, 2019January 25, 2022

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.

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 raspberrypi.org 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

https://www.raspberrypi.org/downloads/raspbian/

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:

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.

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:

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:

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:

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:

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).

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.”

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

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

 network={
     ssid="network_name"
     scan_ssid=1
     psk="password"
     key_mgmt=WPA-PSK
 }

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.

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.

Click on the icon, and select the line that allows you to eject the 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:

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.)

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!

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).

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:

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.

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.

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

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.