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.

Click to check whether the Linux installation on your Raspberry Pi is 64-bit

If you already have a 64-bit Linux distribution installed on your Pi, you can skip ahead to installing viam-server. To check whether the Linux installation on your Raspberry Pi is 64-bit (required for running viam-server), ssh into your Pi and then run lscpu.

Example output:

Screenshot of a terminal running the 'lscpu' command. The output lists of this command on a Raspberry Pi. A red box highlights the command and the top of the output which reads 'Architecture: aarch64.'

If the value of “Architecture: ‘xxxxxx’” ends in “64”, you can skip ahead to installing viam-server.

Hardware requirements

Install Raspberry Pi OS

The Raspberry Pi boots from a microSD card. You need to install Raspberry Pi OS (formerly called Raspbian) on the microSD card you will use with your Pi:

  1. Connect the microSD card to your computer.

  2. Download the Raspberry Pi Imager and launch it.

    Raspberry Pi Imager launcher window showing a 'Choose OS' and 'Choose Storage' buttons.
  3. Click CHOOSE DEVICE. Select your model of Pi.

    Raspberry Pi Imager window showing available pi models.
  4. Click CHOOSE OS. Select Raspberry Pi OS (other).

    Raspberry Pi Imager window showing Raspberry Pi OS (Other) is selected.

    Select Raspberry Pi OS Full (64-bit) from the menu.

    Raspberry Pi Imager window showing Raspberry Pi OS (Legacy, 64-bit) Full is selected.

    You should be brought back to the initial launch screen.

  5. Click CHOOSE STORAGE. From the list of devices, select the microSD card you intend to use in your Raspberry Pi.

    If no devices are listed, make sure your microSD card is connected to your computer correctly.

    The storage screen is shown with a generic SD card available as an option.
  6. Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.

    Raspberry Pi Imager window showing gear-shaped settings icon is selected.

    Check Set hostname and enter the name you would like to access the Pi by in that field:

    Raspberry Pi Imager window showing the advanced options menu with set hostname checked and set to my-machine.local.

    There are two ways you can secure your Raspberry Pi: with an SSH key or with password authentication.

    • For a learning project or a fun hobby project, we recommend using password authentication because it is easiest to set up for first-time users.
    • For production use, we recommend using SSH keys for more secure authentication; only someone with the private SSH key will be able to authenticate to your system.
    1. Select the checkbox next to Set username and password and set a username (for example, your first name) and a unique password that you will use to log into the Pi:

      Raspberry Pi Imager window showing the 'Set username and password' option is selected. The user has entered username 'Robota' and some hidden password.
    2. Select the SERVICES tab.

    3. Check Enable SSH.

    To set up SSH authentication:

    1. Select the checkbox for Set username and password and set a username (for example, your first name) that you will use to log into the Pi. If you skip this step, the default username will be pi (not recommended for security reasons). You do not need to specify a password.

      Raspberry Pi Imager with username specified as 'Robota' and the password field left blank.
    2. Select the SERVICES tab.

    3. Check Enable SSH.

    4. Select Allow public-key authentication only.

      If you select Allow public-key authentication only, and the section Set authorized_ keys for ‘’ is pre-populated, that means you have a public SSH key that is ready to use. In that case, you can leave the pre-populated key as-is. If this section is empty, you can either generate a new SSH key using these instructions, or you can use password authentication instead.

      Raspberry Pi Imager window showing 'Set Hostname' and 'Enable SSH' both selected.

    Lastly, connect your Pi to Wi-Fi so that you can run viam-server wirelessly. Check Configure wireless LAN and 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 country to where your router is currently being operated:

    Raspberry Pi Imager window showing the 'Configure wireless LAN' option selected with SSID and password information for a wireless network.

    Click SAVE.

  7. Double check your OS and Storage settings and then click YES:

    Edit image customization options window

    You will be prompted to confirm erasing your microSD card: select YES.

    Edit image customization options window

    You may also be prompted by your operating system to enter an administrator password:

    macOS admin password confirmation screen.

    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 the installation is complete.

  8. 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:


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 raspi-config:

  1. Launch the configuration tool by running the following command:

    sudo raspi-config
  2. Use your keyboard to select “Interface Options”, and press return.

    Screenshot of the Raspi Config screen with a red box and red arrow pointing to the '3 Interface Options' option where you can find the I2C and other drivers
  3. 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.

  4. Then, to apply the changes, restart your Raspberry Pi if it hasn’t already prompted you to do so.

    sudo reboot

Install viam-server

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 aarch64 or x86_64 architectures, with no need to install any dependencies (except for FUSE, which is required by the AppImage format).

To install viam-server on a Linux computer:

  1. Go to the Viam app. Create an account if you haven’t already.

  2. Add a new machine by providing a name in the New machine field and clicking Add machine:

    The ‘First Location’ page on the Viam app with a new machine name in the New machine field and the Add machine button next to the field highlighted.

  3. Navigate to the CONFIGURE tab and find your machine’s card. An alert will be present directing you to Set up your machine part:

    Machine setup alert in a newly created machine

    Click View setup instructions to open the setup instructions.

  4. Select the appropriate architecture for your machine: Linux (Aarch64), Linux (x86_64), or Armv7l. On most Linux operating systems, you can run uname -m to confirm your computer’s architecture.

  5. Follow the steps shown to install viam-server on your Linux computer.

  6. Once you have followed the steps on the setup instructions, viam-server is installed and running. Wait for confirmation that your computer has successfully connected.

By default, viam-server will start automatically when your system boots, but you can change this behavior if desired.

Next steps


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.

  1. Plug your Pi’s microSD card into your computer and create a plain text file called wpa_supplicant.conf.

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

  3. Save the file and eject the microSD card.

  4. Put the microSD card back into the Pi and boot the Pi.

The 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).

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev

 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"

Additional troubleshooting

You can find additional assistance in the Troubleshooting section.