POSIM v1.0.1Platform for Ocean Simulation · Documentation
Documentation menu
POSIM / Beginner guides

Prepare your terminals

A terminal is a window where you type commands and read their output. The guides call two ordinary terminal windows Terminal A and Terminal B: A runs the simulation, while B reads sensor data or sends commands. They are labels for their roles, not different programs.

Choose where to open the terminals

Installation route Terminal A and Terminal B
Ubuntu native Open the Ubuntu Terminal application twice
Linux Docker Open two Linux terminals; enter the same running container from each with the command below
Windows WSL native Open two Ubuntu tabs in Windows Terminal, using the same WSL distribution
Windows WSL + Docker Open two Ubuntu WSL tabs; enter the same Docker container from both
macOS Docker + RDP Connect to the Linux desktop with RDP, then open two terminal windows inside that desktop

For the Linux and Windows Docker guides, the container is named posim. Run this in each host terminal to enter it:

docker exec -it posim bash

In the macOS RDP desktop, you are already inside the container. Run ROS commands in the desktop's Linux terminals. PowerShell and macOS Terminal are used for host commands such as starting Docker containers.

Understand the workspace

The ROS workspace is the directory that holds source code and built packages. Its src/ directory contains source packages; build/ holds intermediate build files; install/ contains the packages ROS loads.

Installation Workspace path
Ubuntu or WSL native ~/posim_ws
AMD64 Docker image /opt/posim_ws
ARM64 RDP image /home/docker/posim_ws

In paths, ~ means the current Linux user's home directory. POSIM_WS below is a variable holding your workspace path, so later commands work in each installation environment.

Load the environment in both terminals

For Ubuntu or WSL native, run in A and B:

export POSIM_WS="$HOME/posim_ws"
source /opt/ros/lyrical/setup.bash
source "$HOME/.ros_ardusub_env/env"
source "$POSIM_WS/install/setup.bash"
cd "$POSIM_WS"

For Docker, including the Linux desktop reached through RDP, run in A and B:

export POSIM_WS="${POSIM_WS:-${POSIM_UNDERLAY:-/home/docker/posim_ws}}"
source /opt/ros/lyrical/setup.bash
source "$POSIM_WS/install/setup.bash"
cd "$POSIM_WS"

source loads the paths and settings that let this terminal find ROS and POSIM. Repeat this setup in each new terminal. The Docker images supply the workspace variable and their ArduSub paths.

Check before starting

ros2 pkg prefix posim_demos
ros2 pkg prefix ros_gz_sim

Both paths should belong to the workspace's install/ directory. If a package is missing, return to your installation guide. A ros_gz_sim path under /opt/ros/lyrical means the workspace overlay has not been selected.

Continue with First simulation. A command that keeps printing output is still running; use Ctrl+C in that terminal to stop it and wait for the prompt before entering another command.