Getting Started with Workshops#
This guide takes you from an Ubuntu 24.04 host to a running workshop with the Robotics AI Suite, with the Intel® GPU and Intel® NPU passed through. It takes about 30 minutes, most of it is the first suite installation.
You will:
Install LXD and the Workshop CLI.
Check that the GPU and NPU work in a container with the
accel-checkworkshop.Launch the
object-detectionworkshop and run inference on the CPU, GPU and NPU.
Prerequisites#
An Ubuntu 24.04 host with an Intel® GPU and/or Intel® NPU. The
xe(ori915) andintel_vpukernel drivers must be loaded. Check that the device nodes exist:ls /dev/dri /dev/accel
You should see
card*andrenderD*in/dev/dri, andaccel0in/dev/accel.A local desktop session (X11 or Wayland) for the steps that open RViz or Gazebo. Headless steps don’t need one.
About 5 GiB of disk space per workshop with the full suite, more while it installs.
Install LXD and Workshop#
If the host is behind an HTTP proxy, give snapd the proxy first:
sudo snap set system proxy.http="$http_proxy" proxy.https="$https_proxy"
Install and initialize LXD, then install Workshop:
sudo snap install lxd --channel=6/stable sudo lxd init --auto sudo snap install workshop --classic
Add your user to the
lxdgroup, then log out and back in:sudo usermod -aG lxd $USER
Make room in Workshop’s storage pool. Workshop keeps its containers in its own LXD storage pool,
workshop, separate from thedefaultpool thatlxd initcreates. Its default size (28.6 GiB on our test host) fills up with two or three suite workshops installing at once, and launches then fail withno space left on device. Once the pool exists (check withlxc storage list), grow it:lxc storage set workshop size=150GiB
Get the workshop definitions#
Clone the Robotics AI Suite repository. No submodules are needed.
git clone https://github.com/open-edge-platform/robotics-ai-suite.git
cd robotics-ai-suite
Each component’s workshop is in src/components/<component>/workshop/. Run workshop commands from that directory; anywhere else they fail with not a project.
Configure the proxy#
Skip this step on a direct internet connection.
Behind an HTTP proxy, pass the host’s http_proxy, https_proxy and no_proxy to the workshops before the first launch:
src/workshops/scripts/configure-proxy.sh
The script writes src/workshops/sdks/proxy/hooks/proxy.env, which every workshop reads while it is built to configure apt, /etc/environment, curl, wget, cargo and dirmngr. The file is not tracked by git. To write it by hand, copy proxy.env.example from the same directory and edit it.
If the host’s proxy changes later, run the script again, then rebuild each workshop with workshop refresh <name>.
Check the GPU and NPU#
The accel-check workshop installs only the GPU and NPU user-space drivers, without ROS, so it builds in a few minutes. Use it to confirm that devices reach a container on a new host.
Launch the workshop:
cd src/workshops/accel-check workshop launch accel-check
Connect the NPU. The GPU connects automatically; the NPU never does:
workshop connect accel-check/intel-accel:npu :custom-device
List the devices through Level Zero:
workshop run accel-check check-level-zero
The output lists both the GPU and the NPU.
Other checks in this workshop:
Action |
What it checks |
|---|---|
|
|
|
Opens each device node and reads its kernel driver |
|
Lists the GPU and NPU through Level Zero |
|
|
|
GPU statistics for the |
Launch a Robotics AI Suite workshop#
The object-detection workshop installs the full suite with the official robotics-installer, so the first launch takes 10 to 30 minutes.
Launch the workshop and connect the NPU:
cd ../../components/object-detection/workshop workshop launch object-detection workshop connect object-detection/robotics-ai-suite:npu :custom-device
Measure inference latency on each device:
workshop run object-detection benchmark
Connect the desktop and open the tutorial in RViz:
workshop connect object-detection/robotics-ai-suite:desktop workshop run object-detection ros-object-detection-gpu
Press Ctrl+C in the terminal to stop it.
Continue with the Object Detection tutorial, which also covers the NPU.
Everyday commands#
Command |
What it does |
|---|---|
|
Creates a workshop from its definition. Use it only for a new workshop |
|
Starts or stops an existing workshop |
|
Applies changes to the definition or its SDKs. Rebuilds the container if an SDK changed; see What a refresh keeps |
|
Lists the workshop’s actions |
|
Runs an action |
|
Opens an interactive shell in the workshop |
|
Runs one command in the workshop |
|
Shows which interfaces are connected |
|
Connects an interface, such as the NPU or the desktop |
|
Deletes the workshop |
|
Shows Workshop’s warnings; |
Note
Stop an action with Ctrl+C in its terminal. Closing the terminal or killing only the host-side workshop run leaves the processes running in the container; see Troubleshooting.
Use Humble instead of Jazzy#
Every ROS 2 workshop also has a Humble variant on Ubuntu 22.04. Use <name>-humble in place of <name> in every command, for example workshop launch object-detection-humble. Jazzy and Humble workshops can run at the same time. See ROS Distributions and Interoperability.
Next steps#
Pick a tutorial from the list of workshops.
Learn how the definitions are put together in How Workshops Work.
If something doesn’t work, see Troubleshooting.