User Overlay

The user overlay is Layer 3 of the OpenRoSDE image stack:

• Layer 1, openrosde-base: shared Ubuntu 20.04, ROS Noetic, Gazebo, and FlexBE toolchain, built once and shared by all platforms, or openrosde-base-ros2 for a platform on ROS 2, as ROS 2 describes.
• Layer 2, <platform>-devel: robot-specific packages for the platform selected by OPENROSDE_ROBOT_PLATFORM, pulled from the registry.
• Layer 3, user-devel: your customization layer, always built locally on top of Layer 2, or on top of the last Docker layer of the active extensions, as Extensions describes.

openrosde-base (L1)  ->  <platform>-devel (L2)  ->  user-devel (L3, this layer)

It lets you add your own ROS packages, system dependencies, and environment variables without forking OpenRoSDE or touching any platform files, and the tab user of every tmux session runs its starter.

The user overlay is platform-agnostic: the same overlay rebuilds on top of whichever OPENROSDE_ROBOT_PLATFORM you currently have selected.

🗂️ File Map

Path	Purpose
docker/user-devel/Dockerfile	User Docker layer. Add your apt-get or pip3 dependencies here.
docker/docker-compose-user.yaml	User Docker Compose overlay. Add extra environment: and volumes: here.
ros/user_catkin_ws/	User Catkin workspace. Drop your packages under src/.
ros/user_catkin_ws/src/openrosde_user_launch/	Starter launch package with user_example_default.launch and a config/ directory (rviz/, maps/) for your assets.
ros/user_catkin_ws/src/openrosde_user_behaviors/	Starter FlexBE behaviors package with User Example Behavior.
ros2/user_colcon_ws/src/openrosde_user_launch/	Starter launch package of the platforms on ROS 2, with user_example_default.launch.xml, which a colcon workspace builds, as ROS 2 describes.
env/user.env	User overlay environment template (reference only).

🚀 Quick Start

The user overlay ships with working starter content. To verify it on the currently selected platform:

bash ./BUILD-DOCKER-IMAGE.bash local
bash ./RUN-DOCKER-CONTAINER.bash

Inside the container, build the workspaces of the core, the platform, the active extensions, and the user overlay:

openrosde-reset-catkin-workspaces

Then check that the user package is discoverable:

rospack find openrosde_user_launch
roslaunch openrosde_user_launch user_example_default.launch

To run your user-overlay launches alongside the full platform stack, open the tmux session of the platform from the Ubuntu development machine:

bash ./RUN-TMUX-SESSION.bash

Its tab user runs openrosde_user_launch:user_example_default.launch, or user_example_default.launch.xml on ROS 2, beside a shell in the container, from the panes of the core in tmux/openrosde.panes or tmux/openrosde-ros2.panes, as Advanced Usage describes. Each pane waits for a key before it launches, so the starter runs only when you ask for it.

Until #3 removes Terminator, the Terminator layout of the platform still opens with bash ./RUN-TERMINATOR-TERMINAL.bash. Number 12 (terminal25) of every platform layout is pre-wired to openrosde_user_launch:user_example_default.launch, and the spare panes, Numbers 8 to 11, are free shells where you can run any additional user-overlay command. To replace the pre-wired entry, edit the terminator/<platform>.config of the platform and update the command = line under [[[terminal25]]].

In the FlexBE App on ROS 1, which the tab tools starts, load and execute User Example Behavior to confirm the FlexBE setup.

➕ Adding Your Own ROS Package

1. Create your package under ros/user_catkin_ws/src/ (you can also git clone an existing package there).

2. Inside the container, rebuild the user workspace:

   openrosde-build-catkin-workspaces

3. Source the new package and run it:

   source "${OPENROSDE_CONTAINER_ROOT_DIR}/ros/user_catkin_ws/devel/setup.bash"
   rosrun <your_package> <your_node>

The user workspace is automatically:

• Sourced at container startup (source-catkin-workspaces.bash).
• Rebuilt by openrosde-reset-catkin-workspaces (reset-catkin-workspaces.bash).
• Added to ROS_PACKAGE_PATH (initialize-bash-shell.bash).

➕ Adding a System Dependency

1. Edit docker/user-devel/Dockerfile and add your apt-get install or pip3 install block.

2. Rebuild only the user image (the platform image is reused from cache):

   bash ./BUILD-DOCKER-IMAGE.bash local

3. Restart the container:

   bash ./RUN-DOCKER-CONTAINER.bash

➕ Adding an Environment Variable

1. Add a default in .env under the User overlay configuration section (example: OPENROSDE_USER_MY_VAR=default-value).

2. Override it in .env.custom if needed.

3. Expose it to the container by editing docker/docker-compose-user.yaml:

   services:
     openrosde:
       environment:
         - OPENROSDE_USER_MY_VAR=${OPENROSDE_USER_MY_VAR}

scripts/load-openrosde-env.bash exports every OPENROSDE_* variable, so Docker Compose interpolates it with no further step.

🆚 User Overlay vs. New Platform

	User overlay	New platform
Use case	Project-specific or personal customization	Upstream contribution adding support for a new robot
Where it lives	Your clone of OpenRoSDE, never pushed to openrosde/openrosde	A repository of its own, openrosde-platform-<platform>, listed in the core by a pull request into dev
Files touched	This page only	The step-by-step list in Contributing
CI/CD	None (built locally)	The CI of the core, and the workflow test-with-openrosde.yml of the platform repository
Image registry	Local-only (openrosde-local/<setup>/user-devel:latest, which no docker push can publish)	Published by the CI to ghcr.io/openrosde/<platform>-devel as main and dev, and as vX.Y.Z for a release

If you need anything beyond the user overlay (custom Gazebo worlds for an existing platform, additional FlexBE behaviors, etc.), keep it in the user overlay first. Promote it to a platform package or a new platform only when it stabilizes and is ready to be shared upstream.