1. Building a robot.

This part is somewhat looser than the others. In a nutshell, find some motors, wheels, motor controllers, and some connecting materials. Throw them all at a wall and hope that they come together nicely.

I have used RobotShop.com’s:

• Scout platform
• Slightly stronger motors than the one it ships with. (Something like this.)
• Cytron 10A 5-30V Dual Channel DC Motor Driver.
• YDLIDAR G2 Lidar.
• Raspberry Pi 3 Model B.
  • Update 09/21: I could not install ROS on a Raspberry Pi 4 at the time of writing, but you can definitely do it now! Check out the Ubuntu images from Ubiquity Robotics here.

2. Installing ROS

ROS (Robot Operation System) is a framework that facilitates the use of a wide variety of packages to control a robot. Those packages range all the way from motion control, to path planning, to mapping, to localization, SLAM, perception, transformations, communication, and more. ROS provides a relatively simple way interface with those packages and the ability to create custom packages.

Note: The Raspberry Pi 4 is more computationally capable than its predecessors. However, installing ROS on the Pi3 is currently (as of December 2019) easier, and allegedly more reliable.

Get the disc image

I dowloaded the Ubuntu 16.04 Xenial with pre-installed ROS from Ubiquity Robotics. They have great instructions on how to install and download the image. The main points are:

• Download the image from the top of the page.
• Flash it to an SD card (at least 8GB). You can use Etcher, it works well.
• Connect your computer to the WiFi network that starts with ubiquityrobot. Password is robotseverywhere.
• Go to Terminal, and connect to your Pi using ssh ubuntu@10.42.0.1. Password is ubuntu.
• Run roscore to make sure that things are working properly. If you get a warning/errors, try stopping ROS and starting it again with killall -9 roscore.

3. Remotely connecting to ROS

We want to access the ROS communication messages from our laptop. This will also let us visualize things in a convenient manner (with rviz). There are a couple of steps to follow here.

• Spin a Linux machine with ROS Kinetic-Kame. Either a virtual machine or a real machine. You can use VMWare-Fusion with Ubuntu 16.04 or something similar. We will refer to that machine as the Observer machine. The robot is the Master.

• On the Master, find the ROS_IP and ROSMASTER_URI. These two things are the information both machines will need to communicate. Find the ROS_IP(being the IP address of the master computer) by running ifconfig.

• In this example (the IPs would probably be different in your network), on the robot, we set: export ROS_IP=192.168.43.228 export ROS_MASTER_URI=http://192.168.43.228:11311

On the observer laptop, we set: export ROS_IP=192.168.43.123 export ROS_MASTER_URI=http://ubiquityrobot.local:11311. This master URI looks different (but is actually the same under the alias). I believe that setting ubiquityrobot.local to 192.168.42.228 would work (should be the same as the .local), but I did not test it.

• I would add these lines to .bashrc on the Observer machine, or create a script to run them together. This is not required, but would make your life (potentially) easier in the long run (so you won’t need to type those lines every time you’d want to connect to the robot 🙂 ).

• On the master (robot), run roscore.

• On the observer, you now have access to the messages and topics that are on the Master. More on that soon.

In summary, what we have just done is:

• On the robot (the master machine running roscore):

• • Set ROS_IP is the machine IP address.
• • ROS_MASTER_URI is HTTP://:11311.

• On the observer computer:

• • Set ROS_IP is its own IP.
• • SET ROS_MASTER_URI is the robot’s IP

A couple of notes here:

• To make sure the communication works, I followed this tutorial to publish basic shapes to rviz.
• I had to make the messages compatible with Indigo, following an answer here. (The solution with downloading the common msgs Indigo folder and using the visualization_msgs package folder in catkin_ws/src.)
• In rviz, make sure to set the frame to my_frame (if following tutorial).

4. Connecting to WiFi

This part sets up and verifies proper operation of wireless internet connectivity. The information is taken from this website.

• On the robot machine, pifi add YOURNETWOKNAME YOURNETWORKPASSWORD
• Restart the Pi, sudo reboot. Now the Raspberry Pi will connect to your WiFi network on startup. To connect to it, connect your computer to the same network, and ssh ubuntu@ubiquityrobot.local with the password ubuntu.

Woo! Now both machines have internet, and can communicate over SSH.

5. Testing the lidar

This step was a bit of a doozy. It took me a while to figure out how to get the lidar to run. But I did! So hopefully you won’t have to suffer like I had to.

I am using the YDLIDAR G2 lidar for this build. The first step is to install the necessary drivers. The driver is a ROS package.

• cd catkin_workspace/src.
• git clone https://github.com/EAIROBOT/ydlidar_ros.git.
• catkin_make
• Follow the directions from the repository, written below:
• • roscd ydlidar_ros/startup
• • sudo chmod 777 ./*
• • sudo sh initenv.sh
• Go back to your catkin workspace, and run source devel/setup.bash.
• git checkout G2. This command moves you to the branch of your specific Lidar model. It is G2 in our case.
• Run catkin_make again.

Test the lidar with roslaunch ydlidar_ros lidar.launch. Visualize the scans in Rviz, by adding the topic /scan.

It may look something like this! Background may vary 🙂

6. ROS + Arduino; Getting them to talk to each other.

Our goal here is to get commands from the Raspberry Pi to the Arduino with the wish of having the Arduino tell the motors how to move. We will install rosserial, a ROS module that enables Arduino-ROS communication, on both the Raspberry Pi and the Arduino to achieve that.

• Following the steps from the ROS website, we start with installing the package. sudo apt-get install ros-kinetic-rosserial-arduino, and then, sudo apt-get install ros-kinetic-rosserial. If you are using a ROS version different from Kinetic, change the word kinetic to your version.
• In the following commands, substitute catkin_ws with the name of your catkin workspace.

cd catkin_ws/src
 git clone https://github.com/ros-drivers/rosserial.git
 cd catkin_ws
 catkin_make
 catkin_make install

• In your Arduino IDE, install the rosserial library. I found it the easiest to do it from the IDE itself: search for rosserial in the Library Manager and install it.

And that should be it!

For a test run, try the HelloWorld example, from the examples included with the rosserial library. Flash the Arduino with it and connect it to the Raspberry Pi. To run it:

• On the Raspberry Pi roscore
• In a second Raspberry Pi terminal, rosrun rosserial_python serial_node.py /dev/ttyACM0. Change ttyACM0 to the port of your Arduino. You can check the port by navigating to ~/dev/, and observing which files disappear and re-appear when the Arduino is disconnected and connected.
• In a third terminal, rostopic echo chatter to see the messages being sent.

7. Installing Hector-SLAM

This part is exciting! We will now add the mapping and (a bit later) localization functionality to our robot. We use the Hector-SLAM package. It enables us to create the maps (with a Lidar alone, no IMU needed) that we will later use for localization and navigation. ( I found this video by Tiziano Fiorenzani and the official resources on the ROS website helpful for setting Hector-SLAM up.

• Clone the GitHub repository to your catkin workspace. Navigate to the src folder and run git clone https://github.com/tu-darmstadt-ros-pkg/hector_slam.git.
• [This may fail!, see sub-bullet for work-arounds] Build your ROS workspace by running catkin_make and then sourcing setup.bash with source ~/catkin_ws/devel/setup.bash.
• • If your build gets stalled, or seems to be very slow. Do two things.
• • • Increase swap space to 1GB. Follow this tutorial for instructions.
• • Run the build with catkin_make -j2

We need to make a couple of modifications to the Hector SLAM tutorial files in order for them to work with our setup. We first take note of the transformations available to us on the \tf topic, and the reference frames they use.

• Spin the lidar node, with roslaunch ydlidar_ros lidar.launch.
• Check the communication on the /tf topic with rostopic echo /tf
• I get only one transformation:

---                                                                          
transforms:                                                                         
  -                                                                          
    header:                                                                  
      seq: 0                                                                 
      stamp:                                                                 
        secs: 1578619851                                                     
        nsecs: 284012533                                                     
      frame_id: "/base_footprint"                                            
    child_frame_id: "/laser_frame"
    transform:                                             
      translation:                                         
        x: 0.2245                                          
        y: 0.0                                             
        z: 0.2                                             
      rotation:                                            
        x: 0.0                                             
        y: 0.0                                             
        z: 0.0                                             
        w: 1.0                                             
---                        

So we see that we have only two frames. Namely /base_footprint and laser_frame. We will update the file ~/catkin_ws/src/hector_slam/hector_mapping/launch/mapping_default.launch to accommodate those.

• At the somewhat top of the file, change the first line to the second.

• UPDATE 09/21: Do not follow this bullet point. We will take care of that in a different launch file. At almost the very bottom of the file, change from/to:~

• Navigate to ~/catkin_ws/src/hector_slam/hector_slam_launch/launch/tutorial.launch, and change from/to

This should do the trick! Try it out!

• In a first terminal run the lidar with roslauch ydlidar_ros lidar.launch
• In a second terminal run Hector SLAM with roslaunch hector_slam_launch tutorial.launch

You should be able to see the results in Rviz. Choose the /map topic to visualize the map that was created.

8. Lower Level Robot Control (That’s where the Arduino comes in!)

We now want to create a ROS package that would allow ROS communication to move the robot in the world. Again, Tiziano Fiorenzani has a great video explaining the basics of what we are doing here. In a nutshell, we want to make a subscriber node that would run on the Arduino, and listen to the topic /cmd_vel. We would want to begin with sending commands from the keyboard to the robot.

To see what this topic is all about, run rosrun teleop_twist_keyboard teleop_twist_keyboard.py. In another terminal, run rostopic info /cmd_vel to see that this topic publishes the structure geometry_msgs/Twist. Run rosmsg show geometry_msgs/Twist, to see the attributes of the message. They are a linear and angular commands.

geometry_msgs/Vector3 linear
  float64 x
  float64 y
  float64 z
geometry_msgs/Vector3 angular
  float64 x
  float64 y
  float64 z

Let’s create the ROS node on our Arduino. We would want to map values in precentages (that we get from /cmd_vel) to the range [0,255] that our motor controller understands.

The entirety of the code for this node lives on the Arduino. You can find the Arduino sketch I have used here https://github.com/yoraish/lidar_bot under the arduino folder. An example for a very simple sketch that only supports forward and stopping motion is below! Check out the GitHub repo for a full program.

#if (ARDUINO >= 100)
#include 
#else
#include 
#endif

#include 
#include 
// Pin variables for motors.
const int right_pwm_pin = 5;
const int right_dir_pin = A0;
const int left_pwm_pin = 6;
const int left_dir_pin = A1;
const bool left_fwd = true;
const bool right_fwd = false;

// Default_speed.
const int default_vel = 201;

ros::NodeHandle  nh;

void MoveFwd(const size_t speed) {
  digitalWrite(right_dir_pin, right_fwd);
  digitalWrite(left_dir_pin, left_fwd);
  analogWrite(right_pwm_pin, speed);
  analogWrite(left_pwm_pin, speed);
}

void MoveStop() {
  digitalWrite(right_dir_pin, right_fwd);
  digitalWrite(left_dir_pin, left_fwd);
  analogWrite(right_pwm_pin, 0);
  analogWrite(left_pwm_pin, 0);
}

void cmd_vel_cb(const geometry_msgs::Twist & msg) {
  // Read the message. Act accordingly.
  // We only care about the linear x, and the rotational z.
  const float x = msg.linear.x;
  const float z_rotation = msg.angular.z;

  // Decide on the morot state we need, according to command.
  if (x > 0 && z_rotation == 0) {
    MoveFwd(default_vel);
  }
  else {
    MoveStop();
  }
}
ros::Subscriber sub("cmd_vel", cmd_vel_cb);
void setup() {
  pinMode(right_pwm_pin, OUTPUT);    // sets the digital pin 13 as output
  pinMode(right_dir_pin, OUTPUT);
  pinMode(left_pwm_pin, OUTPUT);
  pinMode(left_dir_pin, OUTPUT);
  // Set initial values for directions. Set both to forward.
  digitalWrite(right_dir_pin, right_fwd);
  digitalWrite(left_dir_pin, left_fwd);
  nh.initNode();
  nh.subscribe(sub);
}

void loop() {
  nh.spinOnce();
  delay(1);
}

We can control the robot from our laptop now! In separate terminal instances, run the following:

• Allow Arduino communication with rosrun rosserial_python serial_node.py /dev/ttyACM0
• Enable keyboard control with rosrun teleop_twist_keyboard teleop_twist_keyboard.py

To make our lives easier for the next time we run the teleop node, we can create a launch file!

9. Launch files.

Creating a launch file is pretty simple. The documentation at ROS.org is a great resource for that. In our case, we end up with the following launch file to launch all the necessary nodes for keyboard teleoperation with ROS and through our Arduino.

I have placed this launch file in the directory ~/catkin_ws/src/lidarbot/launch. Don’t forget to catkin_make and source devel/setup.bash !

We can now run the robot in a teleoperated mode with

roslaunch lidarbot lidarbot_teleop.launch

9. Correcting angle offset.

When I was designing the Lidar mount that I ended up 3D printing, I failed to look through the datasheet and design in in a way such that the "forward" direction of the Lidar would actually point forward. Let’s correct that.

Because of a lack of time, I chose to do it in a somewhat hack-y patch.

Navigate to /catkin_ws/src/ydlidar/sdk/src/CYdLidar.cpp, and change the function void CYdLidar::checkCalibrationAngle(const std::string &serialNumber) { to the following. We are simply overriding the angle offset value provided by the Lidar model.

Great, our Lidar’s arrow points forward now.

10. Save a map.

This section outlines two methods for creating maps. The first one is "correct" in the sense that we’ll use it for localization later. The second one will not be used. I am keeping that subsection here for reference.

I have been following the excellent tutorials provided by The Construct on YouTube. They have information about how to record a map, how to provide a map to Rviz, and how to performa localization with the map on a Husky robot. In this section we will be looking first at how to record a map.

Let’s begin by downloading the map server that will do the heavy lifting for us. We will do this with sudo apt-get install ros-kinetic-map-server on the robot Raspberry Pi.

To record a map, we should spin up the robot by executing the following commands in separate terminals:

Now that your lidar is spinning and all the nodes are up, move your robot around the room slowly until you are happy with how the map looks on Rviz (or just hope that it looks okay 🙂 ), and then run:

This command will save my_map.yaml and my_map.pgm files! These two files specify the occupancy information of the map. You can change the name of this map by changing the my_map argument to whichever name you’d like. The .pgm file can be used to visualize the map the was created. From your computer, you can use "Secure Copy", aka SCP, to download the .pgm file and visualize it. In my case, I have saved my map files to ~/catkin_ws/maps/, so I downloaded them to my Mac machine’s Downloads folder using:

Another way to save a map (this is not what you need for localization)

In separate terminals, run:

roslaunch lidarbot lidarbot_teleop.launch

roslaunch ydlidar_ros lidar.launch

roslaunch hector_slam_launch tutorial.launch

And open Rviz from another linux machine, if possible.

Now, as you"ll be driving around the space (slowly! We want the map to be built accurately, so no need to give it a hard time doing so.) you’ll see a map starting to be build in real time, in Rviz. The lighter colors are empty space, and the dark ones are obstacles.

When you think your map is sufficiently good, run the following:

rostopic pub syscommand std_msgs/String "savegeotiff"

This will save a .tif and a .tfw files in ~/catkin_ws/src/hector_slam/hector_geotiff/maps directory.

The map will look something like this:

11. Serve a saved map

In order for the navigation stack to be able to localize the robot, it needs access to the map we have just saved. Luckily, this is a fairly easy task to do! The most straightforward way to do this is by running:

If you had an Rviz session started up, you can visualize the map by showing the /map topic!

You can also set up a launch file to serve the map for you, such that you won’t have to run this command every time you require a map to be served. For example, if we create a new launch file called serve_map.launch in the lidarbot package, we can call it by roslaunch lidarbot serve_map.launch. We should populate it with something like:

Pay attention to the argument value for map_fname. Change it to the path to where you left the map files.

12.Localization

UPDATE 09/21: Localization and navigation finally works!

Our goal in the next two sections is to get our robot to localize in the known map we have recorded and navigate through the map to a specified pose.

The main components of a probabilistic localization system for a robot moving in 2D are

• Laser scanner (lidar) to answer the question: what am I seeing now?
  • We are using our YDLIDAR G2.
• Odometry to answer the question: how much has the robot moved in the recent moment?
  • Helps determine how the robot should change its previous localization estimate to accomodate the motion.
• Saved map to answer the question: which one of my pose estimates on the map is seeing a similar (simulated) laser scan to the one my real laser scan is seeing?
  • In other words, because a map gives us the ability to generate expected laser scans from any point on the map (via ray tracing), we can compare our lidar observations to different ray-traced observations generated from different points on the map and assert that the most-similar map point is the location of the robot.

Let’s go through these components one by one.

Laser scans

This is simple. We have laser scans from our YDLIDAR. Check ✔.

Odometry

This is where things get interesting. Traditionally, odometry data is extracted from accelerometers (on inertial measurement units (IMUs)) or wheel encoders, or GPS, or cameras (for visual-odometry), or optical flow, or some convex combination of all of the above.

In our setup, however, you have probably noticed that we have none of the above. We only have a laser scanner. Therefore, to get odometry data we will exploit an undocumented feature of Hector-SLAM that provides the displacement of the laser scanner over time. This has been tricky to set up — I have relied extensively on help from this ROS Answers page. Specifically, credit should be given to Maximilian Heß, the author of this package and launch file for nudging me towards the right direction.

Anyway, the important thing for you, dear reader, is the existence of the launch file localize.launch in the lidarbot package that exists in the git repo. You’ll notice that the file begins with similar content to older launch files that we have developed in this tutorial. Namely,

As you see, these lines run teleop, they run the map server, and then also publish a rigid transformation between the base frame base_link and the laser frame laser_frame. I chose to keep this transform as effectively nothing for convenience. You’ll also notice that the line starting the lidar is commented out. I have seen weird things happening when this line is run in the launch file so I just started running it separately. More on that later.

Now, we initiate a Hector-SLAM node and get its odometry. I’ll spare you the details (please look at the git repo for those). The important lines are

These few lines give a name to a map-to-scan frame, they specify base_link as the robot base frame and also the odom frame (since in our case Hector is not getting any additional odometry from an IMU), and also ask Hector to not publish a map-to-odom transformation. This will be taken care of my AMCL (the probabilistic localization package we’ll use). Additionally, we change the map topic Hector used to publish it’s SLAM-created map to a different name because we’ll be serving our own pre-made map.

There’s one more thing that has to be done to get our odometry ready. Hector publishes a topic with the odometry transformation with the name /scanmatch_odom". We need to convert the messages on this topic to tf transformations. The node odomtransformer (that Maximilian Heß created and I copied) does just that.

If you run this launch file with the code up to this point, with the commands

roslaunch lidarbot odomtransformer.launch

roslaunch ydlidar_ros lidar.launch

roslaunch lidarbot localize.launch

then you’ll be able to see an odometry transformation changing as the robot moves around via rostopic echo /tf.

13. Localization and Navigation.

To localize in a known map, we feed information from our recorded maps and the Hector SLAM odometry to AMCL, a probabilistic localization package. In the launch file mentioned above, the following lines are important– they specify the names of relevant topics and other localization parameters.

To test this setup, run the following and then, in rviz, click the publish 2D Pose Estimate button and then click on the robot location on the map. When you teleoperate the robot around the map slowly you’d want to see the state estimate changing with it to reflect the true robot pose. Make sure to visualize the estimated state topics in rviz alongside the map topic.

roslaunch lidarbot odomtransformer.launch

roslaunch ydlidar_ros lidar.launch

roslaunch lidarbot localize.launch

We make use of the ROS Navigation Stack to have the robot navigate around the map autonomously. This subset of ROS packages can plan paths in maps with dynamic obstacles and directly control robots via publishing commands to the topic /cmd_vel. Our Arduino is subscribed to this topic and uses its information to move the robot. To put this together I have followed the Navigation Stack Robot Setup page on the ROS website. It is relatively straightforward — please see the git repo for all the details. I have not optimizes the robot dimensions and thresholds yet, but they work nontheless. The files of interest are

• base_local_planner_params.yaml
• costmap_common_params.yaml
• global_costmap_params.yaml
• local_costmap_params.yaml

You’ll notice that the bottom of the launch file includes these yaml files as parameters for the Movement Stack move_base node.

These files specify robot dimensions, max and min allowed velocities, and various parameters for cost maps and navigation. Don’t forget to make and source your workspace!

Putting it all together

Run these lines!

roslaunch lidarbot odomtransformer.launch

roslaunch ydlidar_ros lidar.launch

roslaunch lidarbot localize.launch

Open rviz!

Set a 2D pose estimate!

Set a navigation goal!

Watch in absolute amazement as your robot moves to that location in space.

Simple application, wall following.

This is an old (Jan 2020) part of the tutorial. Proceed with caution.

We are done setting up our robot! It is SMORT and can drive on its own, and sense its environment. I will be updating this Github repository at a dedicated branch with code for some fun applications. The first thing on there is a wall following ROS package!

Happy building!

Update February 2021: I realized that I did not actually detail how to run this example. So here we go.

1. Head over to the repository above, and navigate to src/ros/wall_follower_sim/.

2. Copy this folder to your catkin_ws/src/ folder in your robot. This is a catkin package.

3. Build your workspace with catkin_make && ./devel/setup.bash. (I probably have typos here but you get the idea.)

4. (a) On terminal 1, run roslaunch lidarbot lidarbot_teleop.launch

   (b) On terminal 2, run roslaunch ydlidar_ros lidar.launch

   (c) On terminal 3, run roslaunch wall_follower wall_follower.launch

That should do the trick! You can adjust parameters (velocity, distance to wall) for the wall following from the associated Python files. Lower velocities are more reliable.