11 min read

In this tutorial, you will learn why the Raspberry Pi controller on a robot should be wireless, or headless; what headless means; and why it’s useful in robotics. You will see how to set up a Raspberry Pi as a headless device from the beginning, and how to connect to this Raspberry Pi once on the network, and then send your first instructions to it.

This article is an excerpt from a book written by Danny Staple titled Learn Robotics Programming. In this book, you will learn you’ll gain experience of building a next-generation collaboration robot

What does headless mean and why?

A headless system is a computer designed to be used from another computer via a network, for when keyboard, screen, and mouse access to a device is inconvenient. Headless access is used for server systems and for building robots. Refer to the following diagram:

A Raspberry Pi tethered to a screen, keyboard, and mouse

The preceding diagram shows a system with a head where a user can sit in front of the device. You would need to take a screen, keyboard, and mouse with your robot—not very mobile. You may be able to attach/detach them as required, but this is also inconvenient and adds bulk. There are systems designed to dock with Raspberry Pis like this and are portable, but when a robot moves, you’d need to disconnect or move with the robot.

I have seen, at some events, a robot with a tiny screen attached and someone using a wireless keyboard and mouse as an option. However, in this article we are going to focus on using a robot as a headless device. Take a look at the following diagram:

A Raspberry Pi on a robot in a headless configuration

The Raspberry Pi in the preceding diagram is mounted on a robot as a headless device. This Raspberry Pi is connected to batteries and motors, but not encumbered by a screen and keyboard; those are handled by another computer. The Pi is connected wirelessly to a network, which could be through a laptop. Code, instructions, and information are sent to and from the Raspberry Pi via this wireless network. To interact with it, you use the screen and keyboard on your laptop. However, you would usually expect your robot to function autonomously, so you would only connect to the Pi to modify things or test code. As an alternative to bringing a laptop to control a robot everywhere, it can be more convenient to add a few indicator LEDs so you can start and stop autonomous behaviors, view the robot’s status, or just drive it without needing to hook up the laptop at all. This Raspberry Pi is free from the screen and keyboard.

Most of the time, a screen and keyboard are not required. However, it is worth having them around for the few cases in which you lose contact with the Raspberry Pi and it refuses to respond via the network. You can then use a screen and keyboard to connect with it and see what is going on.

For our headless access to the Raspberry Pi, we will be using the SSH system, a secure shell. SSH gives you a command line to send instructions to the Pi and a file transfer system to put files onto it. As SSH connects over a network, we need to configure our Raspberry Pi to connect to your own wireless network.

Making a Pi headless makes it free to roam around. It keeps a robot light by not needing to carry or power a screen and keyboard. Being headless makes a robot smaller since a screen and keyboard are bulkier. It also encourages you, the maker, to think more about autonomous behavior since you can’t always type commands to the robot.

Setting up wireless on the Raspberry Pi and enabling SSH

To make your Raspberry Pi headless, we need to set up Wi-Fi. First, you will need to insert a MicroSD card prepared using Raspbian into your computer. To prepare your MicroSD card (at least 16GB) follow these steps:

  1. Go to https://www.raspberrypi.org/software/operating-systems/ and download the ZIP file of Raspbian Lite.
  2. Download Etcher and install it.
  3. Connect your MicroSD to your computer and select the downloaded Raspbian Lite file.
  4. The flash button will be highlighted, press it and the process should be completed in a few minutes.

If you are continuing straight here from Etcher, you should remove the card and reinsert it so that the computer can recognize the new state of the drive. You will see the card shows up as two disk drives.

One of the drives is called boot; this is the only one that you can read in Windows. Windows will ask if you want to format one of these disks. Click Cancel when Windows asks you. This is because part of the SD card holds a Linux-specific filesystem that is not readable by Windows.

In boot, you’ll need to create two files:

  • ssh: Create this as an empty file with no extension
  • wpa_supplicant.conf: This file will contain your Wi-Fi network configuration

It is important that the SSH file has no extension, so it is not ssh.txt or some other variation. Windows will hide extensions by default so you may need to reveal them. On Windows, in File Explorer, go to the View tab, look for the Show/Hide pane, and then tick File name extensions. In general, when working with code, having the extensions displayed is important so I recommend leaving this option ticked.

The wpa_supplicant.conf file

The first line you must provide in the wpa_supplicant.conf file is a country code. These are known as iso/iec alpha2 country codes and you should find the appropriate country code for the country you are in, by going to https://datahub.io/core/country-list. This is important, as the Wi-Fi adapter will be disabled by Raspbian if this is not present, to prevent it from operating outside the country’s legal standard, and interfering or being interfered with by other equipment. In my case, I am in Great Britain, so my country code is GB. Let’s take a look at the code:


Then, add the following lines. update_config means that other tools used later are allowed to update the configuration:


Now, you can define the Wi-Fi network your robot and Raspberry Pi will connect to:

  ssid="<your network ssid>"
  psk="<your network psk>"

Please be sure to specify your own network details instead of the placeholders here. The pre-shared key (PSK) is also known as the Wi-Fi password. These should be the same details you use to connect your laptop or computer to your Wi-Fi network.

The completed wpa_supplicant.conf file should look like this:

ssid="<your network ssid>"
psk="<your network psk>"

Ensure you use the menus to eject the MicroSD card so the files are fully written before removing it. Now, with these two files in place, you can use the MicroSD Card to boot the Raspberry Pi. Plug the MicroSD card into the slot on the underside of the Raspberry Pi. The contacts of the MicroSD card should be facing the Raspberry Pi in the slot; it will only fit properly into the slot in the correct orientation.

Plug a Micro-USB cable into the side of the Raspberry Pi and connect it to a power supply.

As the technical requirements suggested, you should have a power supply able to provide around 2.1 amps. Lights turning on means that it is starting.

Finding your Pi on the network

Assuming your SSID and PSK are correct, your Raspberry Pi will now have registered on your Wi-Fi network. However, now you need to find it. The Raspberry Pi will use dynamic addresses (DHCP), so every time you connect it to your network, it may get a different address; linking to your router and writing down the IP address can work in the short term, but doing that every time it changes would be quite frustrating.

Luckily, the Raspberry Pi uses a technology known as mDNS to tell nearby computers that it is there. mDNS is the Multicast Domain Name System, which just means that the Raspberry Pi sends messages to all nearby computers, if they are listening, to say that its name is raspberrypi.local and giving the address to find it. This is also known as Zeroconf and Bonjour. So, the first thing you’ll need to do is ensure your computer is able to receive this.

Apple macOS

If you are using an Apple Mac computer, it is already running the Bonjour software, which is already mDNS capable.

Microsoft Windows

On Windows, you will need the Bonjour software.

If you have already installed a recent version of Skype or iTunes, you will already have this software. You can use this guide (https://smallbusiness.chron.com/enable-bonjour-65245.html) to check that it is already present and enable it.

You can check whether it is already working with the following command in a Command Window:

C:\Users\danny>ping raspberrypi.local

If you see this, you have Bonjour already:

PING raspberrypi.local ( 56(84) bytes of data.
64 bytes from ( icmp_seq=1 ttl=64 time=0.113 ms
64 bytes from ( icmp_seq=2 ttl=64 time=0.079 ms

If you see this, you’ll need to install it:

Ping request could not find host raspberrypi.local. Please check the name and try again.

To do so, browse to the Apple Bonjour For Windows site at https://support.apple.com/downloads/bonjour_for_windows and download it, then install Download Bonjour Print Services for Windows. Once this has run, Windows will now be able to ask for mDNS devices by name.


Ubuntu and Fedora desktop versions have had mDNS compatibility for a long time. On other Linux desktops, you will need to find their instructions for Zeroconf or Avahi. Many recent ones have this enabled by default.

Testing the setup

The Raspberry Pi’s green light should have stopped blinking and only a red power light should be visible.

In Windows, summon a command line by pressing the Windows key and then CMD. In Linux or macOS, summon a Terminal.

From this Terminal, we will try to ping the Raspberry Pi, that is, find the Pi on the network and send a small message to elicit a response:

ping raspberrypi.local

If everything has gone right, the computer will show that it has connected to the Pi:

$ ping raspberrypi.local
PING raspberrypi.local ( 56(84) bytes of data.
64 bytes from ( icmp_seq=1 ttl=64 time=0.113 ms
64 bytes from ( icmp_seq=2 ttl=64 time=0.079 ms
64 bytes from ( icmp_seq=3 ttl=64 time=0.060 ms
64 bytes from ( icmp_seq=4 ttl=64 time=0.047 ms

What if you cannot reach the Raspberry Pi?

If the Raspberry Pi does not appear to be responding to the ping operation, these are some initial steps you can take to try to diagnose and remedy the situation. If it works already, skip to the next heading. Refer to the following steps:

  1. First, double-check your connections. You should have seen a few blinks of green light and a persistent red light. If not, ensure that the SD card is seated firmly and that the power supply can give 2.1 amps.
  2. Use your Wi-Fi access point settings with the Pi booted and see if it has taken an IP address there.
  3. This may mean that Zeroconf/Bonjour is not running on your computer correctly. If you have not installed it, please go back and do so. If you have and you are on Windows, the different versions of Bonjour print services, Bonjour from Skype, and Bonjour from iTunes can conflict if installed together. Use the Windows add/remove functions to see if there is more than one and remove all Bonjour instances, then install the official one again.
  4. Next, turn the power off, take out the SD card, place this back into your computer, and double check that the wpa_supplicant.conf file is present and has the right Wi-Fi details and country code. The most common errors in this file are the following:
    • Incorrect Wi-Fi details
    • Missing quotes or missing or incorrect punctuation
    • Incorrect or missing country code
    • Parts being in the wrong case
  5. The SSH file is removed when the Pi boots, so if you are certain it was there and has been removed, this a good sign that the Pi actually booted.
  1. Finally, this is where you may need to boot the Pi with a screen and keyboard connected, and attempt to diagnose the issue. The screen will tell you whether there are other issues with wpa_supplicant.conf or other problems. With these problems, it is important to look at the screen text and use this to search the web for answers. I cannot reproduce all those here, as there are many kinds of problems that could occur here. If you cannot find this, I recommend asking on Twitter using the tag #raspberrypi, on Stack Overflow, or in the Raspberry Pi Forums at https://www.raspberrypi.org/forums/.

In this article, we explored what headless or wireless means for robots and set up the ‘headless’ in Raspberry Pi. To learn more about robotics and connecting, configuring the robot check out the book, Learn Robotics Programming.

Read next

Introducing Strato Pi: An industrial Raspberry Pi

Raspberry Pi launches it last board for the foreseeable future: the Raspberry Pi 3 Model A+ available now at $25

Introducing Raspberry Pi TV HAT, a new addon that lets you stream live TV

Data science enthusiast. Cycling, music, food, movies. Likes FPS and strategy games.