macOS Installation Guide

Install webots_ros2

On macOS, a solution based on UTM virtual machines allows to improve the user experience with ROS 2 compared to native macOS installation, as it allows to run ROS in a Linux environment. The Virtual Machine (VM) is responsible to run all the ROS part (including RViz) and connects to the host machine through TCP connection to start Webots and benefit from native hardware acceleration. A shared folder allows to transfer the world and other resource files.

The following steps explain how to create the VM image with the installation of the webots_ros2 released package. It is also possible to install from sources. In Pre-configured Images section, you can find already configured images for every release of Webots (starting from R2023a) to download.

Create the VM image

Install UTM on your macOS machine. The link can be found on the official UTM website.

Download the .iso image of Ubuntu 22.04 for Humble and Rolling or Ubuntu 20.04 for Foxy. Be sure to download the image corresponding to your CPU architecture.

In the UTM software:

• Create a new image and choose Virtualize option.
• Select the ISO image you have downloaded in the Boot ISO Image field.
• Leave all hardware settings at default (including hardware acceleration disabled).
• In the Shared Directory window, select a folder that will be used by webots_ros2 to transfer all the Webots assets to the host. In this example, the selected folder is /Users/username/shared.
• Leave all the remaining parameters as default.
• Start the VM. Note that you can select another shared folder each time you start the VM.
• During the first launch of the VM, install Ubuntu and choose a username for your account. In this example, the username is ubuntu.
• Once Ubuntu is installed, close the VM, remove the iso image from the CD/DVD field and restart the VM.

Configure the VM

In this section, ROS 2 is installed in the VM and the shared folder is configured. The following instruction and command are all run inside the VM.

• Open a terminal in the started VM and install the ROS 2 distribution you need by following the instructions on the official ROS website:

  • Humble.
  • Rolling.
  • Foxy.

• Create a folder in the VM to use as shared folder. In this example, the shared folder in the VM is /home/ubuntu/shared.

  mkdir /home/ubuntu/shared

• To mount this folder to the host, execute the following command. Don't forget to modify the path to the shared folder, if it is different in your case.

  sudo mount -t 9p -o trans=virtio share /home/ubuntu/shared -oversion=9p2000.L

• To automatically mount this folder to the host when starting the VM, add the following line to /etc/fstab. Don't forget to modify the path to the shared folder, if it is different in your case.

  share	/home/ubuntu/shared	9p	trans=virtio,version=9p2000.L,rw,_netdev,nofail	0	0

• The environment variable WEBOTS_SHARED_FOLDER must always be set in order for the package to work properly in the VM. This variable specifies the location of the shared folder that is used to exchange data between the host machine and the virtual machine (VM) to the webots_ros2 package. The value to use for this variable should be in the format of <host shared folder>:<VM shared folder>, where <host shared folder> is the path to the shared folder on the host machine and <VM shared folder> is the path to the same shared folder on the VM.

  In this example:

  export WEBOTS_SHARED_FOLDER=/Users/username/shared:/home/ubuntu/shared

  You can add this command line to the ~/.bashrc file to automatically set this environment variable when starting a new terminal.

Install the package from sources

For now the package can only be installed from sources.

# Install git
sudo apt-get install git

# Create a ROS2 workspace
mkdir -p ~/ros2_ws/src

# Source ROS2 environment
source /opt/ros/$ROS_DISTRO/setup.bash

# Retrieve the sources
cd ~/ros2_ws
git clone --recurse-submodules https://github.com/cyberbotics/webots_ros2.git src/webots_ros2

# Install dependencies
sudo apt install python3-pip python3-rosdep python3-colcon-common-extensions
sudo rosdep init && rosdep update
rosdep install --from-paths src --ignore-src --rosdistro $ROS_DISTRO

# Building packages
colcon build

# Source this workspace
source install/local_setup.bash

Pre-configured Images

If you don't want to setup the VM from scratch, the following links provide you with pre-configured UTM images for each version of Webots. The webots_ros2 version is installed from the official repository (not from sources) and is typically the first one that is compatible with the corresponding Webots version. You are welcome to download an image and upgrade the package, or install it from sources if necessary.

• Version 2023.0.2 for Webots R2023a

When adding the image in the UTM software, you should also choose the path to the host shared folder before starting the VM (e.g. /Users/username/shared). The WEBOTS_SHARED_FOLDER environment variable must always be set for the package to work properly in the virtual machine (VM). This variable specifies the location of the shared folder that is used to exchange data between the host machine and the VM for the webots_ros2 package. The value for this variable should be in the format of <host shared folder>:<VM shared folder>, where <host shared folder> is the path to the shared folder on the host machine and <VM shared folder> is the path to the same shared folder on the VM.

In the pre-configured images, WEBOTS_SHARED_FOLDER is already set in ~/.bashrc. You will need to update it to use the correct path for the host folder.

In the ~/.bashrc file:

export WEBOTS_SHARED_FOLDER=/path/to/host/shared/folder:/home/ubuntu/shared

Launch demos

As mentioned in the installation section, the package uses the shared folder to communicate with Webots from the VM to the host. For the package to start Webots on the host, a local simulation server must be started.

The server can be downloaded here: local_simulation_server.py. Specify the Webots installation folder in WEBOTS_HOME environment variable (e.g. /Applications/Webots.app) and run the server using the following commands in a new terminal on the host (not in the VM):

export WEBOTS_HOME=/Applications/Webots.app
python3 local_simulation_server.py

In the VM, open a terminal and execute the following commands to start a package:

# Source ROS 2
source /opt/ros/humble/setup.bash

# If installed from sources, source the ROS2 workspace
cd ~/ros2_ws
source install/local_setup.bash

# If not already set in ~/.bashrc, set WEBOTS_SHARED_FOLDER (see previous sections for details)
export WEBOTS_SHARED_FOLDER=/path/to/host/shared/folder:/path/to/VM/shared/folder

# Start package (e.g. webots_ros2_universal_robot)
ros2 launch webots_ros2_universal_robot multirobot_launch.py

If Webots is closed or the ROS 2 process is interrupted, the local server will automatically wait for a new package launch and the shared folder will be cleaned for the next run.