Python SDK Setup (Advanced)

Before You Start

This guide assumes that you already have a Raspberry Pi with a Linux-based operating system and the following dependencies already installed:

If you'd rather start with a pre-configured SD card image, head on over to our Quick Start instructions.

Note: We have tested on Raspberry Pi OS with desktop (formerly known as Raspbian). If you are working on a different Linux distribution, you may run into issues with missing dependencies. Let us know by filing an issue on GitHub so we can continue to improve our setup scripts to handle more OS variations.

Get Ready

Open the Raspberry Pi terminal, which you can get to by clicking the icon in the toolbar at the top of your screen:

If your Raspberry Pi isn't freshly set up, make sure your OS is up to date by running:

sudo apt update

sudo apt dist-upgrade

sudo apt clean

sudo reboot


Get the Code

We now must obtain the RVR+/RVR Raspberry Pi Python SDK code from GitHub by cloning the repo with git.

Using Git

Using Git to get the code onto your Raspberry Pi is a bit technical (and requires a free GitHub account), but it is much simpler to update your local code, on your Raspberry Pi, whenever we change it on GitHub.

To use Git to clone the repo to your computer, you'll again use the terminal on your Raspberry Pi. This time, we'll want to cd into the directory where you would like the RVR+/RVR Raspberry Pi code to live; for example, we want to just put our code in our home directory that the terminal starts us in, so we just need to do:

cd home


From there, you'll jump into your browser and head over to the (Python SDK GitHub page), where you'll navigate to the green "Code" button.

Clicking on it will yield a menu similar to the one in the photo above where, in the lower right corner, you have the option to copy the url in the center of the menu. Once you've copied this, jump back over to your terminal and write:

git clone https://the-url-you-just-copied.com

cd ~/sphero-sdk-raspberrypi-python


ℹ️ NOTE

pwd stands for "print working directory". This can be a useful command when you are trying to ensure you are in the correct file directory at any point in this process.



You may be prompted for your GitHub login information, so make sure you have that handy! It is normal for nothing to display as you type your password, to protect your information (safety 3rd!).

💡 TIP

Now, any time you want to make sure that you have the most up-to-date version of our code on your Raspberry Pi, you simply need to go to the root directory of the RVR+/RVR code (if you put yours where we suggested, you should be in pi/raspberry-pi) and run:

git pull


Install The Dependencies and Configure the Serial Port

ℹ️ NOTE

We have previously recommended using Pipenv to keep SDK projects and their dependencies isolated from the system Python installation. If you wish to do this, check out our pipenv instructions.

In order to install the required Python packages needed to run the SDK, all you have to do is run the first-time-setup.sh script by running the following command:

./first-time-setup.sh


ℹ️ NOTE

This process may take a few minutes

When the installation completes, the script will ask whether you have already disabled serial shell access and enabled the serial port to communicate with RVR+/RVR. If so, then skip to the next section! If you choose to use raspi-config to change settings, you will need to restart your Pi afterward. If you opt to restart when prompted make sure everything you've been working on is saved! If you opt out at that moment, you will still need to restart your Pi at another point for the installation to take effect so that you can utilize your Pi with your RVR+/RVR.

If you chose not to use raspi-config to configure the serial port, you can also use the graphical Raspberry Pi Configuration tool, and make the selections highlighted below:


Next, shut down your Pi from the Log Off menu, or using the terminal:

sudo shutdown now


❗️ IMPORTANT

You are now ready to connect to your RVR+/RVR!

Please use the link above to proceed, the button below will take you to setting up your OS and using Terminal, which you probably already know.


Setting Up Raspberry Pi OS

Configuration with a Monitor, Keyboard, and Mouse

⚠️ WARNING
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.

Let's move on to the basics of using the Linux terminal on your Pi.

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:

❗️ IMPORTANT

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

💡 TIP

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

Using the Terminal

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.

ℹ️ NOTE

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

💡 TIP

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.

ℹ️ NOTE

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


⚠️ WARNING

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:


❗️ IMPORTANT

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.

⚠️ WARNING

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/set_multiple_leds.py


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.

💡 TIP

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: