Headless setup of a Raspberry Pi
Network Setup for a Raspberry Pi¶
This guide contains instructions to connect to the Pi through SSH in the local WiFi network.
You'll need a Pi with an OS already up and running:
Connection over LAN¶
Unless you are using the Pi with a dedicated monitor, a network connection is needed to use the Pipettin bot.
Connection method¶
There are two main connection methods. Choose the one more appropriate for your context.
Wireless / WiFi: available on RPi 3B or later.
- Configure the wifi connections, as explained below.
- This is only needed if you did not configure the WiFi connection in previous steps (e.g. when loading the OS to the SD card) or if the original WiFi network is no longer available.
Wired / Ethernet: available on all Raspberry Pi B models.
- Find a suitable ethernet cable.
- Connect the Raspberry Pi to your router.
- You may need to enable ethernet in
cloud-init
if using Ubuntu on the Raspberry Pi.
Update WiFi connection¶
There are different ways to update the wifi connection, depending on our setup.
In this section you will configure a WiFi network connection, and obtain the Pi's IP address on that network.
Clean installs¶
If you have just flashed a clean system image to an SD card, choose one of the following options:
- On Pipettin OS or Ubuntu for Raspberry Pi you may change the wifi in cloud-init by editing a file on the SD card.
- We don't provide instructions for doing this on clean Raspberry Pi OS, as it has changed recently and is also done automatically by the Raspberry Pi imager.
Existing installs¶
If you have Pipettin OS on your SD card:
- You may change the wifi in cloud-init by editing a file on the SD card from your computer. You need an adapter for this.
- If you power on the Pi, Pipettin OS will try to join a predefined WiFi network for setup purposes.
- You may create a hotspot with your smartphone with the following credentials, and the Pi will connect to it:
- Hotspot name:
pipettin
- Password:
password
- Hotspot name:
- Note: after finishing the setup, you may want to remove this connection from the WiFi configuration file.
- You may create a hotspot with your smartphone with the following credentials, and the Pi will connect to it:
If your Pi is already configured to connect to an existing network:
- Find its IP address.
- Connect to it through SSH.
If you already have network access to your Raspberry Pi, or if it is connected to a monitor, choose one of the following options:
- On Pipettin OS or Ubuntu for Raspberry Pi you may change the wifi in cloud-init.
- On Raspberri Pi OS you may change the wifi with raspi-config.
- On older versions of Raspberry Pi OS (or Raspbian), change the WiFi in
wpa_supplicant
.
Cloud init networks¶
For a cloud-init
setup, as seen in Ubuntu for Raspberry Pi, things are straightforward.
- Open the
/etc/netplan/50-cloud-init.yaml
file for editing.- If you do not have access to the pi, either mount the SD card on your PC (instructions here), or login with display and keyboard.
- Examine sample below, and make yours look familiar. Then save your changes and exit.
- Put the SD card back on the Pi and/or reboot.
network:
version: 2
# Configure your wifis here.
wifis:
renderer: networkd
wlan0:
access-points:
# First network.
YOUR_SSID_HERE:
password: YOUR_PASSWORD_HERE
# Second network.
ANOTHER_SSID_HERE:
password: ANOTHER_PASSWORD_HERE
# A network without passowrd protection. Oh no!
Grinch: {}
# And so on...
dhcp4: true
optional: true
# The following enables ethernet.
ethernets:
eth0:
dhcp4: true
optional: true
References:
Using raspi-config¶
You can connect to a different WiFi with the raspi-config
and nmcli
tools. This is the official method, which works on modern Raspberry Pi OS / Raspbian.
This method requires termial access, either through the network (through the previous wifi or ethernet), or a display and keyboard connected to the Pi.
If you don't have network access, you'll need to connect a display and keyboard to the Pi to access a terminal.
Tip
If on an older version of RPi OS, try editing the wpa_supplicant
file from the SD card (details below).
- Open a terminal on the Pi.
- Instructions for opening an SSH connection below.
- Follow the tutorial here: https://www.raspberrypi.com/documentation/computers/configuration.html#wireless-networking-command-line
WPA Supplicant networks¶
For WPA-supplicant setups, which work on older Raspbian versions.
Warning
This may not work at all on newer Raspbian versions (>=Bookworm). The wpa_supplicant
"trick" only works at the very first boot.
For details and discussion, see: https://github.com/raspberrypi/bookworm-feedback/issues/72
Alternative method: https://forums.raspberrypi.com/viewtopic.php?t=352958
- Unplug the power supply from the Rapsberry Pi, and remove the SD card.
- Mount the micro SD card in you computer.
- Edit the
/etc/wpa_supplicant.conf
file, and add your wireless network.- We recommend also adding your mobile hotspot network to this file, in case your network blocks
nmap
, or does not support mDNS/zeroconf. - A
wpa_supplicant.conf
file can be created in the/boot
partition, and may also work.
- We recommend also adding your mobile hotspot network to this file, in case your network blocks
- Safely unmount and eject the micro SD card. Then insert it into the Raspberry Pi, and plug it to the power supply.
Find the IP address¶
After setting up your Pi's connection method, the Pi should boot and connect to your network.
Tip
The pipettin bot may include a small OLED display, which shows the Pi's IP and the name of the WiFi netwok it is connected to. If this is the case, just read the IP on the display and you're done!
To access the Pi through that network, you need to find its IP address using a network scanning tool.
- First, try connecting to the
raspberrypi.local
address, as explained below.- If your network supports it, this will work out of the box, and is the easiest method. Otherwise consider the following options.
- Use the
Fing
app (Android). - Use the
nmap
tool (linux): example:sudo nmap -sn 192.168.0.0/24
.- You may need to change the IP range to match your networks' (run
ip a
to get info about that). sudo
is required for getting the full output fromnmap
.- An example of the expected output is shown below.
- You may add the
-p 3333
option, to scan only for the default GUI port.
- You may need to change the IP range to match your networks' (run
- Look for the IP in your router's admin interface.
Once you find the Pi's IP address (e.g. 192.168.0.13
) write it down.
Note
Here is an example output from sudo nmap 192.168.0.0/16 -p 3333
, showing the Pi's IP.
You may now continue to test the connection.
Test the connection¶
After finding the Pi's IP, use a program that allows you to have SSH communication with the Pi (eg: Putty in Windows, or just ssh
in Linux).
To test the connection you'll need to have found the Pi's address. Once an SSH connection is established, you can interact with the Pi through the local network from your PC (without the need to connect a display to the Pi).
The connection can also be tested from a web browser instead of SSH, but this will not allow you to install software or update the wifi network.
Here are some example commands to test a connection to the Pi:
Tip
The default password is "raspberry".
- From a Linux PC using
ssh
:- Using a known IP:
ssh pi@192.168.0.13
- Using mDNS:
ssh pi@raspberrypi.local
- Wait patiently until a command-line prompt appears.
- Using a known IP:
- Using the browser, write the Pi's IP followed by the GUI's port (3333), and the Pipetting GUI should open. This option is only valid if you have flashed our custom OS image instead of a "stock" OS.
- Known IP:
http://192.168.0.13:3333
- Using mDNS:
http://raspberrypi.local:3333
- Known IP:
Note
We are assuming that the user is pi
, that raspberry
is the password, and using an example local IP 192.168.0.13
- yours may differ.
mDNS will only work if properly configured in your network, we do not provide instructions for this.
Tip
The Pi's IP address might expire and change over time. Repeat the steps above if this seems to have happened. You may also try fixing Pi's IP or making it static on your router (i.e. setting a "Static IP" or "DHCP Reservation", respectively), or use the Pi's hostname to connect to it (i.e. through mDNS/zeroconf to a a raspberrypi.local address). Guides for this are available on the internet, specific to your internet router and operating system.
Next steps¶
Choose your own adventure:
- If you installed a clean image of Raspberry Pi OS or Ubuntu, continue with the Software Setup Guide.
- If you installed Pipettin OS, proceed directly to the electronics setup guide.
- Optionally update its software.
Utilities¶
Check port usage¶
This can be handy to see what apps are using which ports:
Source: https://www.cyberciti.biz/faq/unix-linux-check-if-port-is-in-use-command/
Change the hostname¶
To change the hostname in Ubuntu temporarily, you can use raspi-config
or the hostnamectl
command.
The procedures are different, depending on the OS:
- On RaspberryPi OS, use the
raspi-config
tool. Just use the menus. - On Ubuntu, things are a bit messed up (instructions follow).
To change it in ubuntu, run:
sudo hostnamectl set-hostname NEW_HOSTNAME --static # This is only temporary.
sudo hostname NEW_HOSTNAME
Now, to make it persist across reboots, you need to edit some files:
- Edit
/etc/hosts
:- Replace the old hostname here.
- You can use
vi
,nano
, or use sed:sudo sed -i 's/OLD_HOSTNAME/NEW_HOSTNAME/g'
. - Check with
cat /etc/hosts
.
- Edit
/etc/cloud/cloud.cfg
:- Change
preserve_hostname: false
topreserve_hostname: true
(i.e. comment it out). - Add
hostname: NEW_HOSTNAME
(just belowpreserve_hostname
). - Change
- update_hostname
to#- update_hostname
(i.e. comment it out). - Check with
cat /etc/cloud/cloud.cfg
.
- Change
Reboot to check if it worked.
Sources:
- https://www.redswitches.com/blog/ubuntu-change-hostname/
- https://www.cyberciti.biz/faq/ubuntu-20-04-lts-change-hostname-permanently/
- https://stackoverflow.com/a/61064656
- https://linuxconfig.org/how-to-set-hostname-on-raspberry-pi
References¶
A generic from-scratch setup guide for the Raspberry Pi can be found in the internet:
"Headless" setup guide, this is what we need.
- Raspberrypi.org: https://www.raspberrypi.com/documentation/computers/configuration.html#setting-up-a-headless-raspberry-pi
- Hackster: https://www.hackster.io/435738/how-to-setup-your-raspberry-pi-headless-8a905f
- Medium: https://medium.com/hackernoon/how-to-setup-a-headless-raspberry-pi-7f2b8b00c790
The most relevant part of those guides is the network setup.
- Official setup guide: https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up
This last one is not specific enough, but it is worth linking to.