Rover API First Script¶
Description: This is a guided example on how to write a simple python script to use DiscoverCCRI’s RoverAPI
Tutorial Level: Beginner
Previous Tutorial: Getting Started
Next Tutorial: Utilizing More Features
Contents:
1. Prerequisites¶
This code will make use of DiscoverCCRI’s RoverAPI, which is designed to make operation of DiscoverCCRI’s rovers easy. If you are unfamiliar with the Discover project, please check out our website to learn more. The tutorial assumes that you have already set up a development environment based on the previous tutorial.
2. The Code¶
For this tutorial, we will write a simple python script that will make use of the rover’s movement, camera, and lidar capabilities. We will direct the rover to drive alone a fixed path, take photos at regular intervals, and record laser scan data from the lidar.
2.1 Writing the Code¶
First, access your development environment using the instructions from the previous tutorial, open the terminal and change into the beginner_tutorials directory you created:
cd ~/beginner_tutorials
Download the python code for this tutorial and make it an executable file:
wget https://raw.githubusercontent.com/DiscoverCCRI/RoverAPI/main/examples/first_script.py
chmod +x first_script.py
You can view and edit this code with vim first_script.py
or view the code below:
#!/usr/bin/env python3
# license removed for concision
from rover_api.discover_rover import Rover
from rover_api.discover_camera import Camera
from rover_api.discover_lidar import Lidar
from rover_api.discover_utils import finish_experiment
# initialize the objects to control the hardware
rover = Rover()
lidar = Lidar()
cam = Camera()
# take a rosbag recording of the lidar data
lidar.start_recording()
# drive in a 1 meter square
for i in range(4):
# drive forward at a rate of 0.2 m/s for 5s
rover.move_forward(0.2, 5)
# save an image of what the rover sees
cam.get_jpg()
# turn right at a rate of 15 deg/s for 6s
rover.turn_right(15, 6)
# stop the recording
lidar.stop_recording()
# finish the experiment - this will automatically call our finished_cb func
finish_experiment()
2.2 Explanation¶
#!/user/bin/env python3
Every script we write will contain this shebang, which lets the computer know which type of interpreter to use when running scripts as executables.
from rover_api.discover_rover import Rover
from rover_api.discover_camera import Camera
from rover_api.discover_lidar import Lidar
from rover_api.discover_utils import finish_experiment
For this experiment, we will need to access the rover’s lidar, camera, and movement capabilities. Additionally, we will need to use the finish_experiment() function to let the system know that our experiment is done.
# initialize the objects to control the hardware
rover = Rover()
lidar = Lidar()
cam = Camera()
First, we will instantiate the objects to actually access and control the rover’s hardware.
# take a rosbag recording of the lidar data
lidar.start_recording()
Next, we will start recording the data from the lidar. The data will be saved to a rosbag. If you are unfamiliar with ROS, that is alright. Nothing in this API requires you to know ROS, and in the future, we will save the lidar data to a more common format.
# drive in a 1 meter square
for i in range(4):
# drive forward at a rate of 0.2 m/s for 5s
rover.move_forward(0.2, 5)
# save an image of what the rover sees
cam.get_jpg()
# turn right at a rate of 15 deg/s for 6s
rover.turn_right(15, 6)
We will tell the rover to drive forward for 5 seconds at a rate of 0.2 meters per second. This will move the rover forward 1 meter.
Then we tell the rover to save a .jpg image of what the camera is seeing. These images will automatically be saved to the /experiment
directory.
After taking the photo, the rover will turn right at a rate of 15 degrees for 6 seconds, making a complete 90 degree turn.
Finally, we will tell the rover to repeat this series of steps 4 times, driving in a 1 meter by 1 meter square.
# stop the recording
lidar.stop_recording()
Next, we will direct the lidar to stop recording. This will save the rosbag file to the /experiment
directory.
# finish the experiment
finish_experiment()
Finally, we will tell the system that you are finished running your experiment. This allows the system to shut down the docker container that our
code is running in, and saves the /experiment
container with all of our data.