Advanced Usage

The development environment inside the Docker container offers several useful features that you should be aware of. These advanced features will help you increase both the convenience and the quality of your work using OpenRoSDE.

🔧 Custom Bash Functions

The development environment contains several useful Bash functions, all starting with the prefix openrosde-, to make your work more convenient. Including, but not limited to:

• openrosde-download-model-data: Download from the cloud all the large binary files required at runtime (models, datasets, dictionaries, weights, etc.).
• openrosde-source-catkin-workspaces: Source the shared and platform-specific Catkin workspaces (to use after an external build or a manual catkin build call).
• openrosde-build-catkin-workspaces: Build and source the Catkin workspaces on top of the system ROS environment.
• openrosde-reset-catkin-workspaces: Remove built artifacts, then cleanly rebuild and source the Catkin workspaces on top of the system ROS environment (to use after, for example, switching branches).
• openrosde-fix-permission-issues: Fix the various permission issues that may appear when manipulating, on the Ubuntu development machine, files generated by the root user of the Docker container.
• openrosde-initialize-new-container: Execute several of the functions above to quickly get started when entering a freshly built Docker container.
• openrosde-cleanup-output-data: Delete files and data output at runtime to clean up the environment between experiment trials.
• openrosde-kill-ros-nodes: Kill all ROS nodes as well as roscore and rosmaster still running in the Docker container.
• openrosde-help: Print how to use the tabs and the panes of the tmux sessions, as the first pane of a session shows it, which the section on multiple terminals below describes.

note

These Bash functions are based on helper scripts that can be found in ${OPENROSDE_CONTAINER_ROOT_DIR}/docker/openrosde-base/scripts/ in the Docker container or in docker/openrosde-base/scripts/ in the Ubuntu development machine. You can see their definitions in ~/.bashrc inside the container.

note

The script build-catkin-workspaces.bash will build the Catkin workspaces using catkin build instead of the older but still officially default catkin_make. Please be sure to build using catkin build to avoid strange issues.

🖥️ Multiple Terminal Operation

You can simultaneously run multiple terminals in a tmux session using RUN-TMUX-SESSION.bash:

bash ./RUN-TMUX-SESSION.bash #[docker-project] #[session-layout]

The session gathers the panes that the platform, the active extensions, the setup, and the core declare in tmux/<name>.panes, one window per group, which the status bar at the bottom shows as tabs. [session-layout] selects the panes of a layout, default-gazebo by default or default-realworld for the real robot.

Every session opens the same standard windows, as tabs numbered from 1 in this order, so that every platform and every setup feels the same, and leaves out a standard window that holds no pane of the layout:

Window	What it holds	Declared by
robot	The bringup, visualization, planning, and drivers of the platform and its devices	The platform, or the setup that replaces its panes
extra	Optional processes of a setup or an extension, such as cameras, perception, or a demo	A setup or an extension
tools	The FlexBE App on ROS 1 or the FlexBE WebUI on ROS 2, the rqt suite, and rosbridge	The core
user	The example of the user overlay and a shell in the container	The core
host	A shell on the Ubuntu development machine	The core

scripts/load-extension-paths.bash names the standard windows in OPENROSDE_TMUX_STANDARD_WINDOWS. A window outside them still opens, after them, with a warning of RUN-TMUX-SESSION.bash, while the CI fails on it in every pane file that it checks, so put every pane of a platform, a setup, or an extension in robot or extra.

The first pane of the session shows the OpenRoSDE wordmark and a short help right before its prompt, and openrosde-help prints that help again in any shell of the container, as bash ./scripts/print-tmux-splash.bash --help does on the Ubuntu development machine. The status bar names OpenRoSDE, the setup, and the layout on the left, holds the tabs in the middle, and points to openrosde-help on the right, in a purple accent, or plain when NO_COLOR is set. The session sets it with options of its own, so the other sessions of tmux keep their look and their key bindings.

• Click a tab, or press Ctrl+b then its number, to show its window, and press Ctrl+b then n or p for the next or the previous one.
• Click a pane to focus it, and scroll with the wheel, since the session turns the mouse on.
• Press Ctrl+b then z to zoom the focused pane in or out, and Ctrl+b then [ to enter copy mode, which q leaves.
• Press Ctrl+b then d to detach from the session, which keeps running, and run the same command again to attach to it, from the same machine or over SSH.
• Run tmux kill-session -t openrosde-<platform>-<docker-project> on the Ubuntu development machine, such as in the tab host, to close the session and every terminal in it.

Each line of a pane file reads <layouts> <window> <launch-file> [<arg:=value> ...], where <layouts> is * or a comma-separated list, <window> is one of the standard windows, and the words shell and host open a shell in the container or on the host.

Each pane of a launch file automatically executes RUN-DOCKER-CONTAINER.bash with its ROS launch file, and waits for a key before it launches anything. You can then select execution options by pressing specific keys, as shown in the example below:

Run 'example_roslaunch_file.launch'? Press:
'r' to run as remote,       # e.g., physical robot.
'l' to run as local,        # e.g., Gazebo simulation.
'c' to enter a child shell. # e.g., Bash shell.

note

RUN-TERMINATOR-TERMINAL.bash still opens the same terminals in Terminator with the layout stored in terminator/${OPENROSDE_ROBOT_PLATFORM}.config of the platform, whose panes wait for a key the same way, until #3 removes it. The platforms on ROS 2 have no Terminator layout.

🤖 Developing on the Simulator or the Robot

You can continue with one or both of the following options depending on the presence of a physical robot within the same local network as the Ubuntu development machine.

1. Enter the Docker container from a new terminal window:

   bash ./RUN-DOCKER-CONTAINER.bash #[docker-project] #[ros-launch]

   Then connect or switch to roscore used by the Gazebo simulator or by the physical robot with the following aliases:

   local_mode
   remote_mode

2. You can also conveniently run multiple terminals simultaneously in the tmux session by running:

   bash ./RUN-TMUX-SESSION.bash #[docker-project] #[session-layout]

note

The most important rule is to avoid pushing large binary files (datasets, weights, etc.) in the repository. Instead, you need to provide a link to download all your necessary large binary files from the cloud with openrosde-download-model-data. Ideally, all these files should be centralized in an online storage.

🕐 Clock Synchronization

Some robot platforms require clock synchronization between the Ubuntu development machine and the physical robot. The RESTART-CHRONY-SERVICE.bash script restarts the Chrony NTP service on both the host and the robot (via SSH):

bash ./RESTART-CHRONY-SERVICE.bash #[docker-project]

note

Docker containers share the host clock, so resyncing the host is sufficient for containers. The robot-side commands are platform-specific.

🐳 Configuration of the Docker Container

A cascade of scripts performs the initialization of the Docker container. Although the boundaries between them can sometimes be blurry, each one has a specific function, and future implementations or revisions should keep these functions separated as much as possible. They can be found on the Ubuntu development machine at:

• docker/openrosde-base/Dockerfile: Used by BUILD-DOCKER-IMAGE.bash to create the image of the shared development environment. It mainly describes the installations of the project tools and dependencies required inside the container.
• docker/${OPENROSDE_ROBOT_PLATFORM}-devel/Dockerfile: Used by BUILD-DOCKER-IMAGE.bash to create the platform-specific image on top of the shared base. It installs platform-specific tools and dependencies.
• docker/docker-compose.yaml: Describes the interface between the Ubuntu development machine and the container. It includes external information from outside the container, such as device host names or network configuration. It is invoked when the container is (re)started, most frequently the first time that RUN-DOCKER-CONTAINER.bash is run after the container is either stopped (Ubuntu development machine reboot) or rebuilt. Two optional overlays extend it depending on the detected GPU environment: docker/docker-compose-nvidia.yaml (native Nvidia GPU via Nvidia Container Toolkit) and docker/docker-compose-wsl.yaml (WSL 2 GPU via the WSLg D3D12 Mesa driver).
• docker/openrosde-base/scripts/initialize-docker-container.bash: A startup script referenced in docker-compose.yaml and thus also invoked when (re)starting the container, most frequently the first time that RUN-DOCKER-CONTAINER.bash is run after the container is either stopped (Ubuntu development machine reboot) or rebuilt. It executes the internal commands needed at the startup of the container (for example, to maintain the container running in the background).
• docker/openrosde-base/scripts/initialize-bash-shell.bash: A shell script appended to /root/.bashrc at the end of the Dockerfile to set up the Bash shell environment inside the container (terminal colors, shell functions, symbolic links, binary paths, environment sourcing, etc.). Theoretically, its content could be written directly in the Dockerfile, but this would result in complex lines of code as helpful Bash syntaxes like here-documents are not supported by Docker. It is automatically sourced by /root/.bashrc every time the user enters the Bash shell inside the container, most likely every time RUN-DOCKER-CONTAINER.bash is run.

note

The OpenRoSDE installation path inside the Docker container defaults to /root/OpenRoSDE/ and can be changed with the OPENROSDE_CONTAINER_ROOT_DIR variable in .env.

⚙️ Environment Configuration

OpenRoSDE uses a two-file configuration system:

• .env: Contains the default configuration variables (committed to Git), which .env.custom overrides.
• .env.custom: Holds the user-specific overrides (created from a platform template in env/), and Git ignores it.

Key configuration variables:

Variable	Description	Default
OPENROSDE_ROBOT_PLATFORM	Target robot platform	turtlebot3
OPENROSDE_CONTAINER_ROOT_DIR	OpenRoSDE root path inside the container	/root/OpenRoSDE
OPENROSDE_ROBOT_SETUP	Active setup, named after its template (see Extensions)	turtlebot3
OPENROSDE_ROBOT_EXTENSIONS	Active extensions in extensions/, separated by spaces (see Extensions)	(empty)
OPENROSDE_PLATFORM_REPOSITORY_URL	Repository of a public platform, with %s for its name, which the entry scripts name when the selected platform is cloned nowhere	https://github.com/openrosde/openrosde-platform-%s.git
OPENROSDE_DOCKER_REGISTRY	Registry of the base and platform images	ghcr.io/openrosde
OPENROSDE_DOCKER_IMAGE_TAG	Tag of the base and platform images, main, dev, or a release such as v3.0.0 (auto derives main or dev from the branch)	auto
OPENROSDE_DOCKER_BUILD_FALLBACK	Images that BUILD-DOCKER-IMAGE.bash builds locally when their pull fails: true for the base and platform images, platform for the platform image alone, or false for neither	true
OPENROSDE_BUILD_JOBS	Parallel jobs of catkin build, or of colcon build on ROS 2, which caps both the packages built at once and their compiler jobs, set in .env.custom on a machine short of memory, or by the CI from JOB_CPUS when its runner sets it	(empty, every CPU)
OPENROSDE_QUIET	Leaves out the list of every OPENROSDE_* variable that the entry scripts print with true, whose passwords, tokens, and secrets always print as <redacted>	false
OPENROSDE_ROS_VERSION	Version of ROS that the platform runs, 1 or 2, which a platform on ROS 2 sets in its template (see ROS 2)	1
OPENROSDE_ROS_DISTRO	Distribution of ROS of the base image of that version, noetic or lyrical	noetic
OPENROSDE_ROS_MASTER_HOSTNAME	ROS master host name or IP, or on ROS 2 the robot that the discovery reaches as a static peer unless it is localhost	localhost
OPENROSDE_ROS_DOMAIN_ID	Domain of the nodes on ROS 2, which the robot must share	0
OPENROSDE_ROS_CLIENT_IP	Ubuntu development machine IP (optional)	(empty)
OPENROSDE_ROBOT_HOSTNAME	Robot mDNS host name for auto-discovery	turtlebot3.local