ROS-Maver-X4

中文 | English

Adaptation Repository: hex_toolkit_maver_x4

---

Introduction

All the ROS packages we provide are open source. The repository hex_toolkit_maver_x4 contains all the necessary features. You can review and modify it yourself.

However, configuring ROS packages can be complex and prone to various dependency issues. Therefore, we provide a pre-configured Docker image to help avoid compatibility problems.

We offer two configuration tutorials: one using Docker containerization and one without Docker.

Please note that we will not provide any assistance for any compatibility issues that arise from configurations not using Docker. Moreover, the non-Docker tutorial will only demonstrate up to the point where you can use cmd_vel to control the actual vehicle.

If you are using a newly installed Ubuntu computer with only ROS and plan to use only cmd_vel and odom, you can also choose without Docker.

1. Docker Containerized Configuration

1.1 Obtain Docker Image

Use docker pull to get the image

docker pull hexfellow/hex-docker-noetic-maver-x4

1.2 Initialize Working Directory

Create folders according to the following structure:

~/hex_docker/
├── application
│   ├── catkin_ws
│   │   └── src
│   └── git_source
└── docker_shell

mkdir -p hex_docker/application/catkin_ws/src hex_docker/application/git_source hex_docker/docker_shell

1.3 Configure Startup Script

Create a start.sh script in the docker_shell directory and enter the following content

Warning

Configure the following according to whether you are using an Nvidia GPU. If your computer is not using an Nvidia GPU, remove --runtime=nvidia --gpus all and -e NVIDIA_DRIVER_CAPABILITIES=display,compute.

cd ~/hex_docker/docker_shell && vim start.sh

#!/usr/bin/env bash

HOST_USER=$(whoami)
SHELL_DIR=$(dirname "$0")

CURRENT_DIR=$(pwd)
cd $SHELL_DIR

docker run -dit \
  # Container name, you can replace `hex-docker-humble-maver-x4` with a name you like
  --name=hex-docker-humble-maver-x4 \ 
  --net=host \
  --ipc=host \
  --runtime=nvidia --gpus all \
  -e NVIDIA_DRIVER_CAPABILITIES=display,compute \
  -e DISPLAY=$DISPLAY \
  -e QT_X11_NO_MITSHM=1 \
  -e XDG_RUNTIME_DIR=/run/user/$(id -u $HOST_USER) \
  --privileged \
  -v /dev:/dev:rw \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  -u $(id -u $HOST_USER):$(id -g $HOST_USER) \
  -v /run/user/$(id -u $HOST_USER):/run/user/$(id -u $HOST_USER):rw \
  -w /home/hexfellow \
  hexfellow/hex-docker-noetic-maver-x4

cd $CURRENT_DIR

1.4 Start the Container

Run the start.sh script

cd ~/hex_docker/docker_shell
chmod +x start.sh
./start.sh

Use the following command to enter the container. After attach, all operations in this terminal will be executed inside the container.

docker attach hex-docker-humble-maver-x4

If you are unfamiliar with using Docker containers, you can refer to various Docker tutorials available online.

1.5 Compile and Run the Keyboard Control Demo

In the container terminal, run the following commands to compile

cd /home/hexfellow/catkin_ws
colcon build

Next, demonstrate how to use the keyboard control node to test if the environment configuration is successful:

w, s, a, d, j, l: represent forward, backward, left, right, counterclockwise rotation, and clockwise rotation, respectively.

Warning

⚠️ Before controlling the actual vehicle, ensure that the vehicle's IP address is correctly configured. Please refer to IP Address Settings. ⚠️

The demo pulled is for ROS2. If you pulled the ROS1 image, change the last line to: roslaunch hex_toolkit_maver_x4 key_ctrl.launch

cd /home/hexfellow/catkin_ws
source install/setup.bash --extend
ros2 launch hex_toolkit_maver_x4 key_ctrl.launch.py

You can then control the actual vehicle movement in the terminal.

PS: Docker Usage Tips

To run multiple programs, use tmux. You can refer to this tutorial.

To suspend the current container, press Ctrl+p followed by Ctrl+q. To resume after suspension, use the command below

docker attach hex_noetic_basic

To exit the current container, simply type exit. To restart the container after exiting (when it is in a stopped state), use the command below

docker start hex_noetic_basic

2. Native Configuration on Industrial PC

Warning

⚠️ We will not provide any assistance for any compatibility issues that arise from configurations not using Docker. ⚠️

2.1 Preparation

Install the necessary packages:

sudo apt update
sudo apt install python3-pip
sudo apt install git

Create workspace and dependency directories:

mkdir -p catkin_ws/src git_source
cd ~/git_source

2.2 Install and Compile Dependency Libraries

2.2.1 Install protoc, choose the version suitable for your computer's architecture

Run the following command to check your computer's architecture

uname -a

For Linux x86_64:

wget https://github.com/protocolbuffers/protobuf/releases/download/v27.1/protoc-27.1-linux-x86_64.zip
sudo unzip protoc-27.1-linux-x86_64.zip -d /usr/local
rm protoc-27.1-linux-x86_64.zip

For Linux arm64:

wget https://github.com/protocolbuffers/protobuf/releases/download/v27.1/protoc-27.1-linux-aarch_64.zip
sudo unzip protoc-27.1-linux-aarch_64.zip -d /usr/local
rm protoc-27.1-linux-aarch_64.zip

2.2.2 Install Dependency Libraries

cd ~/git_source
git clone https://github.com/hexfellow/hex_vehicle_python_lib.git
cd hex_vehicle_python_lib
git submodule update --init
python3 -m pip install .

2.3 Install and Compile Basic ROS Packages

Enter the src directory of the ROS workspace and clone the required packages:

cd ~/catkin_ws/src
git clone https://github.com/hexfellow/robot_hardware_interface.git

ROS1:

cd .. # Return to catkin_ws root directory
source /opt/ros/noetic/setup.bash
catkin_make

ROS2:

cd .. # Return to catkin_ws root directory
source /opt/ros/humble/setup.bash
colcon build

2.4 Real Vehicle Control Test

ROS1:

source devel/setup.bash --extend
# Replace <ip addr> with the actual vehicle's IP address. The IP address lookup method has been introduced in previous sections.
roslaunch robot_hardware_interface chassis_bringup.launch ws_url:="ws://<ip addr>:8439" simple_mode:=true

ROS2:

source install/setup.bash --extend
# Replace <ip addr> with the actual vehicle's IP address. The IP address lookup method has been introduced in previous sections.
ros2 launch robot_hardware_interface chassis_bringup.launch.py ws_url:="ws://<ip addr>:8439" simple_mode:=true

Then, open an additional terminal to run the following command to control the real vehicle movement

ROS1:

rosrun robot_hardware_interface chassis_key_control.py

ROS2:

ros2 run robot_hardware_interface chassis_key_control