Spirit Raspberry Pi Setup
Pi Software Install:
The Pi should be running the Raspbian Operating system. This operating system includes the base software needed to run the Pi. However, we will be doing some other things with our Pi that require some extra bits of software to be added.
To install this software, complete the steps in the previous section "Initial Configuration", then connect to your Pi using an SSH client.
Perform the following steps in order, and carefully pay attention to exactly how the commands are entered.
First we will make sure all the software on the Pi is updated to most current versions. Type the following commands, one at a time and let each complete before doing the next. They may each take a while to complete. Sometimes they appear to hang, but just give them time and they should complete and return you to the normal command prompt.
NOTE: If the Pi does hang for a long time and you loose connection via your SSH client, make sure the Spirit power is still turned on (the left most blue LED named "PWR" should still be turned on). If you have problems with power turning off, plug in the robot via USB for a while and let the battery re-charge then begin from the previous successful step in your setup).
sudo apt-get update
sudo apt-get dist-upgrade (when prompted for space, type Y to confirm)
sudo apt-get clean
Install Git Core:
sudo apt-get install git-core
sudo apt-get install i2c-tools
Install python-smbus python module:
sudo apt-get install python-smbus
sudo pip install smbus2
Set I2C bus baud rate to 400kHz:
Edit /boot/config.txt with
sudo nano /boot/config.txt
Use arrow keys to move down to the very bottom of the file and enter the following new line to the file:
Press Control-X, then Y, then Enter to save the new version of the file.
Set up Python and set up a new VirtualEnv (virtual environment) to run the Spirit Rover python code:
Install the 2.7-dev python module:
sudo apt-get install libpython2.7-dev (Press Y to continue after the disk space check)
Install NeoPixel Code:
sudo pip install rpi_ws281x
Install virtualenv for python:
sudo pip install virtualenv
Set up a new virtual environment for the rover software:
virtualenv --system-site-packages rover
It is very important to include the --system-site-packages in the command. This will create a new directory and python executable in ~/rover/bin/python, and allow the new virtual environment to use the main system packages already installed.
Configure the Pi to start running python inside this new virtual environment automatically when the Pi boots:
Edit the .bashrc file. This is a script file that runs at each login.
nano .bashrc (Note the period before the file name)
Go to the end of this file and add the following line:
Exit and save the file with Control-X, T, then Enter
Reboot the Pi:
This will drop connection in your SSH client. Wait a minute or so and re-connect a new SSH session. You may need to let your Pi boot for a minute or two before you can establish a new SSH session.
When you log back in, you should see the following prompt:
(rover) pi@raspberrypi:~ $
Note the command line now starts with
(rover) This indicates you are working in the new virtual environment created for your Spirit Rover code.
Setup the Plum Geek Pixel Server and Shutdown Monitor on the Pi:
The pixel server is a control system we wrote ourselves for the Spirit rover. Controlling the physical pins on the Raspberry Pi processor requires "root" access, and communicating with the NeoPixel LED lights requires signals from these physical pins. Normally, you will log into the Pi as user "pi" which does not have root access. To get around this, we kick off a script that runs in the background, which in turn controls the pixels. You can use your normal user code (run by the user "pi" or any other user) to talk to this pixel server and control the lights. The pixel server also allows for doing cool automated fades and simple color animations automatically in the background. This section describes how to install and setup the pixel server.
The Shutdown Monitor watches a special pin that is triggered by the Spirit Mainboard just before the unit powers off. When this line is held low for about 1/2 second, this shutdown monitor script causes the Raspberry Pi to immediately shut down. It is important to allow Linux computers to gracefully shut down (rather than just pulling the power) to avoid possible problems with the file system. Once this shutdown monitor script is installed it works in the background and you can power the Spirit on and off without worrying about it.
PG Pixel Server:
Copy the folder pgpixelserver into the rover folder you created earlier. Use an SFTP client for this. The pgpixelserver folder should have five files inside it.
After the folder and contents are copied, you will need to make the launcher script file executable.
Make both launcher script files executable:
chmod u+x ~/rover/pgpixelserver/pgpixelserver_launcher.sh
chmod u+x ~/rover/pgpixelserver/shutdownmonitor_launcher.sh
Create a directory for pixel server logs:
Add entry to Cron to start the Pixel Server and Shutdown Monitor on boot:
Start the crontab editor. (Make sure you use "sudo" here, so you will be editing the root crontab, which is important for allowing the neopixel code to access the physical control pin on the Pi):
sudo crontab -e (Select option 2 "nano" from prompt)
Move to the bottom of the file and enter the following lines. The first is just a note, the second is the line that is actually executed. You may want to copy and paste this into the editor, it is fairly long and complicated and needs to be entered exactly as shown.
(Note, the gitbook may wrap the following lines. The code below should be entered as 3 separate lines. The first starts with the # symbol, and the two starting with @reboot are complete lines - the end parts 2>&1 may wrap in the gitbook, but they should be entered on the same line as the beginning @reboot).
# start PG Pixel Server and Shutdown Monitor on boot
@reboot sh /home/pi/rover/pgpixelserver/pgpixelserver_launcher.sh >/home/pi/rover/logs/cronlog 2>&1
@reboot sh /home/pi/rover/pgpixelserver/shutdownmonitor_launcher.sh >/home/pi/rover/logs/cronlog 2>&1
In Linux, crontab is a system that automates background tasks. By issuing the @reboot instruction we are telling cron to execute this line each time the Pi is booted. The line causes Linux to run the pgpixelserver_launcher.sh script, and place any logs or errors into the logs directory we created earlier. This will launch the pixel server in the background.
After entry is made, press Control-X to exit and save.
Reboot the Raspberry Pi, then test to make sure the pixel server started up without problems.
After reboot, log back into the Pi and lets check a few things.
This command prints the contents of the cronlog. If everything went as expected, this log should presently be empty, so the above command should not produce any output. If there was a problem starting the pixel server, you will likely find some cryptic errors displayed from this file.
Try one more quick check:
ls -la ~/rover/pgpixelserver
This will list the contents of the pgpixelserver directory. If the pixel server started up, you should now see a new file in this directory named PixAnimation.pyc (note the "c" on the end). If this file is present, it indicates the pixel server has started up at least one time.
If both of the above checks are good, you should have a happily running pixel server from this point forward.
You can verify the shutdown monitor script is working correctly by logging into an SSH session, then press and hold the Spirit Power button (PWR) until the PWR LED beings to blink (this is the blue LED on the far left). Once the shutdown sequence has been initiated, you should see the following line broadcast to your SSH terminal just before connection is lost:
Spirit Shutdown Now!
If you have any problems with either of these scripts, go back and make sure your entry in the crontab is exactly correct, and that you have correctly made both launcher scripts executable in the steps above.
Add Actual Python Code to Spirit:
Now that we've done the bare bones setup, we can finally add a directory with some code!
Copy the folder
democode into the
rover directory you created earlier. Use SFTP to accomplish this.
Important Note: When using the Pi to control your Spirit Rover, it is suggested to load the Arduino sketch "Spirit_BaseSketch_PiControl" onto the Arduino processor. This sketch just waits for motor control signals from the Pi and doesn't do anything else. You can add your own code to this Arduino sketch as well if you like, but generally you will control the robot from either the Arduino processor or the Pi.
There are two important files in the democode directory:
spirit_pixels.py. These files should be present in any directory where you run other spirit python files from.
The other files in this directory are code examples that can be run and edited.
You can run the examples like this:
This will run the "volts.py" script, which displays battery voltage in your terminal window. Try the others and see what happens.
Most of the important functions are contained in the
spirit_core.py file. They generally work the same as similarly named functions in the Arduino base sketch. You can have a look over this core file to see what functions are available. Generally you should use the functions that are in all lower case lettering. Some functions contain upper case letters, but these functions are generally used by other functions within the core file and generally shouldn't be called on their own.
This is the end of this section for now. We will update this and add more detail about the use of the functions soon. This is just to get the more advanced users started.