Getting Started

[[TOC]]

Overview

Currently, LOTUSim supports these platforms

OS	ROS2	Gazebo
Ubuntu 22.04	humble	harmonic
Ubuntu 24.04	jazzy	harmonic
Windows 11 (not actively supported)	jazzy	harmonic

Core systems

LOTUSim is a modular system consisting of the following modular systems.

This flexibility ensures that users can tailor the simulator to their specific research or operational needs.

See the documentation Developer Guide for more details.

Multi-Agent System

• Manages all assets in the world.
• Highly customizable — users can define behaviors via scripts.

Physics System

• Supports external physics engines.
• Default physics engine is xdyn
• Default protocols are provided, and users can integrate their own using the Developer Guide.

Rendering System

• Compatible with external renderers.
• Default rendering engine is Unity
• The rendering pipeline is detailed in the Developer Guide.

User Interface

• Comes with a backend command system.
• Users can develop custom frontends or use the default one.

🚧 Sensor System (2026)

• A fully open sensor interface is under development.

🚧 Control and Navigation system (2026)

🚧 Vessel Interaction System (TBD)

• A fully open interaction system between models is planned.

Default Models

The simulation comes with a few models simple models for academic and research purposes..

For more information about models in the simulation, please check out this page

LRAUV

DTMB

BlueROV 2

Installation

Using docker

docker pull ghcr.io/naval-group/lotusim:latest
docker run -it ghcr.io/naval-group/lotusim:latest

Installing LOTUSim from source

For Windows users, load Ubuntu in Windows

The best method to run LOTUSim on Windows is to run it in WSL2 (Windows Subsystem for Linux).

If you face network issues along the way, do take note of window's firewall rules.

1) Download WSL

1. Open powershell as adminstrator
2. Run the following command to install ubuntu 22.04

wsl --install -d Ubuntu-22.04

2) Run the following command

WSL uses virtualized NAT VM network instead of host's network stack directly.

To use the host's network stack for ROS2 discovery to work out-of-box, run the following commands

notepad $env:USERPROFILE\.wslconfig

Add the following into the file

ini[wsl2] 
networkingMode=mirrored

3) Run WSL with admin rights

In Ubuntu environment

1. Create Workspace

cd
mkdir -p lotusim_ws/src
cd lotusim_ws/src

# The core lotusim
git clone https://github.com/naval-group/LOTUSim.git

• If you want to use the UI:

# The frontend and backend for lotusim
git clone https://github.com/naval-group/LOTUSim-UI-backend.git
git clone https://github.com/naval-group/LOTUSim-UI-frontend.git

• If you want to use the repository to launch generic scenario for lotusim (ROS2): see the documentation Generic Scenario to install it.

2. Adding Environment Variables

It is recommended that you follow the default directory but feel free to change the directory if required.

cat <<EOF >> ~/.bashrc
export LOTUSIM_WS=$HOME/lotusim_ws
export LOTUSIM_PATH=$LOTUSIM_WS/src/LOTUSim
export LD_LIBRARY_PATH=$LOTUSIM_PATH/physics
export LOTUSIM_MODELS_PATH=$LOTUSIM_PATH/assets/models/
export PATH=$LOTUSIM_PATH/physics/:$LOTUSIM_PATH/launch:$PATH
source $LOTUSIM_PATH/launch/bash_completion.sh
EOF

chmod -R +x "$HOME/lotusim_ws/src/lotusim/launch"/*
source ~/.bashrc

3. Install LOTUSim and dependencies

lotusim install

---

Install Unity

(TO be changed to git clone the public repo)

1. Download the Unity Hub and follow the onscreen installation guide.
2. Register a UDN account. Sign in, choose your license type, and install the Unity Editor.
3. Use Unity version 2022.3.18f1 (used for HDRP water system).
4. Clone the Unity project:

git clone --recurse-submodules https://github.com/naval-group/LOTUSim-Unity-modules.git

5. Add and open the project in Unity Hub.
6. Open one of the scenes.

Quick-start

LOTUSim web UI

The web UI is made aid user to pass commands to LOTUSim and have a system overview.

lotusim ui

Unity

To visualise, use Unity.

Running LOTUSim

lotusim run

Running physics engine

This example will run xdyn, the default physics engine of LOTUSim

Run xdyn for lrauv underwater

xdyn-for-cs $HOME/lotusim_ws/src/lotusim/assets/models/lrauv/lrauv.yml --verbose --address 127.0.0.1 --dt 0.2 --port 12346

Spawning vessel in the simulation

Using web UI

1. Go to the webpage using any prefered browser here
2. At the home page, right click where you want the vessel to be and click on add vessel
3. Select the box and parameters of the vessel you want to spawn.

Using ROS2 action client

Please check the examples folder

Using ROS2 CLI

TODO: change the vessel spawned

source $HOME/lotusim_ws/install/setup.bash

ros2 action send_goal /mas_cmd_array lotusim_msgs/action/MASCmdArray "{
  cmd: [
    {
      cmd_type: 0,
      vessel_position: {
        position: {
          x: 10,
          y: 10,
          z: 10
        },
        orientation: {
          x: 0,
          y: 0,
          z: 0,
          w: 1
        }
      },
      vessel_name: 'lrauv',
      model_name: 'lrauv',
      sdf_string: '<lotus_param>
  <render_interface>
    <publish_render>true</publish_render>
    <renderer_type_name>lrauv</renderer_type_name>
  </render_interface>
  <physics_engine_interface>
    <aerial>
      <ConnectionType>ROS2</ConnectionType>
      <namespace>aerialWorld</namespace>
    </aerial>
    <underwater>
      <ConnectionType>XDynWebSocket</ConnectionType>
      <uri>ws://127.0.0.1:12346</uri>
      <thrusters>
        <thursters1>propeller</thursters1>
      </thrusters>
    </underwater>
    <init_state>underwater</init_state>
  </physics_engine_interface>
</lotus_param>'
    }]
}"

Deleting vessels

Currently, only terminal command is available.

ros2 action send_goal /lotusim/mas_cmd_array lotusim_msgs/action/MASCmdArray "{cmd: [
{
cmd_type: 1,
entity: 4,
vessel_name: dtmb
}]}"

Adding models into LOTUSim ecosystem

GUI (recommended method)

Go into the model page and click on the + button

Manual method

The manual method is troublesome and require knowledge in the different system so it is not recommended.

1. Create the model.sdf file in the assets/models folder in sdf format.
2. Create the physics model in the external physics engine if you want a physics calculation.
3. Create the model in Unity.

FAQ

What are the advantages of moving from only Gazebo to LOTUSim?

LOTUSim is a simulation integration project designed to allow users to quickly start maritime simulations.

While built using a Gazebo backbone, LOTUSim doesn't rely solely on it. It's fundamentally different in purpose and design.

It extends Gazebo with:

1. Multi-agent System
   Built-in MAS makes interaction management between models/agents easier.

2. External Physics System
   Connect to external physics engines and distribute processing across machines.

3. External Rendering
   Gazebo GUI is limited—LOTUSim enables better rendering via Unity or other engines.

4. Additional Sensors
   Marine-specific custom sensors are in development.

Should I Use Unity?

That’s up to you. The simulation interface is open—you can integrate your own rendering system.

Recommendation: Use the provided renderer for the best experience.