This repo contains a ROS driver and ROS configuration files (URDF description, Gazebo launch files, move_base config, bringup launch files, message and action descriptions) for the MiR robots. This is a community project created by us (DFKI, the German Research Center for Artificial Intelligence) to use the MiR Robots with ROS. We are not affiliated with Mobile Industrial Robots. If you find a bug or missing feature in this software, please report it on the issue tracker.
This repo has been confirmed to work with the following robots:
It probably also works with the MiR1000. If you can test it on one of those, please let us know if it works.
This repo has been tested with the following MiR software versions:
You can try if it works with other versions, but these are the ones that are known to work.
:warning: Do NOT update to the upcoming version 3.0; it is very well possible that this repo will no longer work with this version!
mir_actions
: Action definitions for the MiR robotmir_description
: URDF description of the MiR robotmir_dwb_critics
: Plugins for the dwb_local_planner used in Gazebomir_driver
: A reverse ROS bridge for the MiR robotmir_gazebo
: Simulation specific launch and configuration files for the MiR robotmir_msgs
: Message definitions for the MiR robotmir_navigation
: move_base launch and configuration filesYou can chose between binary and source install below. If you don't want to
modify the source, the binary install is preferred (if mir_robot
binary
packages are available for your ROS distro). The instructions below use the ROS
distro noetic
as an example; if you use a different distro (e.g. melodic
),
replace all occurrences of the string noetic
by your distro name in the
instructions.
If you haven't already installed ROS on your PC, you need to add the ROS apt repository. This step is necessary for either binary or source install.
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
wget http://packages.ros.org/ros.key -O - | sudo apt-key add -
sudo apt-get update -qq
For a binary install, it suffices to run this command:
sudo apt install ros-noetic-mir-robot
See the tables at the end of this README for a list of ROS distros for which binary packages are available.
For a source install, run the commands below instead of the command from the "binary install" section.
# create a catkin workspace
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src/
# clone mir_robot into the catkin workspace
git clone -b noetic https://github.com/DFKI-NI/mir_robot.git
# use rosdep to install all dependencies (including ROS itself)
sudo apt-get update -qq
sudo apt-get install -qq -y python-rosdep
sudo rosdep init
rosdep update
rosdep install --from-paths ./ -i -y --rosdistro noetic
# build all packages in the catkin workspace
source /opt/ros/noetic/setup.bash
catkin_init_workspace
cd ~/catkin_ws
catkin_make -DCMAKE_BUILD_TYPE=RelWithDebugInfo
In case you encounter problems, please compare the commands above to the build
step in .github/workflows/github-actions.yml
; that should always have the most
recent list of commands.
You should add the following line to the end of your ~/.bashrc
, and then
close and reopen all terminals:
source ~/catkin_ws/devel/setup.bash
https://user-images.githubusercontent.com/320188/145610491-2afeb46c-3729-4106-ab9c-6681b5dd9d2e.mp4
### gazebo:
roslaunch mir_gazebo mir_maze_world.launch
rosservice call /gazebo/unpause_physics # or click the "start" button in the Gazebo GUI
### localization:
roslaunch mir_navigation amcl.launch initial_pose_x:=10.0 initial_pose_y:=10.0
# or alternatively: roslaunch mir_gazebo fake_localization.launch delta_x:=-10.0 delta_y:=-10.0
# navigation:
roslaunch mir_navigation start_planner.launch \
map_file:=$(rospack find mir_gazebo)/maps/maze.yaml \
virtual_walls_map_file:=$(rospack find mir_gazebo)/maps/maze_virtual_walls.yaml
rviz -d $(rospack find mir_navigation)/rviz/navigation.rviz
Now, you can use the "2D Nav Goal" tool in RViz to set a navigation goal for move_base.
### gazebo:
roslaunch mir_gazebo mir_maze_world.launch
rosservice call /gazebo/unpause_physics # or click the "start" button in the Gazebo GUI
### mapping:
roslaunch mir_navigation hector_mapping.launch
# navigation:
roslaunch mir_navigation move_base.xml with_virtual_walls:=false
rviz -d $(rospack find mir_navigation)/rviz/navigation.rviz
https://user-images.githubusercontent.com/320188/171613044-639f3ab2-fe84-4839-acfc-d0642f8869b3.mp4
This repo contains URDF descriptions for the MiR 100 (default) and the MiR 250.
You can switch to the MiR 250 by adding mir_type:=mir_250
to the gazebo
roslaunch command. You can also select another Gazebo world using the
world_name
argument. For example, the video above was generated using the
following commands:
cd <your catkin workspace>
git clone -b ros1 https://github.com/aws-robotics/aws-robomaker-small-warehouse-world.git
catkin build
roslaunch mir_gazebo mir_empty_world.launch \
world_name:=$(rospack find aws_robomaker_small_warehouse_world)/worlds/no_roof_small_warehouse.world \
mir_type:=mir_250
... and then running the remaining commands from the "mapping" section above.
If you want to spawn multiple robots into Gazebo, you unfortunately have to
hard-code the name of the second robot into the mir_empty_world.launch
file,
like this:
diff --git i/mir_gazebo/launch/mir_empty_world.launch w/mir_gazebo/launch/mir_empty_world.launch
index 27b9159..7773fae 100644
--- i/mir_gazebo/launch/mir_empty_world.launch
+++ w/mir_gazebo/launch/mir_empty_world.launch
@@ -17,6 +17,10 @@
<remap from="$(arg namespace)/mobile_base_controller/cmd_vel" to="$(arg namespace)/cmd_vel" />
<remap from="$(arg namespace)/mobile_base_controller/odom" to="$(arg namespace)/odom" />
+ <remap from="mir2/joint_states" to="mir2/mir/joint_states" />
+ <remap from="mir2/mobile_base_controller/cmd_vel" to="mir2/cmd_vel" />
+ <remap from="mir2/mobile_base_controller/odom" to="mir2/odom" />
+
<include file="$(find gazebo_ros)/launch/empty_world.launch">
<arg name="world_name" value="$(arg world_name)"/>
<arg name="paused" value="true" />
Then you can run the simulation like this:
# start Gazebo + first MiR
roslaunch mir_gazebo mir_maze_world.launch tf_prefix:=mir
# first MiR: start localization, navigation + rviz
roslaunch mir_navigation amcl.launch initial_pose_x:=10.0 initial_pose_y:=10.0 tf_prefix:=mir#
roslaunch mir_navigation start_planner.launch \
map_file:=$(rospack find mir_gazebo)/maps/maze.yaml \
virtual_walls_map_file:=$(rospack find mir_gazebo)/maps/maze_virtual_walls.yaml prefix:=mir/
ROS_NAMESPACE=mir rviz -d $(rospack find mir_navigation)/rviz/navigation.rviz
# spawn second MiR into Gazebo
roslaunch mir_gazebo mir_gazebo_common.launch robot_x:=-2 robot_y:=-2 tf_prefix:=mir2 model_name:=mir2 __ns:=mir2
# second MiR: start localization, navigation + rviz
roslaunch mir_navigation amcl.launch initial_pose_x:=8.0 initial_pose_y:=8.0 tf_prefix:=mir2
roslaunch mir_navigation start_planner.launch \
map_file:=$(rospack find mir_gazebo)/maps/maze.yaml \
virtual_walls_map_file:=$(rospack find mir_gazebo)/maps/maze_virtual_walls.yaml prefix:=mir2/
ROS_NAMESPACE=mir2 rviz -d $(rospack find mir_navigation)/rviz/navigation.rviz
The internal robot PC's is not synchronized (for example via NTP), so it tends
to get out of sync quickly (about 1 second per day!). This causes TF transforms
timing out etc. and can be seen using tf_monitor
(the "Max Delay" is about
3.3 seconds, but should be less than 0.1 seconds):
$ rosrun tf tf_monitor
Frames:
Frame: /back_laser_link published by unknown_publisher Average Delay: 3.22686 Max Delay: 3.34766
Frame: /base_footprint published by unknown_publisher Average Delay: 3.34273 Max Delay: 3.38062
Frame: /base_link published by unknown_publisher Average Delay: 3.22751 Max Delay: 3.34844
Frame: /front_laser_link published by unknown_publisher Average Delay: 3.22661 Max Delay: 3.34159
Frame: /imu_link published by unknown_publisher Average Delay: 3.22739 Max Delay: 3.34738
Frame: /odom published by unknown_publisher Average Delay: 3.16493 Max Delay: 3.28667
[...]
All Broadcasters:
Node: unknown_publisher 418.344 Hz, Average Delay: 0.827575 Max Delay: 3.35237
Node: unknown_publisher(static) 465.362 Hz, Average Delay: 0 Max Delay: 0
To fix this:
Afterwards, the ROS software on the robot will restart, so you'll have to start move_base
again (see below).
If you have an external PC on the MiR platform, you can use chrony
to automatically synchronize system time (see below).
move_base
on the robotmove_base
and amcl
on the robotIf the robot's localization is lost:
roslaunch mir_driver mir.launch
If you have an external PC integrated into your robot that is on the same wired
network as the MiR PC, you can use chrony
to automatically synchronize the
MiR's system time. Unfortunately, this method is not easy to install.
Let's call the external PC external-pc
. That PC's clock is our reference
clock. It is synced to an NTP clock whenever the external-pc
has access to
the internet. To implement this synchronization solution, install chrony
on
both the external-pc
and the internal PC of the MiR, and set up the
external-pc
as the chrony server and the internal MiR PC as the chrony
client. This way, the clocks on these systems always stay in sync without any
manual interaction.
To install things on the internal MiR PC:
Connect a monitor, keyboard and USB stick with a live Linux system to the ports that are exposed on one corner of the MiR.
Boot into the live USB Linux system.
chroot
into the MiR PC:
Mount MiR partition and bind /dev, /run etc. You can use fdisk -l to figure out which partition to mount. (Here it's sda3):
sudo mkdir -p /media/mir
sudo mount /dev/sda3 /media/mir
for dir in /dev /dev/pts /proc /sys /run; do sudo mount --bind $dir /media/mir/@$dir; done
chroot
into the MiR PC:
sudo chroot /media/mir/@/
Create user:
adduser newuser
usermod -aG sudo newuser
Reboot and log into MiR PC via SSH and the newly created user name.
Install Chrony:
sudo apt update
sudo apt install chrony
# if not installable (to fix broken dependencies):
sudo apt -f install
sudo apt install chrony
Set up /etc/chrony/chrony.conf
.
Make sure all old ntp configs are configured in chrony. For this, add the following to your chrony.conf (the old ntp.conf part is commented out):
# Clients from this subnet have unlimited access, but only if
# cryptographically authenticated.
#restrict 192.168.12.255 mask 255.255.255.0 nomodify notrap nopeer
allow 192.168.12.0/24 nomodify notrap nopeer
Sometimes the move_base action will print the warning "Got a result when we
were already in the DONE state". This is caused by a race condition between the
/move_base/result
and /move_base/status
topics. When a status message with
status SUCCEEDED
arrives before the corresponding result message, this
warning will be printed. It can be safely ignored.
These errors are expected and can be ignored.
Unfortunately, we cannot set the PID gains (to silence the error) due to the following behavior of Gazebo:
PositionJointInterface
, you must set the PID values for the
joints using that interface, otherwise you will run into
this bug.VelocityJointInterface
, if you omit the PID values, Gazebo
just perfectly follows the commanded velocities. If you specify PID values,
Gazebo will use a PID controller to approximate following the commanded
velocities, so you have to tune the PID controllers.Since we just want Gazebo to follow our commanded velocities, we cannot set the PID values for joints using the VelocityJointInterface, so the errors get printed (but can be ignored).
This repo has a pre-commit check that runs in CI. You can use this locally and set it up to run automatically before you commit something. To install, use pip:
pip3 install --user pre-commit
To run over all the files in the repo manually:
pre-commit run -a
To run pre-commit automatically before committing in the local repo, install the git hooks:
pre-commit install
Noetic |
---|
Noetic source deb | Noetic binary deb | |
---|---|---|
mir_actions | ||
mir_description | ||
mir_driver | ||
mir_dwb_critics | ||
mir_gazebo | ||
mir_msgs | ||
mir_navigation | ||
mir_robot | ||
sdc21x0 |
Noetic devel | Noetic doc | |
---|---|---|
mir_robot |