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

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.

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

The SD card is in your hand, plug it right back in 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:

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.

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.