macOS Installation Guide

Install webots_ros2

On macOS, a solution based on Docker containers allows to improve the user experience with ROS2 compared to native macOS installation, as it allows to run ROS on a Linux platform. The Docker container is responsible to run all the ROS part and connects to the host machine through TCP connection to start Webots. A shared folder allows to transfer the world and other resource files.

Build the Dockerfile

Install the Docker Desktop application on your machine following the official Docker tutorial.

Copy the following lines in a text file and save it with the name Dockerfile in an empty folder. The file is made for the Humble distribution. Other distributions are not yet supported.

FROM amd64/ros:humble-perception # use "FROM arm64v8/ros:humble-perception" on Apple Silicon devices
SHELL ["/bin/bash", "-c"]

ARG HOST_SHARED_DIRECTORY
ARG CONTAINER_SHARED_DIRECTORY

# Environment variable for shared folder information
ENV WEBOTS_SHARED_FOLDER=$HOST_SHARED_DIRECTORY:$CONTAINER_SHARED_DIRECTORY

# Create shared directory and ros2 workspace
RUN mkdir -p $CONTAINER_SHARED_DIRECTORY
RUN mkdir -p ~/ros2_ws/src

# Install ROS2 Humble desktop
RUN sudo apt update && sudo apt install curl gnupg lsb-release -y
RUN sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
RUN sudo apt update
RUN sudo apt upgrade -y
RUN sudo apt install ros-humble-desktop -y

# Clone webots_ros2 sources and configure for arm64 architecture
RUN source /opt/ros/humble/setup.bash
RUN git clone --recurse-submodules https://github.com/cyberbotics/webots_ros2.git ~/ros2_ws/src/webots_ros2

# Install ros dependencies
RUN sudo apt install python3-pip python3-rosdep python3-colcon-common-extensions -y
RUN sudo rosdep update
RUN sudo apt-get update
RUN rosdep install --from-paths ~/ros2_ws/src --ignore-src --rosdistro humble -y

# Build packages
RUN source /opt/ros/humble/setup.bash && cd ~/ros2_ws && colcon build

Start the Docker Desktop application and open a terminal to build the Dockerfile into an image. The build arguments must be used to give a path to a folder of your host machine that is going to be the shared folder, e.g. /Users/username/shared and also a path to a folder in the container, e.g. /shared. Give it an optional arbitrary tag, e.g. cyberbotics/webots_ros2_docker:latest.

cd path/to/the/Dockerfile
docker build . --file Dockerfile --tag cyberbotics/webots_ros2_docker:latest --build-arg HOST_SHARED_DIRECTORY=/Users/username/shared --build-arg CONTAINER_SHARED_DIRECTORY=/shared

Run the Docker container

In a terminal, use the following command to run the image you have just built. Give the same paths for the host and container folders to be shared as given in the previous section. Choose a name for your container, so that you can start it again later.

docker run --name container_name -it -v /Users/username/shared:/shared cyberbotics/webots_ros2_docker:latest bash

The container is now fully configured. It can be shut down from the Docker Desktop application and restarted at any time, with exactly the same configuration in the Containers tab of the application by clicking the Start button. There is no need to repeat the previous configuration steps every time you need to use the package.

Launch demos

As mentioned in the installation section, the package uses the shared folder to communicate with Webots from the container 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 (e.g. /Applications/Webots.app) and run the server using the following commands in a new terminal (not in the container):

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

Run/start the container from the Containers tab of the Docker Desktop application (if not done yet) and copy its id. In a new terminal, the container can be accessed with its id.

docker exec -it <id> bash

In the same terminal (in the container), execute the following commands to start a package

# Source ROS2
source /opt/ros/humble/setup.bash

# Source the ROS2 workspace
cd ~/ros2_ws
source install/local_setup.bash

# Start package (e.g. webots_ros2_epuck)
ros2 launch webots_ros2_epuck robot_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.

Refer to the colcon tutorial for more information on building ROS2 workspace with colcon.