User's Guide

Getting Started with WilsonROS

Installing ROS kinetic

ROS kinetic can be installed as described here.

A VM with an ubuntu with pre-installed ROS can be found here: PC-Setup ROS-Kinetic

Requirements for WilsonROS

WilsonROS requires some packages which can be installed e.g. on ubuntu using this command:

sudo apt-get -y install ros-kinetic-openslam-gmapping ros-kinetic-smach-viewer

Initialization and compiling WilsonROS

Create a directory and initialize a workspace for WilsonROS

mkdir -p wilsonros/src
cd wilsonros/src
catkin_init_workspace

Clone the repository into the src folder

git clone https://github.com/WilsonROS/wilson_ros

Go to the wilsonros folder and compile the project.

cd ..
catkin_make

It may appear that catkin_make fails at first, repeating this command can solve the issue.

Preparing the environment

The environment variables for WilsonROS can be set persistently using this commands, assuming that the workspace folder was created in the home directory:

cat - >> ~/.bashrc <<EOF
export ROS_MASTER_URI=http://10.42.0.1:11311/
cd ~/wilsonros/
source ./devel/setup.bash
EOF

source ~/.bashrc

Starting Nodes

WilsonROS has different components in order to provide the desired functionality. There are for example components for the navigation stack and the mapping process.

Most of the components are composed into a set of launch files, which makes them easier to use because you simply run some commands like roslaunch <launchfile>. To get more information about launch files please read the documentation of roslaunch.

WilsonROS also provides launch files to test in a simulator on the local machine.

Simulator

There exist mainly two files to test functionality inside the simulator, namely home_sim.launch and mapping_sim.launch.

Therefore you start the mapping process in the simulator with

roslaunch wilson_ros mapping_sim.launch

and the autonomous movement with

roslaunch wilson_ros home_sim.launch

respectively.

Note that you can only start one of those at a time. For further use of both of these modes alls the guidelines and rules of later sections apply.

While the simulator is running, you can also start the visualizations as explained below.

Turtlebot 2

WilsonROS surely provides nearly the same convenient methods to execute the nodes on real hardware in the real world. If you did not already build the robot, please refer to this section of the Developer's Guide.

In order to start the robot itself you need to connect to the robot using SSH like the following:

ssh turtlebot@10.42.0.1.

This is the terminal where remote commands get executed.

The mapping on the real robot is started using this command remotely:

roslaunch wilson_ros mapping.launch

This will not start the controller, so you are not able to move the robot. This is explained in the next section.

For the autonomous movement this command has to be executed remotely:

roslaunch wilson_ros boot.launch

This launches a set of nodes to do all the planning and navigation and such on the robot. However, depending on the computing unit you choose it may be necessary to split some of the work. In that case you should execute the follwing command remotely:

roslaunch wilson_ros boot_minimal.launch

and the follwing three commands locally:

roslaunch wilson_ros coverage.launch

roslaunch wilson_ros zone_generator.launch

roslaunch wilson_ros planner.launch

In this case only slightly more than the minimum necessary is running on the robot. You can also split the above three commands on multiple machines, as long as each machine has the same ROS environment setup.

Start Each Node Separately

For more flexibility you can start each node separately. This allows for more distribution and parameterization. To keep it short, this is the only command which must be run remotely:

roslaunch turtlebot_bringup boot.launch

For the mapping part you can run either locally or remotely:

roslaunch wilson_ros slam_gmapping_pr2.launch

For the autonomous movement there are a few parts more involved. Here is a list of all necessary commands:

roslaunch wilson_ros nodelet.launch

roslaunch wilson_ros amcl.launch

roslaunch wilson_ros navigation_stack.launch

roslaunch wilson_ros coverage.launch

roslaunch wilson_ros zone_generator.launch

roslaunch wilson_ros planner.launch

These commands may be distributed in any way, as long as all machines use the same ROS master. However, consider the network latency in you environment and the comparatively slow connection speeds of wifi.

Shutdown the Robot Gracefully

In order to shut down the robot gracefully you just need to terminate all remotely executed commands. This can be done by pressing CTRL-C inside the terminal running the SSH session. After everything is shut down this way feel free to run sudo poweroff.

Moving the Robot

The robot is moving in most cases autonomously. Only in the mapping process the robot needs to be guided. A controller is added to the project ('src/controller/') to move the robot. To control the robot run the following command locally inside the workspace:

rosrun wilson_ros controller

It connects to the rosmaster and opens the following window.

This window is the controller. When the window is focused, the user can move the robot.

The user can use the keys ...:

• 'w' or 'W' or 'KEY_UP' - to move straight ahead
• 's' or 'S' or 'KEY_DOWN' - to move backwards
• 'a' or 'A' or 'KEY_LEFT' - to move to left
• 'd' or 'D' or 'KEY_RIGHT' - to move to right.

The robot moves straight ahead or backwards with a speed of 0.05 (double) and moves to left or right with a speed of 0.33 (double).

To end moving the robot just abort the controller with CTRL-C on the terminal where you started it.

Using rviz

rviz is a useful tool when it comes to debugging and monitoring the behaviour of your robot with WilsonROS. With it you are for example able to fix the position of the robot or to visualize the progress of the behaviours, as follows in the next sections.

Starting rviz

To start rviz you just need to run rosrun rviz rviz after you started roscore locally. For WilsonROS we created to launch files which will load some useful settings to monitor the robot and are described in the next sections.

Mapping Visualization

To get this visualization in rviz during the mapping-part run the following command locally inside the workspace:

roslaunch wilson_ros visualization_mapping.launch

Coverage Visualization

To get this visualization in rviz during the coverage&navigation-part run the following command locally inside the workspace:

roslaunch wilson_ros visualization_coverage.launch

Navigation Visualization

To get this visualization in rviz during the coverage&navigation-part run the following command locally inside the workspace:

roslaunch wilson_ros visualization_navigation.launch

Floor Mapping

To create a map run the following command via ssh on the robot:

roslaunch wilson_ros mapping.launch

The laser sensor is now scanning the environment. The robot also begins to build a map from the receiving scans. In the next step you can move the robot (for more information how to move the robot see above). Do not move the robot too hastily. This can cause some problems during the mapping and at the end the map can contain some fuzzy sections which means that coverage cannot be carried out effectively. Since the robot has cropped laser beams, it is recommended to visit every location on the floor. The map will be even better if visited every possible location and return back to the initial position.

You need to start the controller as described in Moving the Robot.

Using the visualization on rviz you can follow the mapping process on your laptop locally.

The following images shows a step by step visualization of a building floor.

• Hint: Do not forget that the laser is mounted at a certain height. It is possible that some low obstacles cannot be identified. So move the robot carefully and always try to keep eye contact with the robot.
• Hint: Try to drive loops whenever it possibly makes sense. The map can get more accurate if the robot is able to relocalise himself in a known part of the map.

Once you are satisfied with the map (you should definitely monitor the mapping!) you need to save it using the following command remotely:

rosrun map_server map_saver -f map

This creates the files ~/map.yaml and ~/map.pgm. These files are loaded automatically for coverage and navigation.

Floor Navigation

To start the coverage&navigation process you need 3 ssh connections to the robot. In the first connection run the following command:

roslaunch wilson_ros coverage.launch

In the second connection run the following command:

roslaunch wilson_ros boot_minimal.launch

In the third connection run the following command:

roslaunch wilson_ros navigation_minimal.launch

If you want to visualize the coverage / navigation data you may use rviz as described above.

Fixing the initial position of the robot

The initial position is used and published by AMCL. It can be configured by editing the launch/amcl.launch file. But first one needs to know the new position. This can be achieved as follows

1. Booting up the robot (as explained above) 
2. Starting RViz from the command line with rviz (with a configured command line, as explained above)
3. Adding relevant topics to the visualization: /map, /amcl_pose
4. Selecting "2D pose estimate" ant place it at the new position approximately. The AMCL position should move to the point previously selected
5. The command line shows the newly selected pose
6. The launch file needs to be edited to match the position from the command line