Skip to content

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.

  1. Find a suitable ethernet cable.
  2. Connect the Raspberry Pi to your router.
  3. 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
    • Note: after finishing the setup, you may want to remove this connection from the WiFi configuration file.

If your Pi is already configured to connect to an existing network:

  1. Find its IP address.
  2. 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:

Cloud init networks

For a cloud-init setup, as seen in Ubuntu for Raspberry Pi, things are straightforward.

  1. 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.
  2. Examine sample below, and make yours look familiar. Then save your changes and exit.
  3. 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).

  1. Open a terminal on the Pi.
  2. 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

  1. Unplug the power supply from the Rapsberry Pi, and remove the SD card.
  2. Mount the micro SD card in you computer.
  3. 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.
  4. 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 from nmap.
    • An example of the expected output is shown below.
    • You may add the -p 3333 option, to scan only for the default GUI port.
  • 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.

Nmap scan report for 192.168.13.52
Host is up (0.093s latency).

PORT     STATE SERVICE
3333/tcp open  dec-notes
MAC Address: DC:A6:32:50:03:7D (Raspberry Pi Trading)

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

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:

Utilities

Check port usage

This can be handy to see what apps are using which ports:

sudo lsof -i -P -n | grep LISTEN

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 to preserve_hostname: true (i.e. comment it out).
    • Add hostname: NEW_HOSTNAME (just below preserve_hostname).
    • Change - update_hostname to #- update_hostname (i.e. comment it out).
    • Check with cat /etc/cloud/cloud.cfg.

Reboot to check if it worked.

Sources:

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.

The most relevant part of those guides is the network setup.

This last one is not specific enough, but it is worth linking to.