diffbot

DiffBot

DiffBot is an autonomous differential drive robot with two wheels. Its main processing unit is a Raspberry Pi 4 B running Ubuntu Mate 20.04 and the ROS 1 (ROS Noetic) middleware. This respository contains ROS driver packages, ROS Control Hardware Interface for the real robot and configurations for simulating DiffBot. The formatted documentation can be found at: https://ros-mobile-robots.com.

DiffBot	Lidar SLAMTEC RPLidar A2

If you are looking for a 3D printable modular base, see the remo_description repository. You can use it directly with the software of this diffbot repository.

Remo	Gazebo Simulation	RViz

It provides mounts for different camera modules, such as Raspi Cam v2, OAK-1, OAK-D and you can even design your own if you like. There is also support for different single board computers (Raspberry Pi and Nvidia Jetson Nano) through two changable decks. You are agin free to create your own.

Demonstration

SLAM and Navigation

Real robot	Gazebo Simulation

:package: Package Overview

• diffbot_base: ROS Control hardware interface including controller_manager control loop for the real robot. It talks to the Teensy microcontroller, whose firmware is in diffbot_firmware.
• diffbot_bringup: Launch files to bring up the hardware drivers (camera, lidar, imu, ultrasonic, …) for the real DiffBot robot.
• diffbot_control: Configurations for the diff_drive_controller of ROS Control used in Gazebo simulation and the real robot.
• diffbot_description: URDF description of DiffBot including its sensors.
• diffbot_gazebo: Simulation specific launch and configuration files for DiffBot.
• diffbot_msgs: Message definitions specific to DiffBot, for example the message for encoder data.
• diffbot_navigation: Navigation based on move_base package; launch and configuration files.
• diffbot_slam: Simultaneous localization and mapping using different implementations (e.g., gmapping) to create a map of the environment

Installation

The packages are written for and tested with ROS 1 Noetic on Ubuntu 20.04 Focal Fossa. For the real robot Ubuntu Mate 20.04 for arm64 is installed on the Raspberry Pi 4 B with 4GB. The communication between the mobile robot and the work pc is done by configuring the ROS Network, see also the documentation.

Development Container

The quickest way to a working setup on a development PC is the dev container in .devcontainer/noetic: a Docker image with ROS Noetic, Gazebo 11 and everything the DiffBot packages need. It works on Linux and on Windows with WSL 2, and CI builds the same image.

The full guide is on the documentation site: Use the Dev Container (setup on Linux and Windows, usage, updating, troubleshooting) and How the Dev Container Works.

• VS Code: install the Dev Containers extension, open your clone of this repository and choose Reopen in Container.

• Command line: with the Dev Container CLI:

  devcontainer up --workspace-folder . --config .devcontainer/noetic/devcontainer.json
  devcontainer exec --workspace-folder . --config .devcontainer/noetic/devcontainer.json bash
  

Creating the container clones rplidar_ros and remo_description, installs missing dependencies with rosdep and builds the workspace in ~/catkin_ws. Your clone of this repository is mounted at ~/catkin_ws/src/diffbot, so edits on the host show up in the container. The container uses the host network to reach the robot.

RViz and Gazebo open on the host’s display. On Windows, WSLg needs no setup. On a native Linux desktop (X11 or Wayland with Xwayland), install xauth on the host (sudo apt install xauth): before the container starts, host-x11.sh copies your display’s X11 cookie to .devcontainer/noetic/.x11/ (ignored by Git), where the container reads it. So xhost + isn’t needed.

Plain Docker works too. The image’s user has UID 1000; with another UID, use the dev container, which adapts it.

docker build -f .devcontainer/noetic/Dockerfile -t diffbot:noetic .
bash .devcontainer/noetic/host-x11.sh
docker run -it --rm --net=host -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY \
  -e XAUTHORITY=/home/ros/catkin_ws/src/diffbot/.devcontainer/noetic/.x11/xauth \
  -v "$PWD":/home/ros/catkin_ws/src/diffbot diffbot:noetic \
  bash -c "bash src/diffbot/.devcontainer/noetic/setup.sh && bash"

To set up a workspace without Docker, for example on the robot’s Raspberry Pi, follow the steps below.

Dependencies

The required Ubuntu packages are listed in software package sections found in the documentation. Other ROS catkin packages such as rplidar_ros need to be cloned into the catkin workspace.

For an automated and simplified dependency installation process install the vcstool, which is used in the next steps.

sudo apt install python3-vcstool

:hammer: How to Build

To build the packages in this repository including the Remo robot follow these steps:

1. cd into an existing ROS Noetic catkin workspace or create a new one:

   mkdir -p catkin_ws/src
   

2. Clone this repository in the src folder of your ROS Noetic catkin workspace:

   cd catkin_ws/src
   

   git clone https://github.com/fjp/diffbot.git
   

3. Execute the vcs import command from the root of the catkin workspace and pipe in the diffbot_dev.repos or remo_robot.repos YAML file, depending on where you execute the command, either the development PC or the SBC of Remo to clone the listed dependencies. Run the following command only on your development machine:

   vcs import < src/diffbot/diffbot_dev.repos
   

   Run the next command on Remo robot’s SBC:

   vcs import < src/diffbot/remo_robot.repos
   

4. Install the requried binary dependencies of all packages in the catkin workspace using the following rosdep command:

   rosdep install --from-paths src --ignore-src -r -y
   

5. After installing the required dependencies build the catkin workspace, either with catkin_make:

   catkin_ws$ catkin_make
   

   or using catkin-tools:

   catkin_ws$ catkin build
   

6. Finally, source the newly built packages with the devel/setup.* script, depending on your used shell:

   For bash use:

   catkin_ws$ source devel/setup.bash
   

   For zsh use:

   catkin_ws$ source devel/setup.zsh
   

Usage

The following sections describe how to run the robot simulation and how to make use of the real hardware using the available package launch files.

Gazebo Simulation with ROS Control

Control the robot inside Gazebo and view what it sees in RViz using the following launch file:

roslaunch diffbot_control diffbot.launch

This will launch the default diffbot world db_world.world.

To run the turtlebot3_world make sure to download it to your ~/.gazebo/models/ folder, because the turtlebot3_world.world file references the turtlebot3_world model. After that you can run it with the following command:

roslaunch diffbot_control diffbot.launch world_name:='$(find diffbot_gazebo)/worlds/turtlebot3_world.world'

db_world.world	turtlebot3_world.world

Navigation

To navigate the robot in the Gazebo simulator in db_world.world run the command:

roslaunch diffbot_navigation diffbot.launch

This uses a previously mapped map of db_world.world (found in diffbot_navigation/maps) that is served by the map_server. With this you can use the 2D Nav Goal in RViz directly to let the robot drive autonomously in the db_world.world.

To run the turtlebot3_world.world (or your own stored world and map) use the same diffbot_navigation/launch/diffbot.launch file but change the world_name and map_file arguments to your desired world and map yaml files:

roslaunch diffbot_navigation diffbot.launch world_name:='$(find diffbot_gazebo)/worlds/turtlebot3_world.world' map_file:='$(find diffbot_navigation)/maps/map.yaml'

SLAM

To map a new simulated environment using slam gmapping, first run

roslaunch diffbot_gazebo diffbot.launch world_name:='$(find diffbot_gazebo)/worlds/turtlebot3_world.world'

and in a second terminal execute

roslaunch diffbot_slam diffbot_slam.launch slam_method:=gmapping

Then explore the world with the teleop_twist_keyboard or with the already launched rqt_robot_steering GUI plugin:

When you finished exploring the new world, use the map_saver node from the map_server package to store the mapped enviornment:

rosrun map_server map_saver -f ~/map

RViz

View just the diffbot_description in RViz.

roslaunch diffbot_description view_diffbot.launch

Navigating and Mapping on the real Robot

The following video shows how to map a new environment and navigate in it

Start by setting up the ROS Network, by making the development PC the rosmaster (set the ROS_MASTER_URI environment variable accordingly, see ROS Network Setup for more details), Then follow the steps listed below to run the real Diffbot or Remo robot hardware:

1. First, brinup the robot hardware including its laser with the following launch file from the diffbot_bringup package. Make sure to run this on the real robot (e.g. connect to it via ssh):

   roslaunch diffbot_bringup bringup_with_laser.launch
   

2. Then, in a new terminal on your remote/work development machine (not the single board computer) run the slam gmapping with the same command as in the simulation:

   roslaunch diffbot_slam diffbot_slam.launch slam_method:=gmapping
   

   As you can see in the video, this should open up RViz and the rqt_robot_steering plugin.

3. Next, steer the robot around manually either using the keyboard_teleop node or using the rqt_robot_steering node and save the map with the following command when you are done exploring:

   rosrun map_server map_saver -f office
   

After the mapping process it is possible to use the created map for navigation, after running the following launch files:

1. On the single board computer (e.g. Raspberry Pi) make sure that the following is launched:

   roslaunch diffbot_bringup bringup_with_laser.launch
   

2. Then on the work/remote development machine run the diffbot_hw.lauch from the diffbot_navigation package:

   roslaunch diffbot_navigation diffbot_hw.lauch
   

   Among other essential navigation and map server nodes, this will also launch an instance of RViz on your work pc where you can use its tools to:

   1. Localize the robot with the “2D Pose Estimate” tool (green arrow) in RViz
   2. Use the “2D Nav Goal” tool in RViz (red arrow) to send goals to the robot

:construction: Future Work

Contributions to these tasks are welcome, see also the contribution section below.

ROS 2

• Migrate from ROS 1 to ROS 2

Drivers, Odometry and Hardware Interface

• Add diffbot_driver package for ultrasonic ranger, imu and motor driver node code.
• Make use of the imu odometry data to improve the encoder odometry using a Kalman filter, such as robot_localization (or the less active robot_pose_ekf).
• The current implementation of the ROS Control hardware_interface::RobotHW uses a high level PID controller. This is working but also test a low level PID on the Teensy 3.2 mcu using the Arduino library of the Grove i2c motor driver. -> This is partly implemented (see diffbot_firmware) Also replace Wire.h with the improved i2c_t3 library.

Navigation

• Test different global and local planners and add documentation
• Add diffbot_mbf package using move_base_flex, the improved version of move_base.

Perception

To enable object detection or semantic segmentation with the RPi Camera the Raspberry Pi 4 B will be upated with a Google Coral USB Accelerator. Possible useful packages:

• MSeg

Teleoperation

• Use the generic teleop_twist_keyboard and/or teleop_twist_joy package to drive the real robot and in simulation.
• Playstation controller

Tooling

• Use clang format together with .clang-format file for roscpp to comply with ROS C++ Style Guidelines

Part List Diffbot

SBC RPi 4B	MCU Teensy 3.2	IMU Bosch

Part	Store
Raspberry Pi 4 B (4 Gb)	Amazon.com, Amazon.de
SanDisk 64 GB SD Card Class 10	Amazon.com, Amazon.de
Robot Smart Chassis Kit	Amazon.com, Amazon.de
SLAMTEC RPLidar A2M8 (12 m)	Amazon.com, Amazon.de
Grove Ultrasonic Ranger	Amazon.com, Amazon.de
Raspi Camera Module V2, 8 MP, 1080p	Amazon.com, Amazon.de
Grove Motor Driver	seeedstudio.com, Amazon.de
I2C Hub	seeedstudio.com, Amazon.de
Teensy 4.0 or 3.2	PJRC Teensy 4.0, PJRC Teensy 3.2
Hobby Motor with Encoder - Metal Gear (DG01D-E)	Sparkfun

Part List Remo

Part	Store
Raspberry Pi 4 B (4 Gb)	Amazon.com, Amazon.de
SanDisk 64 GB SD Card Class 10	Amazon.com, Amazon.de
Remo Base	3D printable, see remo_description
SLAMTEC RPLidar A2M8 (12 m)	Amazon.com, Amazon.de
Raspi Camera Module V2, 8 MP, 1080p	Amazon.com, Amazon.de
Adafruit DC Motor (+ Stepper) FeatherWing	adafruit.com, Amazon.de
Teensy 4.0 or 3.2	PJRC Teensy 4.0, PJRC Teensy 3.2
Hobby Motor with Encoder - Metal Gear (DG01D-E)	Sparkfun
Powerbank (e.g 15000 mAh)	Amazon.de This Powerbank from Goobay is close to the maximum possible size LxWxH: 135.5x70x18 mm)
Battery pack (for four or eight batteries)	Amazon.de

Additional (Optional) Equipment

Part	Store
PicoScope 3000 Series Oscilloscope 2CH	Amazon.de
VOLTCRAFT PPS-16005	Amazon.de
3D Printer for Remo’s parts	Prusa, Ultimaker, etc. or use a local print service or an online one such as Sculpteo

Hardware Architecture and Wiring

DiffBot

Remo

:handshake: Acknowledgment

• Louis Morandy-Rapiné for his great work on REMO robot and designing it in Fusion 360.
• Lentin Joseph and the participants of ROS Developer Learning Path
• The configurable diffbot_description using yaml files (see ROS Wiki on xacro) is part of mobile_robot_description from @pxalcantara.
• Thanks to @NestorDP for help with the meshes (similar to littlebot), see also issue #1
• dfki-ric/mir_robot
• eborghi10/my_ROS_mobile_robot
• husky
• turtlebot3
• Linorobot

:wrench: Contributing

Your contributions are most welcome. These can be in the form of raising issues, creating PRs to correct or add documentation and of course solving existing issues or adding new features.

:pencil: License

diffbot is licenses under the BSD 3-Clause. The wheel meshes are the exception: GrabCAD’s terms apply to them, see the notice next to wheel.stl. See also open-source-license-acknowledgements-and-third-party-copyrights.md. The documentation is licensed differently, visit its license text to learn more.