Note: This tutorial assumes that you have completed the previous tutorials: ROS/Installation, Robots/AMR_Pioneer_Compatible.
(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the 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

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.

Select your ROS version here:

  Show EOL distros: 

ROSARIA hasn't been extensively tested on electric, but instructions for fuerte should work.

Note, on October 11, 2013, ROSARIA was renamed to rosaria and the source code repository was moved to github from Google code. The instructions for ROS hydro have been updated for this changes, but instructions for prior versions below have not yet been tested and updated for the new name and repository location.

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 a 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 won'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.

Set up your shell environment, so that some ROS-specific commands are available:

. /opt/ros/groovy/setup.bash

. /opt/ros/hydro/setup.bash

. /opt/ros/indigo/setup.bash

. /opt/ros/jade/setup.bash

. /opt/ros/kinetic/setup.bash

. /opt/ros/lunar/setup.bash

. /opt/ros/melodic/setup.bash

Create a catkin workspace. (Your workspace directory may have any name, catkin_ws is used here as an example, but you may use a different name if you wish.)

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
catkin_init_workspace
cd ~/catkin_ws
catkin_make

Note that catkin_init_workspace must be run inside the src subdirectory, but catkin_make is used in the parent workspace directory. catkin_init_workspace only needs to be done once in the src directory.

You can setup separate workspaces for different versions of ROS if more than one is installed.

Source setup.bash

Every time you want to use the catkin workspace to build packages, you must source the special devel/setup.bash script:

cd catkin_ws
. devel/setup.bash

You must do this for every new shell or terminal window you open.

If you only use one catkin workspace, you can add this command to your .bashrc file, so that it automatically occurs for every new shell or terminal window you run.

For example, if your catkin workspace is catkin_ws in your home directory, edit .bashrc in your home directory and add the following line to the end of the file. The .bashrc file is normally hidden, but you can still reference it to edit it or enable "Show hidden files" in the file browser preferences.

. ~/catkin_ws/devel/setup.bash

If you have multiple catkin workspaces for multiple versions of ROS, you must source the setup file from inside the workspace you want to use.

Bring ROSARIA into the workspace

Next you will need to download the rosaria source code from its repository.

rosws set amor-ros-pkg https://code.google.com/p/amor-ros-pkg/ --hg -v fuerte
rosws update amor-ros-pkg

Note that '-v fuerte' will check out the latest version of ROSARIA that was tested on ROS-F, it may not contain all of the latest features and updates.

cd ~/catkin_ws/src
git clone https://github.com/amor-ros-pkg/rosaria.git

Install ARIA and Build ROSARIA

Setup the environment:

As rosws already warned after merge operation:

Do not forget to do ...
$ source ~/ros-fuerte/setup.bash
... in every open terminal.

(It's not necessary to do this every time you start a new terminal session. See the discussion about Environment setup at fuerte installation instructions for Ubuntu.)

RosAria uses the Aria library from Adept MobileRobots to communicate with the robot.

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.)

Download and Install MobileRobots ARIA Ubuntu Package

To install the latest version of ARIA, download it from http://robots.mobilerobots.com/wiki/Aria. If you are using Ubuntu 16.04 or later, install the package indicated for Ubuntu 16 or later. If you are using a previous version of Ubuntu (12.04 or later), install the package indicated for Ubuntu 12.

If you are running Ubuntu 32-bit OS, make sure you have the 32-bit ARIA package (i386) installed. If you are running Ubuntu 64-bit OS, make sure the 64-bit ARIA package (amd64) is installed. If building rosaria on a 64-bit OS, but the 32-bit libAria.so library is installed, it will not be able to link to libAria.so (resulting in a warning about incompatibly libAria.so, then failure to link)

Install the ARIA package by opening it in the Ubuntu GUI, or use the dpkg tool on the command line with its -i option, for example:

  sudo dpkg -i libaria_2.9.1+ubuntu12_i386.deb

or

  sudo dpkg -i libaria_2.9.1+ubuntu16_i368.deb

etc.

NOTE: Packages indicated for Ubuntu 12.04 can be used on any version of Ubuntu up to 16.04. Ubuntu 16.04 and later includes GCC 5+ in which the C++ standard library ABI has changed. To use an Ubuntu 12.04 ARIA package on Ubuntu 16.04, you must recompile ARIA. After installing the Ubuntu 12 package, enter the ARIA directory and rebuild ARIA:

  cd /usr/local/Aria
  make clean
  make -j4

If an Ubuntu 16 package is available, however, use that instead.

Alternative AriaCoda version

If the robots.mobilerobots.com website or the ARIA download are no longer available, then a modified fork of ARIA is also available by cloning or forking http://github.com/reedhedges/AriaCoda. Build from source code and install. See README and other notes about changes from ARIA 2.9.

Alternative `rosdep` install method

You can also use rosdep to automatically install the ARIA dependency instead if you prefer. For this step to work, you should use the 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

You can now use rosdep to automatically install the ARIA dependency.

rosdep update
rosdep install rosaria

rosdep may install any additional ROS packages not currently installed, and therefore may prompt you for your password in order to run apt-get or other package manager as root, and prompt you for confirmation of the packages to install.

It will then either install the ARIA binary package for your OS, or it will build (compile) the ARIA library from source and create and ad-hoc binary package (libaria-sourcedep), depending on binary package availability and your OS. Building (compiling) ARIA and building the "sourcedep" package may take several minutes.

Warning If using rosdep, you must remove any existing ARIA installation in /usr/local/Aria. You can uninstall an installed libaria debian package with the command apt-get remove libaria.

Since downloading the ARIA library from mobilerobots.com is required to build ROSARIA, the host computer must be connected to the internet for this step to work successfully.

If you do not wish to automatically install ARIA using rosdep, and instead use an existing installation of ARIA, you may omit the rosdep command. (You may need to install additional required ROS packages or other dependencies manually, and/or by using rosdep install -a.)

The ARIA library package installed by rosdep may not be the latest version. If you need the latest version of ARIA (e.g. for a bug fix), download and install it separately as described above.

Note about Catkin/CMake detection and caching of ARIA library location

Note: rosaria's CMake build script detects the location of the ARIA library when catkin runs cmake. If you have already tried building rosaria prior to installing the ARIA library (either via rosdep or manually), you must force catkin to re-run cmake for rosaria with catkin_make --force-cmake. Do this if you get errors while building rosaria such as "could not find such file or directory : Aria/Aria.h" or siimlar.

Build rosaria

Now build rosaria using catkin. Run this from your catkin workspace directory:

catkin_make 

This will build all packages in the catkin workspace.

You only need to install and build ROSARIA once, or when changing to new versions of ROSARIA or ARIA.

Run roscore

Next, we can start the RosAria node. First, run roscore from your ros workspace, if you have not done so already:

roscore

roscore must always be running for any other ROS node in this ROS node network to work and communicate. It only needs to run once, however, you don't need to run it every time you restart RosAria.

If you are running different nodes on different computers, only one roscore is needed, but its hostname (address) must be specified when running nodes on other computers. The RosAria node must run on a computer connected to the robot controller -- either the robot's (primary) onboard computer, or a laptop connected via serial connector to the robot HOST serial port.

Run the RosAria node

Next, run the !RosAria node from the rosaria package.

If necessary, open a new terminal window. If you have not yet done so in this terminal windows or shell, and you have not set up your .bashrc file to do so automatically, source the catkin setup script in your workspace:

cd catkin_ws
. devel/setup.bash

Unless the computer running RosAria has a DNS entry that client programs and other nodes can use to locate it, you must also set the ROS_IP environment variable before running RosAria. Normally ROS provides the local computer's hostname to other nodes, but if they cannot use this hostname, then they will not be able to connect to the RosAria node. The ROS_IP environment variable explicitly specifies the IP address to use. For example, if your computer has IP address 10.0.126.32 set ROS_IP as follows before running RosAria:

export ROS_IP=10.0.126.32

Substitute the correct IP address if different. If you are using a wireless network, use the IP address for the wireless ethernet interface (usually wlan0, wifi0, or ath0).

Next, run the RosAria node:

rosrun rosaria RosAria

rosrun ROSARIA RosAria

The first argument to rosrun specifies the package name, "rosaria". The second argument to rosrun specifies the node name, "RosAria".

Additional parameters may be set via rosrun. See below for details.

If you receive an error regarding connecting to the robot on port /dev/ttyUSB0 or similar, you may need to specify a different port via the ~port parameter. See the section below on "RosAria Parameters" for more information.

To disconnect, then reconnect with the robot, kill RosAria (by pressing Ctrl-C or using the kill command) and re-run it.

Only one program can connect to the robot at a time, so only one instance of the rosaria node (or any other program connected to the robot, such as one of the demo/example/server programs provided with ARIA or ARNL, or the p2os node) can run at a time.

Note, if you ran roscore on a different computer, set the ROS_MASTER_URI environment variable first to reference that roscore server. For example, if you ran roscore on a computer with address 10.0.100.1, set it like this:

export ROS_MASTER_URI=http://10.0.100.1:11311

You must also set ROS_MASTER_URI before running any other nodes or client programs on computers other than the computer running roscore.

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.

The default port is /dev/ttyUSB0, which will work if you have connected your Linux laptop or other computer to the robot via a USB-serial adapter, and also on the Pioneer LX which uses USB-serial adapters:

rosrun rosaria RosAria

To specify the port as /dev/ttyS0 (COM1, normal for most robot onboard computers) instead, use:

rosrun rosaria RosAria _port:=/dev/ttyS0

Make sure you have added your user to the "dialout" group (sudo usermod -a -G dialout $USER), or change the permissions of the serial port device to allow all users to access it (e.g. sudo chmod a+rw /dev/ttyUSB0 or sudo chmod a+rw /dev/ttyS0). You can check the Linux kernel logs by running dmesg after plugging in the USB-serial converter to see the name of the device interface being used.

If you have a robot with a wireless ethernet-serial bridge device with IP address 10.0.126.32, use the following command instead:

rosrun rosaria RosAria _port:=10.0.126.32:8101

If using the onboard computer on a Pioneer 3, Pioneer 2, PeopleBot, PowerBot or PatrolBot, use /dev/ttyS0 as in the example above. IF you are using the embedded computer in a Pioneer LX, use /dev/ttyUSB0.

Note that only one instance of the RosAria node may run at one time, stop any other RosAria instances before running a new one.

In addition to the port parameter, RosAria also accepts other parameters as well. See ROSARIA for a full list.

Note: When you specify a parameter using rosrun, the ROS parameter system automatically stores this setting for future use, and will use the previously set value if the parameter is omitted. Specify a new value to change.

Example Client Programs

An example set of client programs with a text-based interactive interface for running them is available from https://github.com/pengtang/rosaria_client. Read the README file for instructions. These example programs show how to publish or subscribe to ROSARIA's topics, and can be used to interactively test or demonstrate ROSARIA controlling the robot.

Launch files and other configuration

A set of configuration files including roslaunch files, URDF, etc is available from http://github.com/MobileRobots/amr-ros-config

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.

For more full-featured simulation in ROS, use stdr_simulator, Stage or Gazebo instead.

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 nav_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 '[0.1, 0.0, 0.0]' '[0.0, 0.0, 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:

BumperState contains two boolean arrays, front_bumpers and rear_bumpers)

Battery State

RosAria publishes a /RosAria/battery_state_of_charge topic for robot models which provide battery state-of-charge data (Pioneer LX, Seekur, Seekur Jr.). This is a charge percentage from 0.0 to 1.0. If a robot does not provide state-of-charge data, then this topic is not published.

RosAria publishes /RosAria/battery_voltage topic for all robot models. This is a battery voltage measurement (volts DC).

Recharging Status

RosAria can provide status on recharging a Pioneer LX robot, via the /RosAria/battery_recharge_state topic.

This is an 8-bit integer which is 0 if not charging, > 0 if recharging, and < 0 on error or no data. (Specifically -2 means no data; -1 unknown state; 0 not recharging; 1 bolk recharge; 2 overcharge state; 3 float)

If a robot does not provide recharge status, then this topic is not published.

Enable/Disable Motors

Whether the robot's motors are enabled or disabled is published as a boolean value via the /RosAria/motors_state topic.

To enable the motors, use the /RosAria/enable_motors service. To disable the motors, use the /RosAria/disable_motors service.

RosAria enables the motors when it connects to the robot, but some robots require motors to be explicitly re-enabled after the e-stop button is pressed (e.g. Pioneer LX) or a bumper hit occurs (e.g. Seekur).

Laser Rangefinders

You can optionally configure RosAria to connect to any laser rangefinder sensors configured in the ARIA robot parameters, and provide that data as well as robot data. Set the ~publish_aria_lasers parameter to true on the command line with rosrun or in your roslaunch file. For example: rosrun rosaria RosAria _publish_aria_lasers:=true.

Or, you may run a ROS node specific to your laser type. These nodes will be configurable through ROS parameters and may provide more ROS-specific data. See Robots/Pioneer for more discussion of lasers, including notes specific to the LMS-200 and Pioneer 3 robot, and for links to documentation on various ROS nodes supporting various laser rangefinder types.

Note that you will need to disable ~publish_aria_lasers if you have previously run RosAria with ~publish_aria_lasers set to true. For example: rosrun rosaria RosAria _publish_aria_lasers:=false.

Other Topics

Other topics may be added in the future as well.

See ROSARIA for the current, complete list.

Acceleration Parameters

Acceleration and deceleration parameters may be adjusted via dynamic_reconfigure: trans_accel, trans_decel, rot_accel, rot_decel, lat_accel, lat_decel. These are sent to the robot controller and it will use them as soon as any requested velocity changes to achieve that change in velocity.

Odometry Calibration

It is possible to modify odometry/position integration parameters (TicksMM, DriftFactor, RevCount) via dynamic_reconfigure. These parameters will be stored and re-set whenever the RosAria node runs.

If these parameters are not set, then the robot controller will use its saved values, usually these are default values for that model robot, but can be changed using the robot controller firmware configuration tool. Defaults often work fine for most robots, but you can tweak the calibration if you want to try to improve it slightly to adjust for worn tires or other differences in your individual robot.

If these calibration parameters are set and RosAria is changing them at startup, then RosAria will print a log message indicating that it is using these parameters and sending them to the robot.

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.

Wiki: ROSARIA/Tutorials/How to use ROSARIA (last edited 2018-08-09 13:49:22 by ReedHedges)