This software is the brain of SGVHAK Rover, a six-wheeled rover project inspired by the Mars rovers NASA JPL sent to the red planet. It presents an HTML user interface over HTTP that can be used by any device with a web browser. It communicates with underlying motor controllers via I2C and Serial. This software is designed to run on a Raspberry Pi 3 mounted on the rover, but can be adapted to other hardware as long as it can be a wireless access point and communicate with serial and I2C peripherals.
The source code is intended to be easy for others to understand and tinker with. So it is kept as simple as possible with the following intentional tradeoffs:
- Functionality is limited to driving the rover as a big remote control car. No autonomous functionality.
- Not robust against unreliability network. (Noisy WiFi environments.)
- Not secured against hostile network attackers.
And most of all: no multithreading. Threading is very easy to get wrong, causing problems that are difficult to debug. Since this project is intended to be easy for aspiring robot programmers to pick up and play with, using multiple threads would raise the barrier to entry significantly. Admittedly, avoiding multithreading does limit the features we can implement with this software. But anyone who outgrows the capabilities of this software package hopefully will also be ready to move on to a different robot software platform. (Related note: Though the underlying Flask web platform is capable of multi-thread and multi-process, it will only run as a single thread in a single process when running in development server mode as per instructions below.)
Setup for development & testing
python 2.7.14 with associated
- Python version dictated by Ion Motion Control's RoboClaw Python API, which is written for 2.7. See http://forums.ionmc.com/viewtopic.php?f=2&t=542
virtualenv recommended to help keep Python libraries separate.
- Install virtualenv
pip install virtualenv
- Switch to SGVHAK_Rover directory
- Create new virtual environment
python -m virtualenv venv
- Activate virtual environment
. venv/bin/activate. Prompt should now be prepended with
- All Python dependencies are described in setup.py and can be installed with
pip install -e .(Don't forget the period at the end of the command.)
- All HTML related dependencies are copied in the
/static/subdirectory and no installation is necessary. Because the HTML UI is served up from the Raspberry Pi 3 acting as an access point without actual internet connectivity, we could not ask the user's web browser to download jQuery and Materialize. Instead, we have a local copy to serve up for use.
- To enable debugging (warning: development only)
- Open UI by pointing web browser to
Setup for Rover Raspberry Pi
- Clone this repository and set up python, pip, and virtualenv as described above. Manually launch Flask and a web browser to verify the web app launched successfully.
- Configure flask for launch on startup by editing
/etc/rc.localand add the following just above
exit 0at the end of that file.
cd /home/pi/SGVHAK_Rover export FLASK_APP=SGVHAK_Rover . venv/bin/activate flask run --host=0.0.0.0 &
- Configure Pi to be a wireless access point by following instructions at https://www.raspberrypi.org/documentation/configuration/wireless/access-point-routed.md
- Once complete, connect to the new Pi-hosted wireless access point and open a web browser (default URL is
http://192.168.4.1:5000) to use rover UI.
In order to drive a six-wheel rover, we need to control the relative velocities of its six driven wheels and the steering angles for each of the four corner steerable wheels. This calculation is the core of the project, and can be found in
After the calculations have been made, their results can be sent to one of several motor control control module that will drive the actual mechanical parts. This implementation has the following motor control module implementations to match hardware installed on the rover:
- A low-cost low-end servo motor solution controlled with the Adafruit PWM HAT. Adafruit provides a Python library which is wrapped via
- A midrange solution with brushed DC motor matched with a quadrature encoder for closed-loop feedback. Controlled via Ion Motion Control's RoboClaw modules. Ion Motion Control likewise provides a Python library, which is wrapped via
- For testing purposes, a nonoperative solution that serves as placeholder when running on a system that has none of the above controllers installed. All operations return success code with no actual effect. This is implemented by
roboclaw_stub.pyinstead of the actual RoboClaw Python API.
menu.py and the root menu is in
index.html. The flexibility of HTML allows quick experimentation for different methods to present a rover user interface to the user. Several experimental UI are included and they all use the same underlying
move_velocity_radius API of
Configurations and Modifications
roverchassis.py requires knowing the physical layout of rover's wheels in order to properly calculate velocity and angle. Physical layout is described by specifying each wheel's (x,y) coordinate inside
config_roverchassis.json. The coordinate system used is: Looking down on the rover from above, the front of the rover is the +Y axis and the right side of the rover is the +X axis. The center of the rover is the origin. The example length values in the repository are in inches, but any unit (either metric or imperial) may be used as long as they are used consistently. Since
roverchassis.py calculations are made on their relative ratios.
Aside from physical geometry,
config_roverchassis.json also specifies two motor controlls for each wheel. One for the rolling travel motion, and the other for steering control.
- A freely rolling, undriven wheel will have
nullas its rolling control.
- A wheel that has no steering motor will have
nullas its steering control.
- It is valid to have a wheel that has
nullfor both values. For example, a caster wheel.
When RoboClaw controller is used, relevant parameters must be present in
config_roboclaw.json. See Ion Motion Control's RoboClaw documentation for details.
- Connection parameters: serial port, baudrate, etc.
- Velocity PID values must be present if RoboClaw is controlling any rolling travel motors.
- Position PID values must be present if RoboClaw is controlling any steering motors.
Adafruit Servo HAT Parameters
When Adafruit PWM HAT is used, relevant parameters must be present in
- Connection parameters: I2C address, I2C bus, PWM frequency.
- The following parameter for each of 16 servo addresses:
- PWM value for center position.
- Maximum travel range, expressed in degrees off center.
- PWM value for the maximum positive travel. (Minimum is assumed symmetric and will be calculated from other parameters.)
move_velocity_radius API on
roverchassis.py to utilize all the same code calculating velocity/angle and sending them to the motor controllers.
Additional Motor Controllers
Other motor control classes may be added as peers of
adafruit_servo_wrapper.py. The new motor control module must be initialized in
init_motorcontrollers(). Then its name may be used in
config_roverchassis.json to specify its usage as wheel rolling or steering control.