| Note: This tutorial assumes that you have completed the previous tutorials: ROS/Installation, Robots/AMR_Pioneer_Compatible. |
 It is appreciated that problems/questions regarding this tutorial are asked on answers.ros.org. Don't forget to include in your question the link to this page, versions of your OS & ROS, and also add appropriate tags. |
How to use ROSARIA
Description: This tutorial describes how to get started using ROSARIA with ActivMedia/MobileRobots/Adept robots (supported with Aria library).Keywords: Aria, Pioneer, ActivMedia, MobileRobots, Adept
Tutorial Level: BEGINNER
Contents
For an introductory overview of using ROS with Adept MobileRobots robots, see The AMR Pioneer Robots Portal. This page also includes links to other ROS nodes that you may need for accessory devices on your robot.
Reading the other introductory documentation on this wiki is highly recommended, if you have not already: ROS/Introduction, ROS/Concepts, ROS/Tutorials, ROS/CommandLineTools.
Certain parts of this tutorial have been edited for specific ROS versions. Choose yours here:
Install ROS
If you have not yet installed ROS, see the ROS installation instructions. The easiest OS to install ROS on is Ubuntu. Install at least the "base" set of packages.
Create your ros workspace
If you have not yet created your ROS overlay workspace in your home directory, do so now.
rosws init ~/ros-fuerte /opt/ros/fuerte
This command creates the files setup.bash, setup.sh, setup.zsh and the hidden file .rosinstall in the directory ~/ros-fuerte. These scripts are used to setup different shell environments. Assuming you use bash shell, source the setup.bash script to setup your shell environment:
source ~/ros-fuerte/setup.bash
This overlay now includes all packages that were installed in /opt/ros/groovy. It's convenient to add this to your ~/.bashrc file, so you wouldn't need to repeat this every time you open a new terminal.
echo "source ~/ros-fuerte/setup.bash >> ~/.bashrc
See fuerte/Installation/Overlays for details on working with overlays.
ROSARIA has been catkinized for groovy, so we'll create a catkin workspace
mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src catkin_init_workspace cd ~/catkin_ws catkin_make
ROSARIA hasn't been extensively tested on electric, but instructions for fuerte should work.
You can also setup separate workspaces for different versions of ROS if more than one is installed.
Bring ROSARIA into the workspace
Next, enter your workspace directory, and add ROSARIA to your workspace using the rosws tool (rosws and roslocate are from the python-rosinstall package).
cd ~/catkin_ws/src hg clone https://code.google.com/p/amor-ros-pkg
If you are using ROS Fuerte, specify the fuerte tag. (Note that this code may not contain fixes and new features added to the main development branch since.)
rosws set amor-ros-pkg https://code.google.com/p/amor-ros-pkg/ --hg -v fuerte
(The source code repository (mercurial) that contains ROSARIA is called amor-ros-pkg, and is at https://code.google.com/p/amor-ros-pkg/)
Download Updated ROSARIA
Since amor-ros-pkg is now known repository in your ros workspace, downloading the current version of ROSARIA from the amor-ros-pkg code repository online is now as simple as using rosws update while connected to the internet
rosws update amor-ros-pkg
Or, if you want to update all repositories in your workspace from their published repositories online:
rosws update
The sources have been downloaded by cloning the repository.
Building ROSARIA
Setup the environment:
As rosws already warned after merge operation:
Do not forget to do ... $ source /path/to/your/workspace/setup.sh ... in every open terminal.
(It's not necessary to do this every time you start a new terminal session. See the discusion about Environment setup at fuerte installation instructions for Ubuntu.)
Source the appropriate setup.*sh file in your terminal/shell, e.g.:
source ~/catkin_ws/devel/setup.bash
or append this to your .bashrc:
echo "~/catkin_ws/devel/setup.bash" >> ~/.bashrc source ~/.bashrc
After getting packages, compile them:
rosmake ROSARIA
ROSARIA depends on Aria metapackage in amor-ros-pkg repository which currently downloads and rebuilds ARIA-2.7.2.tgz. (Information and reference documentation and example code for the ARIA library will be found there; amor-ros-pkg/Aria.)
Note
The dependency on ARIA is handled using rosdep, and for this step to work, one should use python-rosdep (>= 0.10.15) package. You can check your version like this:
dpkg-query -W python-rosdep
If it's not the latest, this should update it:
sudo apt-get update sudo apt-get upgrade
If you haven't updated the rosdep database lately, run
rosdep update
rosdep install ROSARIA roscd catkin_make
Since downloading ARIA-2.7.2.tgz from mobilerobots.com is required to build ROSARIA, the host computer must be connected to the internet for this step to work successfully.
Run roscore
Next, run roscore from your ros workspace, if you have not done so already:
roscore
roscore must always be running for any other ROS node on this computer to work and communicate. It only needs to run once, however, you don't need to run it every time you start or restart RosAria.
Run the RosAria node
Next, run the RosAria node from the ROSARIA package. If neccesary, open a new terminal window.
rosrun ROSARIA RosAria
RosAria currently saves the log output of Aria into a log file. (This may be changed in the future to use ROS logging instead.)
To reconnect with the robot, kill RosAria (Ctrl-C) and re-run it.
ROSARIA Parameters
RosAria has a port parameter that specifies which serial port to use to connect to the robot, or it may contain a hostname and TCP port to connect remotely over TCP (for example, to connect to an AmigoBot or other robot that uses a wifi serial-bridge or to to a MobileSim simulator running on a different host.) The port parameter may be given on the command line when running the RosAria node with rosrun, or it may be changed using rosparam (before staring RosAria, or restart RosAria.) The value will be saved in the ROS parameters and reused next time you run RosAria.
To specify the port as /dev/ttyS0 (COM1, normal for robot onboard computers):
rosrun ROSARIA RosAria _port:=/dev/ttyS0
To specify TCP connection to device with IP address 10.0.126.32 on port 8101 (8101 is the default port for both wireless ethernet-serial bridges and the MobileSim simulator):
rosrun ROSARIA RosAria _port:=10.0.126.32:8101
By default, ROSARIA uses /dev/ttyUSB0 as the serial port, which is the typical name for a USB-serial converter. Use this if you are using your laptop running Linux with a USB-serial connection to control the robot. Make sure you add your user to the "dialout" group (sudo usermod -a -G dialout $USER), or change the permissions of /dev/ttyUSB0 to allow all users to access it (sudo chmod a+rw -R /dev/ttyUSB0) if using this device connection. You can check the Linux kernel logs by running dmesg after plugging in the USB-serial converter to verify that it is using /dev/ttyUSB as the device name.
If using the onboard computer, change the port to /dev/ttyS0 as in the example above.
Using MobileSim simulator
MobileSim is a simulator for use with ARIA. It provides a simple 2D simulation scalable to many robots, and useful for software testing. (It is actually based on Stage version 2.)
ARIA automatically detects MobileSim if it is running on the same computer, and will connect to it. Or, you can explicitly set it using RosAria's ~port parameter:
rosrun ROSARIA RosAria _port:=localhost:8101
MobileSim will emulate the robot base (i.e. velocity commands from the cmd_vel topic and a position estimate given via pose or odom topics -- see below) and sonar (sonar topic -- see below), but connection to other devices such as laser, camera, etc. are through separate nodes in ROS and cannot currently be connected to MobileSim.
Topics and Commands
ROSARIA provides several topics for publishing information received from the robot and devices by ARIA, and for receiving commands. These follow ROS conventions and use standard ROS datatypes and units. For example, it uses a "twist" for velocity commands, even though only some components apply to differential drive ground mobile robots, and units are translated to meters and radians as used in ROS from the millimeters and degrees used by the robot and ARIA.
Pose
ROSARIA publishes the current pose estimation received from the robot in /RosAria/pose. The type of this data is navigation_msgs/Odometry. (This pose estimation is calculated by the robot firmware as ARIA based on wheel odometry, and if preset, the optional internal gyroscope.)
This pose estimation is received from the robot every 100ms (by default), and is then published on the /RosAria/pose topic.
To view /RosAria/pose using rostopic use:
rostopic echo /RosAria/pose
Press Ctrl-C to stop.
Velocity Commands
The desired velocity of the robot is set via the /ROSARIA/cmd_vel topic. This desired velocity state is set in ARIA, which sends commands every robot cycle (100ms by default) to effect this state in the robot's embedded motion controller, which performs motor control to achieve then maintain the robot velocity automatically (using previously configured acceleration parameters).
You do not need to send commands at any fixed rate to maintain robot velocity, ARIA and the robot controller maintain the velocities. Velocity commands only need to be sent to change the desired velocities.
A standard type for robot motion commands in ROS is geometry_msgs/Twist, which contains many components (dimensions). The relevant twist components for Pioneer mobile robots are linear x (forward/back translational velocity) and angular z (rotational velocity). (In future, the Seekur robot will accept linear y for lateral velocity as well.)
The syntax for specifying twist data using the rostopic command is as follows (this example sets a linear velocity of 0.1 meters/s):
rostopic pub -1 /RosAria/cmd_vel geometry_msgs/Twist '{linear: {x: 0.1, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}'
Sonar
ROSARIA also provides the /ROSARIA/sonar topic for sonar readings. The type of this topic is a 2-dimensional sensor_msgs/PointCloud.
Bumpers
ROSARIA also provides /ROSARIA/bumper_state for bumper switch state (ROSARIA/BumperState contains two boolean arrays, front_bumpers and rear_bumpers)
Other Topics
Other topics may be added in the future as well.
See ROSARIA for the current, complete list.
Useful utilities and companion nodes
For a list of nodes used with some common accessory devices used on Pioneer robots, see Robots/AMR_Pioneer_Compatible#Hardware_Drivers_and_Simulation.
Some other useful nodes are:
- Joystick driver
(svn)) https://code.ros.org/svn/ros-pkg/stacks/joystick_drivers/trunk/joy
- Joystick remapper
(svn) http://ua-ros-pkg.googlecode.com/svn/trunk/arrg/ua_drivers/joystick_remapper
TODO: Describe how would this be done using wstool.