Python SDK Setup (Quick Start)

Downloading And Flashing the SD Card Image

The first step is to download our version of the latest Raspberry Pi OS (formerly known as Raspbian). This version is preconfigured with the Sphero SDK, which will make set up very easy. First download this file and save it on your computer.

You'll need a tool to write this image onto a micro SD card. We recommend using Balena Etcher, but you can use any tool you're familiar with. After you have a writing tool downloaded and installed, insert your micro SD card into your computer before moving on.

If you're using Balena Etcher, open the application, and select the .gz file you downloaded. There is no need to unzip the the folder.

The next step should automatically be configured to use the micro SD card you inserted, unless you have multiple external drives attached. In that case, you'll need to select the drive containing the micro SD card. Click "Flash!" to kick off the image writing process. On Windows, you will see a User Account Control popup asking if you want to allow the Windows Command Processor to make changes to your device. Click Yes to continue.

You should see the UI update with progress bar. Once the writing process is complete, you can eject the micro SD card from your computer.


If you're on Windows, you may see this dialog. DO NOT FORMAT! You'll erase the image you just wrote. Windows 10 does not support the file system used by the Raspberry Pi, so it thinks it's corrupted. Just ignore the message and eject the micro SD card. 

Finally, insert your micro SD with the preconfigured image into the card slot on your Raspberry Pi. 

Setting Up Raspberry Pi OS

Configuration with a Monitor, Keyboard, and Mouse

If you connect a monitor to your Pi after it has already booted, it may have the HDMI port disabled so you'll just get a blank screen. If this happens, disconnect power and make your connections in the order described above.

Using the Terminal

Open the Terminal

You'll be using the terminal on your Pi to enter commands. From the desktop, click the icon shown in the toolbar at the top of your screen to open the terminal:

Run a command

Let's check our Python version. In your terminal, type the following and then press enter:

python3 --version

There, you just ran your first command in the terminal! It should have printed the Python version to the terminal as shown below:


Notice that the command was python3, not python. Without the 3 you'll run Python 2.x.x, which is incompatible with the RVR+/RVR SDK. If you didn't start with the Sphero preconfigured SD card image, you might see a different version here. That's okay as long as it's 3.5.3 or higher.

Some Common Bash Terminal Commands

When you use the terminal, you are interacting with a program called a shell. The default shell in Raspberry Pi OS is bash. The following commands are all bash commands, but many are common to other shells, such as zsh.

Common Bash Terminal Commands


The more you use bash, the more comfortable and efficient you will become. One helpful feature is bash autocompletion. Press the Tab key to auto complete partially-typed command sequences.

Learning More

If you're new to using Bash, the Raspberry Pi Foundation has a fun Pac-Man treasure hunt on the terminal tutorial that will help you get comfortable hacking in the terminal.

Using SSH

What is SSH?

SSH, or Secure Shell Protocol, is a way of securely accessing the terminal (where you enter commands) of another computer remotely over a network. (That's a simplification - for more details, check out the wikipedia article)

Why use it?

While carrying an extra keyboard, mouse and monitor around with you can make you look cool and important 👩‍🔬, one of the great things about the Raspberry Pi computer is that it can be accessed remotely from another device on the same network (via SSH). This means that you can drive your RVR+/RVR around in style with an entirely wireless setup (aside from the cables connecting your RVR+/RVR to your Raspberry Pi)! 😎

Since RVR+/RVR is primarily a mobility platform for your projects, we strongly recommend setting this up to avoid the hassle of extra cables.

Why wouldn't I use it?

In some cases, SSH will not be a useful and/or available option for you to use:

How do I set it up?

SSH is disabled by default in the Raspberry Pi OS. You have two options for enabling it.

Option 1: Use the Raspberry Pi Configuration Menu

Option 2: Use the raspi-config command.


Enabling SSH requires you to reboot your Raspberry Pi. Go ahead and do that now if you haven't already.

For more information on SSH, review the official Raspberry Pi Secure Shell access tutorial.

Once SSH is configured, you just need to send a few commands for the connection to go through and you'll be able to control your Raspberry Pi-controlled-RVR+ or RVR from your laptop, desktop, or other device!

Getting your Raspberry Pi IP Address

You'll need the IP address of the Raspberry Pi to SSH into it, so the next thing we'll need to do is gather that information. Get the IP address of the Pi by jumping into its terminal and entering:

hostname -I

Your IP address is often the same, especially as long as you stay on the same wifi network, but it can change, so, if you are having issues connecting, you can run the above command again (from the Raspberry Pi, with a monitor/mouse/keyboard plugged in) to check if there have been any changes.

Try out an SSH connection


It's a good idea to test the SSH connection (in the terminal on your desktop/laptop) and make sure that it works before completely abandoning your Raspberry Pi's monitor/mouse/keyboard setup.

On Remote Computer

The device you want to use to control the RVR+/RVR must be on the same wifi network as your Raspberry Pi. On your laptop/desktop/etc., open the the terminal and use this command to access your Raspberry Pi. Make sure to replace "ipaddress" with the IP Address of your Pi.

ssh pi@ipaddress

Once you run this command, you'll be prompted for the password to your Raspberry Pi. For security, you'll get no indication that your password is being typed as you type it.


If you have installed a new Raspberry Pi OS and have previously used SSH you may encounter an error at this step. Try regenerating your SSH keys with this command.

ssh-keygen -R ipAddressOfYourPiHere

You should now get a success message and be able to work in the terminal to control your Raspberry Pi the same way you could when you had a monitor plugged into it.

Type the following command to shutdown your Raspberry Pi and get ready to connect it to RVR+/RVR in the next step.

sudo shutdown now


You should try to always shut down your Raspberry Pi properly before removing power (unplugging it or turning off a RVR+/RVR that is powering it). SD card corruption may occur if your Pi is not shut down properly.

Connecting to RVR+/RVR

Signal Connections to RVR+/RVR

To set up the Raspberry Pi on top of RVR+/RVR, connect its ground and serial pins on the GPIO header to those on the RVR+/RVR as shown in the wiring diagram below:


Your Tx and Rx (yellow and orange) wires should be crossed, as shown in the table below:

*Pin numbers are from the Raspberry Pi GPIO Pinout Guide, where you can find more info about the GPIO header on your Pi.

Powering Your Raspberry Pi

To make your RVR+/RVR fully mobile, you'll want to power your Pi directly from RVR+/RVR or another onboard source.

Pi 3, 3B+, and Zero W

These models can be powered by RVR+/RVR directly using the USB Type A port on RVR+/RVR, or by a separate USB power source if desired.

Pi 4

The Raspberry Pi 4 was released after we finalized RVR's electrical design. Its maximum input current specification exceeds RVR's 2.1A current limit for powering external devices. We therefore recommend powering a Raspberry Pi 4 from a separate USB power bank capable of sourcing enough current.


Depending on usage patterns, RVR+/RVR can sometimes power a Pi 4 - just be aware that the e-fuse on RVR+/RVR will shut off power without warning if it detects current over 2.1A. Do this at your own risk.

Powering From the Expansion Port

Although +5V and GND on the expansion port are internally connected to the corresponding lines on the USB port, most jumper wires will be too thin to power a Raspberry Pi and could result in low voltage warnings or an outright failure to boot. The 5V pin on the RVR+/RVR expansion port is generally useful for lower-power devices.

Test it!

Let's Make Sure Everything is Working...

To make sure your Pi is set up correctly and connected to your robot's UART port, power on your RVR+/RVR using the power button and enter the following commands in your terminal:

cd ~/sphero-sdk-raspberrypi-python

python3 getting_started/observer/leds/

Did you see the front LEDs on your RVR+/RVR turn red and blue? Great, your system is working!

If you didn't see the front LEDs change to red and blue, check out our troubleshooting article.


Once you are finished using your Raspberry Pi and RVR+/RVR, make sure to shut down your Pi properly to avoid SD card corruption:

sudo shutdown now

What's Next?

Now that you've set up your Pi and verified that it can communicate with your RVR+/RVR, here are some things to check out next: