Skip to content

2. Installation

Jump to bottom
Juraj Obradovic edited this page May 27, 2023 · 4 revisions

Linux installation

There are two possibilities for the installation of MARUS in Linux OS: "Normal installation" and "Docker installation". It is suggested to try setting up "Docker installation" for testing because it is quicker and easier to setup.

Normal installation

Requirements

  • Make sure you have git-lfs installed on your system sudo apt install git-lfs

  • Make sure your ssh key is added to GitHub! If not you will get "Please make sure you have the correct access rights and the repository exists" error when trying to build submodules in the later part of the installation

  • UnityHub

  • Unity Editor (you can do it through UnityHub) - version indicated on marus-core. At first UnityHub run you will get popup as shown in the following.

    • You can skip this window at this point, and install Unity Editor later. When you try to opet marus-example project UnityHub will recognize which editor version is project using and recommend installation for you.

install_editor

Image 1: UnityHub install editor window

  • Blender - install with sudo apt install blender

Setup marus-example project

The best way to install the simulator is by downloading an example Unity project.

  • Clone marus-example repository to your preferred folder.
  • After cloning, run following command in the marus-example directory to pull marus-core submodule:
    • git submodule update --init --recursive
      • If you get "Please make sure you have the correct access rights and the repository exists" error make sure your ssh key is generated and added to GitHub.
  • When properly cloned, marus-example should have non-empty marus-core repository inside Assets folder.
  • After everything is cloned successfully, import the project in UnityHub:
    • Open UnityHub.
    • Under Projects tab press Open.
    • From the browser menu, select root directory of marus-example project.
    • If you have no Unity Editor version installed, UnityHub should recommend version. Install recommended version of Unity Editor.
      • Note: In the Image 2 version is 2021.3.3f1, which was the version that was used in the marus-example at that time.

      Editor version recommendation

      Image 2: UnityHub recommendation of the Unity Editor version

    • In the next window you don't have to add any modules and can just continue to installation.
    • Click on the project and wait for Unity to open and import the project, it can take some time to import all assets.
    • Open ExampleScene.unity from Unity (Assets/Scenes/ExampleScene.unity). You should see scene as in Image 3.

    Example scene you should see in MARUS.

    Image 3: Example scene in MARUS

Setup ROS backend

  1. MARUS is compatible with ROS1 and ROS2. Recommended is ROS2 Humble (installation).
  2. Create colcon (ROS2) or catkin (ROS1) workspace (e.g. ~/ros_ws/src)
  3. Clone grpc_ros_adapter in the src folder of workspace (e.g. ~/ros_ws/src).
    1. git clone https://github.com/MARUSimulator/grpc_ros_adapter.git
    2. If using ROS1 stay on the default branch.
    3. If using ROS2, checkout to galactic branch which works well for galactic and humble.
      • git checkout galactic
  4. Install all the python dependencies. Position yourself in grpc_ros_adapter and run: pip3 install -r requirements.txt
  5. Build and source colcon/catkin workspace.
    • Position yourself in root of the workspace (e.g. cd ~/ros_ws) and run:
    • ROS2:
      • source /opt/ros/{ROS_DISTRO}/setup.bash && colcon build
      • source ~/ros_ws/install/setup.bash
    • ROS1:
      • source /opt/ros/{ROS_DISTRO}/setup.bash && catkin build
      • source ~/ros_ws/devel/setup.bash
  6. Finally run the ROS server with:
    • ROS2:
      • ros2 launch grpc_ros_adapter ros2_server_launch.py
    • ROS1:
      • roslaunch grpc_ros_adapter launch_server.launch
  7. After you press play button in the marus-example Unity project you should see "Connected to ROS Server" in Unity Console as show in the Image 4.

Connected to ROS message in Unity console

Image 4: Connected to ROS server

Docker installation (only for Nvidia GPU!)

Requirements

Building and running MARUS in docker

  • Clone marus-docker
  • In the marus-docker folder run:
    • docker build -t marus_docker . --build-arg ssh_prv_key="$(cat ~/.ssh/id_rsa)" --build-arg ssh_pub_key="$(cat ~/.ssh/id_rsa.pub)
    • This can take few minutes to build. Note: if not using default id_rsa key for github, mofify above command.
  • Finally run the MARUS docker image: docker run --rm --name marus_container -v /tmp/.X11-unix:/tmp/.X11-unix --gpus all --runtime nvidia -e DISPLAY=$DISPLAY --privileged -it marus_docker /bin/bash

Now you have docker container with marus-example and ROS backend installed on Ubuntu 20.04.

Running the simulator

  • First open UnityHub in terminal by executing:
    • unityhub
  • Now register/login to unityhub with your account
  • After you are logged in open marus-example (~/marus-example)
    • After importing, marus-example is ready to use.
  • To connect with ROS open running MARUS container in new terminal:
    • docker exec -it marus_container /bin/bash
  • Finally run the ROS server with:
    • ROS2:
      • ros2 launch grpc_ros_adapter ros2_server_launch.py
    • ROS1:
      • roslaunch grpc_ros_adapter launch_server.launch
  • At this point if you press play button in the marus-example Unity project you should see message in the Unity Console as shown in the image 4.

Windows installation

Requirements

  • Make sure your ssh key is added to GitHub!
    • If not you will get "Please make sure you have the correct access rights and the repository exists" error when trying to build submodules in the later part of the installation.
    • Note: when you install Ubuntu in WSL make sure you have ssh key setup there as well!
  • UnityHub
  • Blender
  • Unity Editor (you can do it through UnityHub) - version indicated on marus-core.
    • At first UnityHub run you will get window as shown in the Image 1. You can skip this window at this point, and install Unity Editor later.
    • When you try to open marus-example project, UnityHub will recognize which editor version is project using and recommend installation for you.
  • WSL2. You can install any Ubuntu version. For ROS2 server it is recommended to use Ubuntu 22.04.
    • wsl --install -d Ubuntu-22.04

Setup marus-example project

The best way to install the simulator is by downloading an example Unity project.

  • Clone marus-example repository to your preferred folder.
  • After cloning, run following command in the marus-example directory to pull marus-core submodule:
    • git submodule update --init --recursive
      • If you get "Please make sure you have the correct access rights and the repository exists" error make sure your ssh key is generated and added to GitHub.
  • When properly cloned, marus-example should have non-empty marus-core repository inside Assets folder.
  • After everything is cloned successfully, import the project in UnityHub:
    • Open UnityHub
    • Under Projects tab press Open.
    • From the browser menu, select root directory of marus-example project.
    • If you have no Unity Editor version installed, UnityHub should recommend version. Install recommended version of Unity Editor.
      • Note: In the Image 2 version is 2021.3.3f1, which was the version that was used in the marus-example at that time.
    • In the next window you don't have to add any modules and can just continue to installation.
  • Click on the project and wait for Unity to open and import the project, it can take some time to import all assets.
  • Open ExampleScene.unity from Unity (Assets/Scenes/ExampleScene.unity). You should see scene as in Image 3.

Setup ROS backend

For the normal installation in Windows we use WSL for running ROS server.

  1. Make sure you have WSL2 with Ubuntu installed (listed in requirements)
  2. To test if GUI works by default in WSL (Win11), test by opening any program (e.g. gedit). Follow these instructions to use GUI applications from within the WSL environment if previous test failed (Win10):
    1. Install VcXsrv Windows X Server software
    2. Create config.xlaunch with xml provided here: 
       <?xml version="1.0" encoding="UTF-8"?>
 <XLaunch WindowMode="MultiWindow" ClientMode="NoClient"
 LocalClient="False" Display="-1" LocalProgram="xcalc"
 RemoteProgram="xterm" RemotePassword="" PrivateKey=""
 RemoteHost="" RemoteUser="" XDMCPHost="" XDMCPBroadcast="False"
 XDMCPIndirect="False" Clipboard="True" ClipboardPrimary="True"
 ExtraParams="-nowgl" Wgl="True" DisableAC="True" XDMCPTerminate="False"
 />
    3. Double click on config.xlaunch to run the X Server
    4. In WSL2 export DESKTOP environmental variable:
      • export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0.0
    5. At this point you should be able to run GUI applications from WSL linux distribution.
  3. Install desktop version of ROS in WSL. MARUS is compatible with ROS1 and ROS2. Recommended is ROS2 Humble (installation).
  4. Create colcon (ROS2) or catkin (ROS1) workspace (e.g. ~/ros_ws/src)
  5. Clone grpc_ros_adapter in the src folder of workspace (e.g. ~/ros_ws/src).
    1. git clone https://github.com/MARUSimulator/grpc_ros_adapter.git
    2. If using ROS1 stay on the default branch.
    3. If using ROS2, checkout to galactic branch which works well for galactic and humble.
      • git checkout galactic
  6. Install all the python dependencies. Position yourself in grpc_ros_adapter and run: pip3 install -r requirements.txt
  7. Build and source colcon/catkin workspace.
    • Position yourself in root of the workspace (e.g. cd ~/ros_ws) and run:
    • ROS2:
      • source /opt/ros/{ROS_DISTRO}/setup.bash && colcon build
      • source ~/ros_ws/install/setup.bash
    • ROS1:
      • source /opt/ros/{ROS_DISTRO}/setup.bash && catkin build
      • source ~/ros_ws/devel/setup.bash
  8. Finally run the ROS server with:
    • ROS2:
      • ros2 launch grpc_ros_adapter ros2_server_launch.py
    • ROS1:
      • roslaunch grpc_ros_adapter launch_server.launch
  9. After you press play button in the marus-example Unity project you should see "Connected to ROS Server" in Unity Console as show in the next Image 4.
Clone this wiki locally