Raspberry Pi Setup Guide
To install the Viam RDK, you need a Raspberry Pi running a 64-bit Linux distribution.
If you already have a 64-bit Linux distribution installed on your Pi, skip ahead to enable the required communication protocols for your hardware.
- A Raspberry Pi single board computer
- A microSD card
- An internet-connected computer
- A way to connect the microSD card to the computer (microSD slot or microSD reader)
Install Raspberry Pi OS
To install Raspberry Pi OS (formerly called Raspbian) on a microSD card from which the Pi boots, connect the microSD card to your computer.
Download the Raspberry Pi Imager and launch it.
CHOOSE OS. Click on
Raspberry Pi OS (other).
Raspberry Pi OS (Legacy, 64-bit) Fullfrom the menu.
You should be brought back to the initial launch screen.
To make your Raspberry Pi easier to access in the next step, configure your Raspberry Pi’s hostname, ssh credentials, and wifi. Click the gear-shaped settings icon in the lower right to bring up the Advanced options menu.
If you are using a non-Raspberry Pi OS, altering the Advanced options will cause the initial boot to fail.
Set hostnameand enter the name you would like to access the Pi by in that field.
There are two ways you can secure your Raspberry Pi: with an SSH key or with password authentication.
To use the SSH key method: check
Enable SSH. Using SSH Keys for authentication is a great way of securing your Raspberry Pi as only someone with the private SSH key will be able to authenticate to your system. If you select
Allow public-key authentication only, and the section
set authorized_ keys for 'pi'is pre-populated, that means you do have an existing public SSH key that is ready to use. In that case, you do not have to change this section.
If this section is empty, you can either generate a new SSH key using these instructions, or you can use password authentication instead.
If you decide to use the password authentication method: click on
Use password authentication. If you scroll down, you have the option to change the username, then to set a password:
Be sure that you remember the
passwordyou use, as you will need this when you SSH into your Pi.
The default username and password on Raspberry Pis are
- username: pi
- password: raspberry
However, it’s bad practice to keep the default username and password on a Raspberry Pi since doing so makes it easy for hackers to get access to your Pi. In the past, malware infected thousands of Raspberry Pi devices that were using the default username and password.
Lastly, you should connect your Pi to Wi-Fi, so that you can run
Configure wireless LANand enter your wireless network credentials. SSID (short for Service Set Identifier) is your Wi-Fi network name, and password is the network password. Change the section
Wireless LAN countryto where your router is currently being operated and then hit save:
This should return you to the initial screen.
Now you need to pick your storage medium, so click
You may have many devices listed, select the microSD card you intend to use in your Raspberry Pi. If this page is blank and you do not have any listed, make sure your microSD card is connected to your computer correctly:
After clicking save, double check your OS and Storage settings and then click
You will be prompted to confirm erasing your microSD card: select
YES. You may also be prompted by your operating system to enter an Administrator password:
After granting permissions to the Imager, it will begin writing and then verifying the Linux installation to the MicroSD card:
Remove the microSD card from your computer when it is complete:
Place the SD card into your Raspberry Pi and boot the Pi by plugging it in to an outlet. A red LED will turn on to indicate that the Pi is connected to power.
Connect with SSH
Once your Raspberry Pi is plugged in and turned on, wait a minute to let your Pi boot up.
Launch your terminal on your computer and run this command:
The text in <> should be replaced (including the < and > symbols themselves) with the user and host names you configured when you set up your Pi.
Example: if your username is ‘USERNAME’ and your hostname is ‘pi’: then it should be
If you are prompted “Are you sure you want to continue connecting?”, type “yes” and hit enter. Then, enter your password. You should be greeted by a login message and a command prompt.
Next, it’s good practice to update your Raspberry Pi to ensure all the latest packages are installed:
sudo apt update
sudo apt upgrade
Enable communication protocols
Certain hardware, such as analog-to-digital converters (ADCs), accelerometers, and sensors, communicates with your Pi using specialized communications protocols, including I2C, SPI, serial, or one-wire protocols.
If you are using hardware that requires these protocols, you must enable support for them on your Pi using
Launch the configuration tool by running the following command:
Use your keyboard to select “Interface Options”, and press return.
Enable the relevant protocols to support your specific hardware. For example:
- If you are using an analog-to-digital converter (ADC), motor, or other device that requires the SPI protocol, enable SPI.
- If you are using an accelerometer, sensor, or other device that requires the I2C protocol, enable I2C.
- If you are using a CSI v1.3 or v2.0 camera, enable Legacy Camera support.
- If you are using a sensor, motor, or other device that communicates over the serial port, enable Serial Port.
Check the documentation for your specific component to verify the communication protocols it requires.
Then, to apply the changes, restart your Raspberry Pi if it hasn’t already prompted you to do so.
viam-server is distributed for Linux as an AppImage.
The AppImage is a single, self-contained binary that runs on 64-bit Linux systems running the
x86_64 architectures, with no need to install any dependencies (except for FUSE, which is required by the AppImage format).
viam-server on a Linux computer:
Determine if FUSE version 2 is installed on your Linux system:
find /usr -name libfuse.so.2
If the above command does not return a path to the
libfuse.so.2file, install FUSE version 2 according to your Linux platform:
viam-serveron a Raspberry Pi running Raspberry Pi OS (Debian GNU/Linux 12 bookworm or later), install FUSE version 2 with the following command:
sudo apt install libfuse2
viam-serveron Ubuntu, install FUSE version 2 with the following commands:
sudo add-apt-repository universe sudo apt install libfuse2
viam-serveron other Linux distributions, or for more information, see FUSE troubleshooting.
Do not install the
fusepackage (that is, without a version number).
viam-serverrequires FUSE version 2 specifically (
Go to the Viam app and add a new machine by providing a name in the New machine field and clicking Add machine. If this is your first time using the Viam app, you must create an account first.
On the Setup tab, select
Linux (x86_64)for the appropriate Architecture for your computer. On most Linux operating systems, you can run
uname -mto confirm your computer’s architecture.
Follow the steps shown on the Setup tab to install
viam-serveron your Linux computer.
Once you have followed the steps on the Setup tab,
viam-serveris installed and running. Return to the Setup page on the Viam app and wait for confirmation that your computer has successfully connected.
viam-server will start automatically when your system boots, but you can change this behavior if desired.
Before you can program a machine, you must configure its components and services as well as any modules, remotes, processes and frames.
Write error when imaging Raspberry Pi OS
If you experience the error
Verifying write failed. Contents of SD card is different from what was written to it when imaging your Raspberry Pi with the Imager in step 5, there might be an issue with your micro SD card reader.
Try a different micro SD card reader, or use a different USB port on your computer.
If you are connecting your SD card reader to your computer through a USB hub, try connecting directly it to your computer instead.
Error: can’t read from I2C address
If you see the error
error: can't read from I2C address in your logs after installing
viam-server, you need to enable
I2C support on your Raspberry Pi.
You can use the command
sudo journalctl --unit=viam-server to read through the
viam-server log file.
Follow the instructions to enable communication protocols on your Pi to resolve this error.
Add additional WiFi credentials
If you move your machine to a different WiFi network, you will have to update the WiFi credentials.
You can update the WiFi configuration by creating a new
wpa_supplicant.conf file on the “boot” partition.
The steps are explained below.
Plug your Pi’s microSD card into your computer and create a plain text file called
Paste the following example into the file, replacing “Name of your wireless LAN” and “Password for your wireless LAN” with your credentials. Be sure to use UNIX (LF) line breaks in your text editor.
Save the file and eject the microSD card.
Put the microSD card back into the Pi and boot the Pi.
wpa_supplicant.conf file will be read by the Pi on boot, and the file will disappear but the WiFi credentials will be updated.
You can duplicate the “network” section to add additional WiFi networks (for example your work, and your home).
The “priority” attribute is optional and can be used to prioritize networks if multiple networks are configured (higher numbers are prioritized).
ssid="Name of your wireless LAN"
psk="Password for your wireless LAN"
ssid="Name of your other wireless LAN"
psk="Password for your other wireless LAN"
You can find additional assistance in the Troubleshooting section.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better: