Mini Pupper ROS 2 Humble

Supported versions

Ubuntu 22.04 + ROS 2 Humble

1. Installation

To use Gazebo simulator, "1.1 PC Setup" is required.
To control Mini Pupper, "1.2 Mini Pupper Setup" is required.
To control Mini Pupper using visualize tools, "1.1 PC Setup" and "1.2 Mini Pupper Setup" is required.
To use Gazebo simulator or control Mini Pupper using joystick, "1.4 Joystick Setup" is required.

1.1 PC Setup

PC Setup corresponds to PC (your desktop or laptop PC) for controlling Mini Pupper remotely or execute simulator.
Do not apply these PC Setup commands to your Raspberry Pi on Mini Pupper.

Ubuntu 22.04 + ROS 2 Humble is required.

cd ~
sudo apt update
git clone https://github.com/Tiryoh/ros2_setup_scripts_ubuntu.git
~/ros2_setup_scripts_ubuntu/ros2-humble-ros-base-main.sh
source /opt/ros/humble/setup.bash

After ROS 2 installation, download the Mini Pupper ROS package in the workspace.

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
git clone https://github.com/mangdangroboticsclub/mini_pupper_ros.git -b ros2-dev mini_pupper_ros
vcs import < mini_pupper_ros/.minipupper.repos --recursive

Build and install all ROS packages.

cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
sudo apt install ros-humble-teleop-twist-keyboard
sudo apt install ros-humble-teleop-twist-joy
colcon build --symlink-install

Reference(Just for reference, don't need to do it again.):

installation document for ROS Humble or

unofficial ROS 2 installation script

1.2 Mini Pupper Setup

Mini Pupper Setup corresponds to the Raspberry Pi on your Mini Pupper.
Ubuntu 22.04 is required.

Before installation, you need to install the BSP(board support package) repo for your Mini Pupper 2 or Mini Pupper.

After installing the driver software, install ROS 2 Humble is required.

cd ~
git clone https://github.com/mangdangroboticsclub/mini_pupper_ros.git -b ros2-dev mini_pupper_ros
cd mini_pupper_ros
./install.sh

Reference(Just for reference, don't need to do it again.):

installation document for ROS Humble or

unofficial ROS 2 installation script

1.3 Connecting Mini Pupper to PC

The mini pupper is assumed to be automatically connected to the PC under same internet environment, but to make sure the mini pupper is connected to the PC, we can check their ROS domain ID according to the following steps:

# Terminal 1 (ssh to real mini pupper)
export | grep "ROS_DOMAIN_ID"

# Terminal 2 (on PC)
export | grep "ROS_DOMAIN_ID"

Compare the output and check if they are the same in both terminals:

Example output:

If the ID are different in both terminal or there is no output of the above commnand, you will have to set the ROS_DOMAIN_ID to the same number using the following command (which number is used does not matter):

To tackle the example output, we can use the following command to set the same id on both terminal:

This command can be used on both PC and Mini Pupper

# Terminal 1 (ssh to real mini pupper)
export ROS_DOMAIN_ID=42

# Terminal 2 (on PC)
export ROS_DOMAIN_ID=42

Use the following command in both terminals to confirm that the PC and the mini pupper are connected:

# Terminal 1 (ssh to real mini pupper)
ros2 node list

# Terminal 2 (on PC)
ros2 node list

Compare the output in both terminals:

If the output in both terminals shows the same list of node which is similar to the picture, your PC and the mini pupper is connected. The following steps can be proceeded. Note that the node list depends on the nodes in progress, which may not be exactly the same from the image.

1.4 Joystick Setup

Connection to PC Press the HOME button on the controller. Then search for available bluetooth devices on your PC.
Connection to Mini Pupper using USB port Plug the controller to the robot through a USB Type A to USB Micro wire.
Connection to Mini Pupper using Bluetooth Press the HOME button on the controller.

#Terminal 1 (ssh)
bluetoothctl scan on #then look for your sevice address

#Terminal 2 (ssh)
bluetoothctl trust <address of your controller>
bluetoothctl connect <address of your controller>

To check whether the joystick is connected

#(ssh or PC)
sudo apt install joystick 
jstest /dev/input/js0 # there will be output once the joystick is connected

2. Quick Start

2.1 PC

2.1.1 Test in RViz

Note: This step is only for PC

# Terminal 1
. ~/ros2_ws/install/setup.bash # setup.zsh if you use zsh instead of bash
ros2 launch mini_pupper_bringup bringup.launch.py hardware_connected:=False

# Terminal 2
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_bringup rviz.launch.py

If using keyboard control

# Terminal 3
. ~/ros2_ws/install/setup.bash
ros2 run teleop_twist_keyboard teleop_twist_keyboard

If using joystick control

# Terminal 3
. ~/ros2_ws/install/setup.bash
ros2 launch teleop_twist_joy teleop-launch.py

2.1.2 Test in Gazebo

Note: This step is only for PC

# Terminal 1
. ~/ros2_ws/install/setup.bash # setup.zsh if you use zsh instead of bash
ros2 launch mini_pupper_gazebo gazebo.launch.py

If using keyboard control

# Terminal 2
. ~/ros2_ws/install/setup.bash
ros2 run teleop_twist_keyboard teleop_twist_keyboard

If using joystick control

# Terminal 2
. ~/ros2_ws/install/setup.bash
ros2 launch teleop_twist_joy teleop-launch.py

2.1.3 Test SLAM (Mapping) in Gazebo

Note: This step is only for PC

Bring up Gazebo

# Terminal 1
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_gazebo gazebo.launch.py

Mapping on PC

# Terminal 2
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_slam slam.launch.py use_sim_time:=true

If using keyboard control

# Terminal 3
. ~/ros2_ws/install/setup.bash
ros2 run teleop_twist_keyboard teleop_twist_keyboard

If using joystick control

# Terminal 3
. ~/ros2_ws/install/setup.bash
ros2 launch teleop_twist_joy teleop-launch.py

Save the map

# Terminal 4 (on PC)
. ~/ros2_ws/install/setup.bash
ros2 run nav2_map_server map_saver_cli -f ~/map

The map will be saved under home directory. Two files will be generated, namely map.pgm and map.yaml.

2.1.4 Test Navigation in Gazebo

Bring up Gazebo

# Terminal 1
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_gazebo gazebo.launch.py

Navigation

# Terminal 2
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_navigation navigation.launch.py use_sim_time:=true

Alternatively, if you wish to use the map you generated in previous step, you can specify the map path with the following command.

ros2 launch mini_pupper_navigation navigation.launch.py use_sim_time:=true map:=$HOME/map.yaml

After executing this command, the rviz window will be displayed. You can utilize the "2D Post Estimate" feature to establish an appropriate initial pose for the robot. Subsequently, you can set a goal for the robot by clicking on "Nav2 Goal", hence Nav2 will plan the path and guide the robot towards reaching the goal.

2.2 Mini Pupper

2.2.1 Test walk

Note: This step is only for Mini Pupper

Open 2 terminals and ssh login to Mini Pupper on both.

# Terminal 1 (ssh)
. ~/ros2_ws/install/setup.bash # setup.zsh if you use zsh instead of bash
ros2 launch mini_pupper_bringup bringup.launch.py

If using keyboard control

# Terminal 2 (ssh or PC)
. ~/ros2_ws/install/setup.bash
ros2 run teleop_twist_keyboard teleop_twist_keyboard

If using joystick control

# Terminal 2 (ssh or PC)
. ~/ros2_ws/install/setup.bash
ros2 launch teleop_twist_joy teleop-launch.py joy_dev:=<device file path (usually start with /dev/input/...)>

2.2.2 Test SLAM (Mapping)

Note: This step requires both PC and Mini Pupper

Bring up real mini pupper

# Terminal 1 (ssh to real mini pupper)
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_bringup bringup.launch.py

SLAM on PC

# Terminal 2 (on PC)
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_slam slam.launch.py

Remotely control the Mini Pupper to complete the mapping.

If using keyboard control

# Terminal 3 (on PC)
. ~/ros2_ws/install/setup.bash
ros2 run teleop_twist_keyboard teleop_twist_keyboard

If using joystick control

# Terminal 3 (on PC)
. ~/ros2_ws/install/setup.bash
ros2 launch teleop_twist_joy teleop-launch.py

Save the map
Run the following command from a new terminal.

# Terminal 4 (on PC)
. ~/ros2_ws/install/setup.bash
ros2 run nav2_map_server map_saver_cli -f ~/map

The map will be saved under home directory. Two files will be generated, namely map.pgm and map.yaml.

2.2.3 Test Navigation

Bring up real mini pupper

# Terminal 1 (ssh to real mini pupper)
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_bringup bringup.launch.py

Navigation with previously saved map from step 2.2.2

# Terminal 4 (on PC)
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_navigation navigation.launch.py map:=$HOME/map.yaml

2.2.1 Test dance

Please refer to the README.md inside package "mini_pupper_dance".

License

Copyright 2022-2024 MangDang

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

FAQ

Q. Is Ubuntu 20.04 supported?
- A. No. Ubuntu 22.04 only for now.
Q. Is ROS 2 Foxy/Galactic supported?
- A. No. ROS 2 Humble only for now.

Q. colcon build shows 1 package had stderr output: mini_pupper_driver.

A. The following warnings can be safely ignored. See mini_pupper_ros#45 for details.

Starting >>> mini_pupper_description
--- stderr: mini_pupper_driver
/usr/lib/python3/dist-packages/setuptools/command/easy_install.py:158: EasyInstallDeprecationWarning: easy_install command is deprecated. Use build and pip and other standards-based tools.
  warnings.warn(
/usr/lib/python3/dist-packages/setuptools/command/install.py:34: SetuptoolsDeprecationWarning: setup.py install is deprecated. Use build and pip and other standards-based tools.
  warnings.warn(
/usr/lib/python3/dist-packages/pkg_resources/__init__.py:116: PkgResourcesDeprecationWarning: 1.1build1 is an invalid version and will not be supported in a future release
  warnings.warn(
/usr/lib/python3/dist-packages/pkg_resources/__init__.py:116: PkgResourcesDeprecationWarning: 0.1.43ubuntu1 is an invalid version and will not be supported in a future release
  warnings.warn(
---
Finished <<< mini_pupper_driver [7.37s]