Setting Up Raspberry Pi 3, 3 B+ or Zero W
Raspberry Pi is more than just a board that you can load a few programs you wrote on your computer onto and have a litte fun; it is a fully fledged computer! We are looking forward to seeing all the fun you're able to have by connecting your Raspberry Pi to your RVR. The processes below can help you get on your feet, no matter what stage of Raspberry Pi use you are at!
Getting Your Raspberry Pi RVR-Ready
We have both a Python SDK and Node/Client SDKs that you can use with the Raspberry Pi and RVR.
There are two main ways to setup your Raspberry Pi with the Sphero SDK(s). The first method is meant for users who want to get up and running as soon as possible. The second method is meant for users that might already have existing projects on their Pi, and want to add our SDK(s) as an addition to their existing setup.
Method 1
You can download our version of the latest Raspbian preconfigured with the Sphero SDK from here. Once downloaded, unzip it to produce a .img file. You'll need a tool to write this image unto a micro SD card. We recommend using Balena Etcher, but you can use any tool you're familiar
with. Insert your micro SD card into your computer before moving on.
If you're using Balena Etcher, open the application, and select the .img file you previously unzipped.
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. You might get prompted to enter the login password for your computer. You should see the UI update with progress bar.
Once the writing process is complete, eject the micro SD card, and insert it into your Raspberry Pi. Be sure to attach a monitor, keyboard, and mouse. When the desktop loads, you might see some pop-up dialogs regarding a system update, and updating the default password. Close these for now, they will reappear every time the Raspberry Pi boots up.
Open the terminal, and type in the following command:
sudo raspi-config --expand-rootfs
This will expand the file system to take up the space available on the micro SD card you are using. Without it, you might find your storage and memory space limited. Go ahead and shut down the Pi.
sudo shutdown now
The changes will take effect the next time your Pi boots up, but first let's connect your Raspberry Pi to your RVR.
Method 2
Before you can do anything with your RVR and your Raspberry Pi, you'll need to set your Raspberry Pi up with an operating system and configure a few settings. Raspberry Pi's general setup is a very easy step by step process to follow and works just fine for getting your Raspberry Pi up and running quickly. Once you've installed an OS on your Raspberry Pi, there are just a few more things to do in order to make your Raspberry Pi capable of communicating with your RVR.
Gathering Your Tools
The following commands are to be input into your terminal, which you can get to by clicking the icon at the top of your screen:
If you're not working with a freshly set up (ie the previous step) Raspberry Pi, make sure your Raspbian is up to date by running:
sudo apt update
sudo apt dist-upgrade
sudo apt clean
sudo reboot
Get the Code
We have two options for obtaining the RVR Raspberry Pi code from GitHub (Python or Node.js/Client.js)... cloning the repo with git or downloading a ZIP of the repo...
Downloading a Zip File
This method is nice because it allows you to download the files in a way similar to how you are used to downloading anything to your computer. The disadvantage is that it is not very agile, so any time we update the code, you need to go through this whole process again....
To download a zip file of the repo, while still working on your Raspberry Pi, find the repo on GitHub (Python or Node.js/Client.js) and navigate to the green "Clone or download" button, just above the list of files on the right side of your screen. 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 "Download ZIP".
Once the ZIP file has downloaded, you'll be able to extract it; we recommend choosing the main "pi" directory to load the code into, so that it is easy to access (and your code will be in the same place as ours, making it easier to follow along with our examples 😉).
Using Git
Using git to get the code onto your Raspberry Pi is a bit more 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 (Python or Node.js/Client.js).
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 Raspberry Pi code to live; for example, we want to just put our code in the pi folder in our home directory and the terminal starts us in the home directory, so we just need to do:
cd pi
Note:cd stands for "change directory", which allows you to move down a level in your folder structure. If you get an error when you run this, saying that it can't be found, try typing ls (and then pressing enter) to get your bearings of where you are in your folder structure (ls will print all the files and folders within the folder you are in). Doing cd ../ will move you up a level in the folder structure, if you are too deep in to access the pi folder 😄
From there, you'll jump into your browser and head over to the GitHub (Python or Node.js/Client.js), where you'll navigate to the green "Clone or download" button, just above the list of files on the right side of your screen. 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
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!).
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 code (if you put yours where we suggested, you should be in pi/raspberry-pi) and run:
git pull
Install The Dependencies
For this guide, we recommend using Pipenv.
Pipenv is a tool used to run the Sphero SDK virtual environment (also known as a VM). It's considered good practice to run python projects (like our SDK) in a VM in order to keep all dependencies local to a project folder. This is done in order to not interfere with the Raspberry Pi's global libraries and tools, including the default version of Python, which other projects might depend on.
In order to install Pipenv, all you have to do is run the first-time-setup.sh script by running the following command:
./first-time-setup.sh
When the installation completes, the script will prompt you to reboot your Pi, if you opt to do so 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.
Setting Up Your Virtual Environment
Before we get too far, check what versions of Python are available on your Raspberry Pi (no need to change the version) by jumping back into the terminal and running:
ls /usr/bin/python*
Your output should look something like this:
We'll need Python version 3.5 or above, which should be available to you if you have the most recent Raspbian, but it is always good to check 😉
As we mentioned earlier, it's good practice to install project-specific dependencies into a virtual environment. Our Raspberry Pi SDK comes with the Pipfile that Pipenv uses to setup the VM. You only need to run the command below once to get the VM setup. Assuming Python 3.7 is your latest available version, your command will read as:
pipenv --python /usr/bin/python3.7
If your latest version is 3.5, swap out the 7 for a 5 in the code above; if your latest version is below 3.5, you can update Python using the process outlined in our Python Getting Started Guide.
Once your virtual environment is created, run the following command to install the SDK dependencies:
pipenv install
Note: This process can take a while on a Raspberry Pi Zero W.
Now, you are ready to connect your Raspberry Pi to your RVR and start going through our examples (the code for which can be found in the scripts in the getting_started folder), or jump right into writing your own code!
Connecting Your Raspberry Pi to your RVR
Note: Never just kill power to your Raspberry Pi; always shut it down before removing power (unplugging it).
To set up the Raspberry Pi on top of RVR, connect its ground and serial pins on the GPIO to those on the RVR and power it using the USB Type A port on RVR.
If the Raspberry Pi is oriented so that the USB ports face downwards, then the 3rd (black cable), 4th (yellow cable), and 5th (orange cable) pins from the top in the right column of the Raspberry Pi GPIO, in order, are ground, Tx, Rx.
On the RVR, there are 4 pins next to the USB port. If the RVR is oriented with the topper-release button facing to the right, from left to right, the pins are voltage, ground, Tx and Rx.
To connect these pins, connect ground to ground, and then Tx on the Raspberry Pi to Rx on the RVR, and Rx on the Raspberry Pi to Tx on the RVR. Your Tx and Rx (yellow and orange) wires should be crossed.
Once you're connected, you can go ahead and power up RVR, which will also power your Pi. When the Desktop loads, bring up the terminal (either with your keyboard/mouse/monitor plugged in OR via SSH), and head over to the "Starting Programs" section to start running programs on RVR.
SSH and Serial Port
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 around in style with an entirely wireless setup (aside from the cables connecting your RVR to your Raspberry Pi)! 😎
If this sounds like a blast, follow Raspberry Pi's Secure Shell access tutorial to get set up! Note: In addition to enabling Serial Port in Preferences > Raspberry Pi Configuration > Interfaces, you want to disable Serial Console, so that the remote computer can actually reach the Raspberry Pi and send it commands for the RVR.
Once that 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 from your laptop, desktop, or other device!
On Raspberry Pi Monitor (before you disconnect)
The device you want to use to control the RVR must be on the same wifi network as is your Raspberry Pi. This means that you'll need to get your Raspberry Pi connected to the wifi network you'll want to use for this connection before you disconnect it from its monitor/mouse/keyboard.
Additionally, we'll use the IP address of the RVR to SSH into it, so the next thing we'll need to do is gather that information. Get the IP address of the RVR by jumping into your terminal (on your Raspberry Pi) and entering:
hostname -I
Your IP address is often the same, especially as long as you are staying 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.
Note: It is not a bad idea to run the commands below (in the terminal on your remote machine) and make sure that they work before completely abandoning your Raspberry Pi's monitor/mouse/keyboard setup.
On Remote Computer
On your laptop/desktop/etc (that is connected to the same wifi network as your Raspberry Pi), you'll jump into the terminal and use this command to access your Raspberry Pi:
ssh pi@ipaddress
Once you run this command, you'll be prompted for the password to your Raspberry Pi. Again, you'll get no indication that your password is being typed as you type it.
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.
Starting Programs
Once the VM setup is complete and your RVR is connected to your Pi, any time you want to work on RVR python programs, be sure to start the VM from within the root SDK folder.
Assuming the SDK is located at /home/pi/sphero-sdk-raspberrypi-python, to ensure you are in the right place, use the following command:
cd ~/sphero-sdk-raspberrypi-python
The character ~ represents the /home/pi directory.
Now activate the VM with the following command:
pipenv shell
If you see the name of the SDK folder in parentheses before your command prompt, you are now in a project-specific VM!
If you'll be running the example scripts from the getting_started folder, you can use cd to get to the directory of the example you'd like to execute, and then you can run that code using:
python scriptname.py
Exiting the VM
Once you are finished working with the SDK, you can exit the VM in one of two ways.
- by issuing the following command:
exit
- by pressing
Ctrl + D.
Turning Off Your Raspberry Pi
Once you are finished playing with your Raspberry Pi/RVR, make sure to shut down your Raspberry Pi:
sudo shutdown now