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:

• Python 3.7

• Git (recommended, but not required)

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:

Setting Up Raspberry Pi OS

Configuration with a Monitor, Keyboard, and Mouse

1. Connect your monitor, keyboard, and mouse to your Raspberry Pi, following the connection section of the official Raspberry Pi setup guide.

2. Plug your USB power supply cable into an outlet and connect it to your Raspberry Pi's power port. You'll see a red light indicating that your Pi is booting and raspberries will appear in the upper left corner of your screen.

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

3. If you didn't already do it, follow the Start up your Raspberry Pi section of the Raspberry Pi setup guide as well. This will walk you through powering up your Pi, connecting to WiFi, and updating your operating system. Be aware that updating the Raspberry Pi operating system may take a few minutes.

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

❗️ 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.

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

• If your network administrator has blocked SSH. (This can be an issue in schools)

• If you prefer to do all your development directly on the Raspberry Pi without a separate computer.

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

1. Open the Raspberry Pi Configuration from the Preferences menu in the upper left corner of the screen.

2. Select the Interface tab.

3. Toggle the SSH radio button to Enabled.

4. Click OK.

Option 2: Use the raspi-config command.

1. In the terminal, enter sudo raspi-config.

2. Select Interfacing Options.

3. Select SSH.

4. Select Yes.

5. Select Ok.

6. Select Finish.

ℹ️ 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.

❗️ 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:

• If you're new to Python and RVR+/RVR, following the basic tutorials in the First Programs section is a great idea. Start here.

• If you're more experienced, you can check out the example scripts in the getting_started directory of the SDK (default ~/sphero-sdk-raspberrypi-python/getting_started) to see how various RVR features can be used.

• We also have some sample projects you can check out for inspiration.