search

mangdangroboticsclub / mini_pupper_ros

ROS 1 & 2 repos based on Mini Pupper legged robots from MangDang
https://mangdang.store/
Apache License 2.0
105 stars 38 forks source link

readme

ROS2 VERSION   Ubuntu VERSION   LICENSE   Twitter URL

Mini Pupper ROS 2 Humble

Make sure the bsp package is installed to your pupper before installing this repositiory if you are not using a pre-built image to install this repository. Please refer to bsp for mini pupper 2 or bsp for mini pupper according to your model.

For a more detailed guide, please refer to our online documentation.

Supported Software versions

Supported Hardware versions

1. Installation

Please note that the setup of PC and the mini pupper is separated

1.1 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, if the installation is unsuccessful, repeat the steps to install the package again. 

cd ~
git clone https://github.com/mangdangroboticsclub/mini_pupper_ros.git -b ros2-dev mini_pupper_ros
cd mini_pupper_ros
./pupper_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.2 PC Setup

PC Setup corresponds to PC (your desktop or laptop PC) for controlling Mini Pupper remotely or execute simulator, if the installation is unsuccessful, repeat the steps to install the package again.
Do not apply these PC Setup commands to your Raspberry Pi on Mini Pupper.

Ubuntu 22.04 + 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
./pc_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 (which can be defined by user and is 0 in default cases) 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:

check_ROS_DOMAIN_ID.png

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)
nano ~/.bashrc
export ROS_DOMAIN_ID=42 #add to the final line of the file

# If your robot is Mini Pupper 2
export ROBOT_MODEL=mini_pupper_2

# If your robot is Mini Pupper
export ROBOT_MODEL=mini_pupper

Save the file and run the following command to apply the change.

# Terminal 1 (ssh to real mini pupper)
source ~/.bashrc
# Terminal 2 (on PC)
nano ~/.bashrc
export ROS_DOMAIN_ID=42 #add to the final line of the file

# If your robot is Mini Pupper 2
export ROBOT_MODEL=mini_pupper_2

# If your robot is Mini Pupper
export ROBOT_MODEL=mini_pupper

Save the file and run the following command to apply the change.

# Terminal 2 (on PC)
source ~/.bashrc

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:

nodeList.png

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

Press the HOME button on the controller. Then search for available bluetooth devices on your PC.

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

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_simulation main.launch.py

2.1.3 Test SLAM (Mapping) in Gazebo

Note: This step is only for PC

2.1.4 Test Navigation in Gazebo

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

2.2.2 Test SLAM (Mapping)

Note: This step requires both PC and Mini Pupper

Remotely control the Mini Pupper to complete the mapping.

2.2.3 Test Navigation


- Navigation with previously saved map from step 2.2.2
```sh
# Terminal 4 (on PC)
. ~/ros2_ws/install/setup.bash
ros2 launch mini_pupper_navigation navigation.launch.py map:=$HOME/map.yaml

2.2.4 Test dance

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

2.2.5 Image Recognition

This package base on camera, and is tested utilising a package called v4l2 camera that focuses on Raspberry Pi Camera for most systems.

Note: This step can be done by only using Mini Pupper or both PC and Mini Pupper

Before bringing up mini pupper, please change the config file under

(ssh)
~/ros2_ws/src/mini_pupper_ros/mini_pupper_bringup/config

Open the configuration file according to the model that you are using (eg. if you are using mini pupper 2 then change the value of mini_pupper_2.yaml).

Change the value of camera to true and that of lidar to false so that camera is turned on for the function as the following example of mini pupper 2.

sensors:
  lidar: false
  imu: true
  camera: true
ports: 
  lidar: '/dev/ttyAMA1'

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