## page was renamed from ROSARIA/Tutorials/How to use ROSARIA with ActivMedia/MobileRobots/Adept robots
## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
### note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links
## note.0=[[ROS/Installation]]
## note.1=[[Robots/AMR_Pioneer_Compatible]]
## descriptive title for the tutorial
## title = How to use ROSARIA
## multi-line description to be displayed in search
## description = This tutorial describes how to get started using [[ROSARIA]] with ActivMedia/MobileRobots/Adept robots (supported with Aria library).
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for
## level= BeginnerCategory
## keywords = Aria, Pioneer, !ActivMedia, !MobileRobots, Adept
####################################
<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

For an introductory overview of using ROS with Adept MobileRobots robots, see [[Robots/AMR_Pioneer_Compatible|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:'''''

<<Version()>>

{{{#!wiki version electric
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|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.

{{{{#!wiki version fuerte
{{{
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.
}}}} 

{{{{#!wiki version groovy_and_newer
Set up your shell environment, so that some ROS-specific commands are available:
}}}}
{{{{#!wiki version groovy
{{{
. /opt/ros/groovy/setup.bash
}}}
}}}}
{{{{#!wiki version hydro
{{{
. /opt/ros/hydro/setup.bash
}}}
}}}}
{{{{#!wiki version indigo
{{{
. /opt/ros/indigo/setup.bash
}}}
}}}} 
{{{{#!wiki version jade
{{{
. /opt/ros/jade/setup.bash
}}}
}}}} 
{{{{#!wiki version kinetic
{{{
. /opt/ros/kinetic/setup.bash
}}}
}}}} 
{{{{#!wiki version lunar
{{{
. /opt/ros/lunar/setup.bash
}}}
}}}} 
{{{{#!wiki version melodic
{{{
. /opt/ros/melodic/setup.bash
}}}
}}}} 

{{{{#!wiki version groovy_and_newer
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.

{{{{#!wiki version fuerte
{{{
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.
}}}}

{{{{#!wiki version groovy_and_newer
{{{
cd ~/catkin_ws/src
git clone https://github.com/amor-ros-pkg/rosaria.git
}}}
}}}}

=== Install ARIA and Build ROSARIA ===

{{{{#!wiki version fuerte
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 [[fuerte/Installation/Ubuntu#fuerte.2BAC8-Installation.2BAC8-DebEnvironment.Environment_setup|Environment setup]] at fuerte installation instructions for Ubuntu.)
}}}}

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

{{{{#!wiki version fuerte
ROSARIA depends on Aria metapackage in amor-ros-pkg repository which currently downloads and rebuilds [[http://robots.mobilerobots.com/ARIA/download/archives/ARIA-2.7.2.tgz|ARIA-2.7.2.tgz]]. (Information and reference documentation and example code for the ARIA library will be found there; amor-ros-pkg/Aria.)
}}}} 

{{{{#!wiki version groovy_and_newer
==== 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. 

{{{{#!wiki version groovy hydro indigo jade
==== 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:

{{{{#!wiki version groovy_and_newer
{{{
rosrun rosaria RosAria
}}}
}}}}

{{{{#!wiki version fuerte
{{{
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 [[http://robots.mobilerobots.com/wiki/Wireless_ethernet-serial_bridge_device|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 ===
[[http://robots.mobilerobots.com/wiki/MobileSim|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|Stage]] or [[gazebo|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 <<MsgLink(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 <<MsgLink(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 <<MsgLink(sensor_msgs/PointCloud)>>.

==== Bumpers ====
!RosAria also provides `/RosAria/bumper_state` for bumper switch state:
{{{#!wiki version hydro_and_newer
[[http://ros.org/doc/hydro/api/rosaria/html/msg/BumperState.html|rosaria/BumperState]]
}}}
{{{#!wiki version groovy
[[http://ros.org/doc/fuetre/api/ROSARIA/html/msg/BumperState.html|ROSARIA/BumperState]]
}}}
{{{#!wiki version fuerte
[[http://ros.org/doc/fuerte/api/ROSARIA/html/msg/BumperState.html|ROSARIA/BumperState]]
}}}
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]].

## AUTOGENERATED DO NOT DELETE
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE