# How Workshops Work This page explains how the Robotics AI Suite workshops are built, and how to add a workshop for another component. For Workshop itself, see the [Canonical Workshop documentation](https://ubuntu.com/workshop/docs/). ## Overview ```mermaid flowchart TB subgraph host["Ubuntu 24.04 host"] k["Kernel drivers: xe (GPU), intel_vpu (NPU), uvcvideo (camera)"] x["X11 / Wayland session"] subgraph lxd["LXD (Workshop project)"] direction LR w1["object-detection
Ubuntu 24.04, Jazzy"] w2["wandering-humble
Ubuntu 22.04, Humble"] w3["ros1-bridge
Ubuntu 20.04, Noetic"] end br(["workshopbr0 bridge"]) end k -- "gpu / npu / camera plugs" --> w1 x -- "desktop plug" --> w1 w1 --- br w2 --- br w3 --- br ``` Each workshop is an LXD system container managed by Workshop. Its user space follows the definition's `base`, which sets the Ubuntu release and with it the ROS 2 distribution, but it runs on the host's kernel and kernel drivers. Devices and the desktop reach the container through Workshop interfaces, called plugs. All workshops and the host share the `workshopbr0` network bridge, so ROS 2 discovery works between them. ## Workshop definitions A workshop is defined by a YAML file in a project directory. For a component, the project directory is `src/components//workshop/`: ```text src/components//workshop/ .workshop/ .yaml Ubuntu 24.04, ROS 2 Jazzy -humble.yaml Ubuntu 22.04, ROS 2 Humble proxy, robotics-ai-suite, ... Symbolic links to the shared SDKs apt-packages.txt The component's packages *_check.py, *.rviz, patches/ Helpers used by the actions README.md ``` The project directory is mounted read-write in the container at `/project`, so actions can use the helper scripts and configuration files in it. A definition names the workshop, its base, the SDKs that set it up, and its actions: ```yaml name: its-planner base: ubuntu@24.04 sdks: - name: project-proxy - name: project-robotics-ai-suite actions: plan-check: | source /opt/ros/*/setup.bash ... ``` ## SDKs An SDK is a reusable part of a workshop: a directory with an `sdk.yaml` file that declares its plugs, and optional hooks that install software. The definitions list them as `project-`, which Workshop resolves to `.workshop//`. In this repository those are symbolic links to [`src/workshops/sdks/`](https://github.com/open-edge-platform/robotics-ai-suite/tree/main/src/workshops/sdks), so every workshop shares one copy. | SDK | Plugs | What it installs | Used by | |---|---|---|---| | `proxy` | - | The host's proxy settings for apt, `/etc/environment`, curl, wget, cargo and dirmngr. Does nothing on a direct connection | All workshops, listed first | | `robotics-ai-suite` | `gpu`, `npu`, `desktop` | The Robotics AI Suite with robotics-installer, then the workshop's `apt-packages.txt` | All ROS 2 workshops | | `intel-accel` | `gpu`, `npu` | GPU and NPU user-space drivers and tools (`clinfo`, `vainfo`, `qmassa`) | accel-check | | `camera` | `camera` | Nothing; declares the camera plug only | RealSense™ Camera, Multi-camera AI Demo | | `docker` | - | Docker and Docker Compose inside the workshop | Robotics System Profiler | | `ros1-bridge` | - | ROS 1 Noetic, ROS 2 Foxy and `ros1_bridge` from packages.ros.org (Ubuntu 20.04 only) | ROS 1 Bridge | | `ros2` | `gpu`, `npu`, `desktop` | ROS 2 Lyrical from packages.ros.org and the GPU compute runtime (Ubuntu 26.04 only) | Robotics System Profiler on Lyrical | SDKs are installed in the order listed. `setup-base` hooks run as root; `setup-project` hooks run as the `workshop` user, after the plugs connect automatically. The suite installer runs in `setup-project`, so its preflight check can see the GPU. ### The robotics-ai-suite SDK The SDK picks the ROS 2 distribution and installer profile from the definition's base: | `base` | ROS 2 | Installer profile | |---|---|---| | `ubuntu@24.04` | Jazzy | `complete` | | `ubuntu@22.04` | Humble | `full` | It downloads robotics-installer, verifies its SHA-256 checksum, and runs it unattended. It then installs the packages in the workshop's `apt-packages.txt`: one package per line, with `#` comments allowed and `${ROS_DISTRO}` expanded. The list is installed on every build, so to add a package, add it to the list and run `workshop refresh `. Ubuntu 26.04 is not yet supported by robotics-installer or the Intel® AMR and OpenVINO™ apt repositories, so workshops on `ubuntu@26.04` use the `ros2` SDK instead. It skips, with a message, any entry in `apt-packages.txt` that apt doesn't know. ## Device interfaces | Plug | Interface | Gives the container | Connects | |---|---|---|---| | `gpu` | `gpu` | `/dev/dri/card*` and `/dev/dri/renderD*` | Automatically | | `npu` | `custom-device` (subsystem `accel`) | `/dev/accel/accel*` | Manually: `workshop connect /:npu :custom-device` | | `desktop` | `desktop` | The host's X11 or Wayland display, for RViz and Gazebo | Manually: `workshop connect /robotics-ai-suite:desktop` | | `camera` | `camera` | `/dev/video*` and `/dev/media*`, with hot-plug | Manually: `workshop connect /camera:camera` | Workshop resolves the GPU and the display when the plug is connected. If either changes on the host, for example a reboot that renumbers the GPU or a new X display after logging in again, reconnect the plug. See [Troubleshooting](troubleshooting.md). ## Jazzy and Humble pairs Every ROS 2 workshop has two definitions that differ only in `name` and `base`. To keep them otherwise identical: - Actions use `$ROS_DISTRO` or `/opt/ros/*/setup.bash`, never a distribution name. - `apt-packages.txt` names packages as `ros-${ROS_DISTRO}-...`. - Both definitions share the project directory, so they share `/project` and its helper scripts. See [ROS Distributions and Interoperability](ros-distros.md) for Humble results and known issues. ## Actions Actions are shell snippets in the definition, run with `workshop run [args]`. Arguments arrive as `$1`, `$2` and so on. Workshop reads actions from the definition each time they run, so editing an action needs no refresh. The actions in these workshops follow some conventions: - Actions that open a window check the X display first. If it can't be opened, they print the commands to reconnect the desktop plug. - Headless check actions, named `*-check`, print PASS or FAIL and return non-zero on failure, so they can be used in scripts. - Actions don't read `~/.bashrc`, so `ROS_DOMAIN_ID` is unset (domain 0) unless the action sets it. - Background processes started inside an action stop when the action ends. To run two sides at once, start two `workshop run` commands from the host. ## Networking All workshops sit on the `workshopbr0` LXD bridge together with the host. ROS 2 discovery reaches across it, so workshops on the same `ROS_DOMAIN_ID` see each other's topics, and the host can join them. The container's hostname is the workshop name. See [ROS 2 from the host](ros-distros.md#ros-2-from-the-host). ## What a refresh keeps `workshop refresh ` applies changes to the definition or its SDKs: - Changes to actions need no refresh. - A change to an SDK (its hooks, plugs or `sdk.yaml`) rebuilds the container. For the suite, that runs the full installer again, about 10 to 12 minutes. - A rebuild keeps manually connected plugs, but discards anything built or configured inside the container. Examples are the `~/ov_ws` overlay from the Object Detection tutorial's `build-npu-fix` action, and SSH pairing for the Robotics System Profiler. Repeat those steps after a rebuild. - `workshop restore` resets the container to its last launch or refresh, and also resets interface connections. Reconnect the NPU and the desktop afterwards. ## Add a workshop for another component 1. Create the workshop directory next to the component's source, and link the shared SDKs: ```bash mkdir -p src/components/my-component/workshop/.workshop cd src/components/my-component/workshop/.workshop ln -s ../../../../workshops/sdks/proxy proxy ln -s ../../../../workshops/sdks/robotics-ai-suite robotics-ai-suite ``` 2. List the component's packages in `src/components/my-component/workshop/apt-packages.txt`, for example `ros-${ROS_DISTRO}-my-component`. 3. Write `.workshop/my-component.yaml`: ```yaml # Copyright (C) 2026 Intel Corporation # # SPDX-License-Identifier: Apache-2.0 name: my-component base: ubuntu@24.04 sdks: - name: project-proxy - name: project-robotics-ai-suite actions: demo: | source /opt/ros/*/setup.bash ros2 launch my_component demo.launch.py ``` 4. Copy it to `.workshop/my-component-humble.yaml`, and change `name` to `my-component-humble` and `base` to `ubuntu@22.04`. 5. Launch both. Add a headless `*-check` action that prints PASS or FAIL and returns non-zero on failure. 6. Add a `README.md` to the workshop directory, and a tutorial page to this section of the documentation. 7. Give every new file a REUSE license header, or cover it in the component's `REUSE.toml`; component CI runs `make license-check`. To copy a single workshop elsewhere, use `cp -rL` so that the SDKs come along as real files instead of links.