In part two of the series, we will build the irobotcreate2 package from source to install on our host machine. But first, let’s have a preview of what we’re actually building! Check out the video below to see the Create 2 in action, exploring our office (skip to 0:53 to see it start moving and streaming):
Catch up on any tutorials you’ve missed:
Tutorial 1
Tutorial 2 (You are here)
Tutorial 3
Tutorial 4
Tutorial 5
You can download the source files for this project here.
1 Create and Initialize a Catkin Package
First we’ll need to create and initialize a catkin package to put our source files in. There are some great tutorials on ros.org that cover both creating and building packages.
Source the environmental variables if this is a new terminal session and go to workspace:
$ source /opt/ros/indigo/setup.bash $ cd ~/catkin_ws/src
Create the catkin package:
$ catkin_create_pkg irobotcreate2
cd to the top of your catkin workspace and build the package initially (this will be how we build the package after making any changes):
$ cd ~/catkin_ws $ catkin_make
2 What’s in the irobotcreate2 Package?
Type or copy the source files to the catkin package you just created in ~/catkin_ws/src/irobotcreate2
Alternatively you can clone the source directory to ~/catkin_ws/src/.
An overview tree view of the irobotcreate2 package is as follows:
user@host_machine:~/catkin_ws/src/irobotcreate2$ tree ├── CMakeLists.txt ├── package.xml ├── setup.py ├── launch │ ├── host_teleop.launch │ ├── target_create2.launch │ ├── unified_launch_kb.launch │ └── unified_launch_ps3.launch ├── msg │ └── instructions.msg ├── scripts │ └── target_create2.py │ └── host_keyboard_teleop.py ├── src │ ├── create2_teleop.cpp │ └── irobotcreate2 │ └── Create2Class.py │ └── __init__.py
The package as it stands has four launch files, which take care of launching the individual nodes together. The one exception is the ps3joy.py node from Joystick Drivers which must be rosrun’d manually as it requires root permissions to access the Bluetooth drivers on your host machine (more on this later). Host_teleop.launch runs on the host machine; it launches create2_teleop_node (which was created by catkin_make), the necessary joystick nodes, as well as the image_view node to receive the webcam footage from an image pipeline. Target_create2.launch runs on the target COM and launches the target_create2.py which subscribes to instructions.msg and imports the module Create2Class.py to control the Create2.
The unified_*.launch files wrap up the individual launch files and allow you to launch both the Host and Target nodes from a single launch file on the Host. Unified_launch_kb.launch launches keyboard teleoperation, and unified_launch_ps3.launch launches the nodes for joystick teleoperation, but ps3joy.py must be rosrun’d manually for the same reasons mentioned above.
The DualShock 3 controller connects to the host machine over Bluetooth where the ps3joy package reads its button values and publishes button states and values. Create2_teleop_node then reads these values, extracts the necessary information, and republishes this new information as the instructions.msg data structure (this may seem redundant, and it is: the purpose of this exercise was to demonstrate the language independence of .msg files in ROS).
2.1 CMakeLists.txt
CMakeLists.txt provides CMake (which is called by catkin_make), the necessary build instructions, as well as target install directories. More info at http://wiki.ros.org/catkin/CMakeLists.txt.
It is necessary to edit the CMakeLists.txt of the package you are building whenever you add a new file, or include a new dependency. Message, service, launch and bag files must also be included in CMakeLists.txt or they will be omitted when catkin_make is called. Special attention must be paid towards your Python and C++ (or other language) source files.
2.2 package.xml
Package.xml provides catkin_make with metadata for your package. A thorough line by line analysis and tutorial on package.xml is available on the ROS tutorials page.
CMakeLists.txt and package.xml are the key elements of a catkin package and are somewhat intertwined, any discrepancies will show up as an error when you run catkin_make, so make sure to watch the output when running catkin_make!
2.3 instructions.msg
.msg files in ROS are language independent (notice we have a C++ publisher and a Python subscriber to this message type) text files that describe the structure of a message used for communication between two nodes on a ROS network. The message file instructions.msg is an extremely simple message file used to transport the values of the two sticks on the Dual Shock 3 controller. This can be easily expanded to include more button states and values from the Dual Shock 3.
More details on the ps3joy package here.
2.4 ./scripts/target_create2.py
target_create2.py is the Python node that runs on the Gumstix COM on the Create2. ROS convention calls for all Python nodes to live under a ./scripts directory, seperate from the Python modules which live under the ./src directory.
target_create2.py subscribes to the “instructions” topic in this tutorial. It drives the Create 2’s left and right wheels with respect to the values read from the “instructions” topic.
Note: You may need to modify the first line under the main section of the code to match the path pointing to your Create 2:
create2 = Create2Class.Create2Class(“/dev/ttyUSB0”)
2.5 ./src/create2_teleop.cpp
create2_teleop.cpp is the C++ node that runs on the host machine. This node subscribes to the “joy” topic, which contains information regarding the current button state/values on the Dual Shock 3. The node sifts through this information and republishes the desired information over the network under the “instructions” topic.
Note: You may be interested in adding additional functionality by reading more button presses, or even sending commands back to the joystick (blink LEDs or vibrate). Consult the ps3joy package documentation mentioned in the previous tutorial, and modify both create2_teleop.cpp and target_create2.py to implement these new features.
2.6 setup.py, ./src/irobotcreate2/Create2Class.py and __init__.py
Create2Class.py is a standalone Python driver for the iRobot Create 2. This driver can in fact be run on its own outside of ROS. The driver wraps the serial commands necessary to access the various features made available on the Create 2. It may be worth your while to skim through this driver and play around with the features available on the Create 2. The ROS package as it is now does not fully demonstrate the capabilities of the Create 2 or Create2Class.py module
__init__.py is the file that lets the system know that there is a Python module living in this directory.
Setup.py is a necessary for for letting the system know that the ROS package contains modules and scripts to install.
More information is available at the iRobot Create 2 Open Interface Manual.
2.7 *.launch
The launch files streamline the node startup process by . Each launch file is as its name implies, host_teleop.launch is launched on the host, and target_create2.launch is launched on the target. Launch files are XML files that launch several nodes, or other launch files simultaneously.
The two unified launch files can be run instead of the two individual launch files mentioned above. These unified versions take care of launching both local and remote nodes together. The exception being when the launch sequence is important. In our case, the ps3joy.py node must be run first in its own terminal session. Only after that can unified_launch_ps3.launch be ran without errors. The unified_launch_kb.launch can be ran by itself on the host because it utilizes the keyboard for teleoperation instead of a Dual Shock 3 controller. Make sure the IP addresses in these files are changed to match your devices’ IP addresses.
More information on .launch files at http://wiki.ros.org/roslaunch/XML.
3 Building the irobotcreate2 Package
After you have cloned the source files, or created the package, move up to the top of your workspace and run catkin_make as we did for the gscam package.
$ cd ~/catkin_ws $ catkin_make
Congratulations! You’ve built the irobotcreate2 package, in part three, we’ll create our very own Yocto Project image to deploy on the Gumstix.
RSS