# Ros2 > Core ROS 2 usage: workspaces, colcon builds, packages (ament_python/ament_cmake), nodes, topics/services/actions, QoS, launch files, parameters, TF2, rosdep, and gluing third-party packages together. Use when: any ROS 2 development or debugging; 'ros2', 'colcon', 'launch file', 'package.xml', 'QoS mismatch', 'TF', 'node not receiving messages', 'rosdep'. Foundation skill for the ROS vertical — load alongside nav2, gazebo, rviz2. ROS 2 only; ROS 1 is EOL and out of scope. Not for: navigation specifics (nav2), simulation (gazebo), or visualization (rviz2/foxglove). - Skill: `robium-ai/ros2-11` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add robium-ai/ros2-11` - Raw SKILL.md: https://api.skillmd.com/api/skills/robium-ai/ros2-11/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: robium-ai (https://skillmd.com/u/robium-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/robium-ai/ros2-11 --- # ros2 The foundation tool skill for the robium ROS vertical. Everything that touches ROS 2 itself — workspaces, colcon, package anatomy, nodes, topics/services/ actions, QoS, launch files, parameters, TF2, rosdep, and gluing third-party ROS packages together — lives here. `nav2`, `gazebo`, and `rviz2` all assume this skill's content and cross-reference it rather than re-explaining ROS 2 basics; load this skill alongside any of them. This skill is ROS 2 only — ROS 1 reached end-of-life with Noetic Ninjemys and is out of scope everywhere in robium. ## When to use this skill - Any ROS 2 development or debugging task: creating a package, building a workspace, writing nodes, wiring topics/services/actions, writing launch files, setting parameters, working with TF2, resolving dependencies. - The trigger phrases in the description: 'ros2', 'colcon', 'launch file', 'package.xml', 'QoS mismatch', 'TF', 'node not receiving messages', 'rosdep'. - A ROS 2 node isn't receiving messages it should be — start here (QoS is the first suspect), not in application logic. - Cross-references — go to the sibling skill instead when the question is: - Autonomous navigation specifics (costmaps, planners, controllers, behavior trees, AMCL/localization) → `nav2`. This skill covers the ROS 2 substrate Nav2 runs on, not navigation algorithms. - Simulating a ROS 2 robot → `gazebo`. - Visualizing ROS 2 data → `rviz2` (local display) or `foxglove` (remote/ headless). - Choosing uv vs Docker, or macOS/GPU environment setup → `environments`. - Module boundaries, non-ROS transports at a system boundary, Dockerfiles/ compose for a multi-module app → `integration`. This skill's "bridge two third-party packages" pattern below is intra-system (still ROS 2 topics); crossing to a non-ROS peer is `integration`'s call. - The whole-stack decision this feeds into → `architect` (routes here). ## Key directives - **Delegation posture: embed.** No good upstream "how do I use ROS 2" skill exists to point to — this content lives here, in depth, not as a thin pointer to docs.ros.org. Link out only for exact version/tag facts that change release-to-release. - **Always `rosdep install` before building.** A workspace that hasn't had `rosdep install --from-paths src -y --ignore-src` run against it is not ready to build — missing system/package dependencies produce confusing colcon failures that look like source bugs. Run rosdep first, every time a new package or a fresh clone enters the workspace, not just on first setup. See `references/workspace-and-packages.md`. - **QoS compatibility is the first suspect for silent topic failures.** A node that runs cleanly, discovers its peer, and still exchanges zero messages is almost always a QoS mismatch (e.g. one side `RELIABLE`, the other `BEST_EFFORT`), not a code bug — DDS drops the connection silently with no error on either side. Check `ros2 topic info -v` before debugging anything else. See `references/interfaces-and-qos.md` and `references/debugging.md`. - **Prefer workspace overlays over editing third-party package source.** When a third-party ROS package needs different behavior, put your changes in an overlay package (a new package, or a `COLCON_IGNORE`d fork built on top) rather than hand-editing files inside an installed or vendored package. Overlays survive `rosdep update`/reinstalls and keep the diff visible; in-place edits to third-party source silently rot. See `references/workspace-and-packages.md`. - **Never write distro, tag, or API-surface facts from memory.** ROS 2's distro cadence, package availability, and even some API idioms (e.g. the `rclpy.init()` context-manager form) change release to release. Verify before repeating a claim in a real project — every example in this skill is marked `status: unverified` for exactly this reason. ## Quick start **1. Confirm the workspace exists and rosdep is current:** ```bash mkdir -p ~/ros2_ws/src && cd ~/ros2_ws source /opt/ros/lyrical/setup.bash rosdep update rosdep install --from-paths src -y --ignore-src ``` **2. Build and source the overlay:** ```bash colcon build --symlink-install source install/setup.bash ``` **3. Run something.** The `examples/package-ament-python/` directory in this skill is a minimal, internally-consistent ament_python package (one parameterized publisher node, one launch file) — copy it into `src/`, rebuild, and run with `ros2 run ros2_example_pkg talker` or `ros2 launch ros2_example_pkg talker.launch.py`. For any step beyond this, see the matching usage pattern below and the references it points to. ## Usage patterns **Create a package → build → run.** `ros2 pkg create --build-type ament_python --license Apache-2.0 --node-name ` scaffolds `package.xml`, `setup.py`, `setup.cfg`, the resource marker, and a starter node. Fill in `package.xml`'s ``/``, add real dependencies, `colcon build --symlink-install` from the workspace root, `source install/setup.bash`, then `ros2 run `. See `references/workspace-and-packages.md` and `examples/package-ament-python/`. **Add a dependency.** Declare it in `package.xml` as `` (runtime) or `` (build-time C++), then re-run `rosdep install --from-paths src -y --ignore-src` before rebuilding — adding the tag alone does not install the underlying apt/pip package. See `references/workspace-and-packages.md`. **Write a launch file.** Python launch files are the default choice (XML/YAML exist but are thinner and less composable): `generate_launch_description()` returning a `LaunchDescription` of `Node` actions, with `DeclareLaunchArgument`/`LaunchConfiguration` for anything that should be overridable from the command line, and the launch directory registered in `setup.py`'s `data_files` plus `launch` / `launch_ros` in `package.xml`. See `references/launch-patterns.md` and `examples/package-ament-python/launch/talker.launch.py`. **Bridge two third-party packages (remap + relay).** When two existing packages almost line up but use different topic names or message shapes, prefer wiring them at the launch/CLI layer over patching either package's source: `remappings=[('from_topic', 'to_topic')]` on a `Node` action (or `` in XML) for a straight rename, and `ros2 run topic_tools relay ` (or `relay_field` for a field-level republish) when the fix needs to live as its own running node rather than a launch-time rename. This stays inside one ROS 2 system — crossing to a non-ROS peer is `integration`'s call, not this pattern. See `references/launch-patterns.md`. **Parameterize a node.** Call `self.declare_parameter('name', default)` in the node's `__init__`, read it with `self.get_parameter('name').value` (or the typed `.get_parameter_value()` accessors), and feed it from a launch file's `parameters=[{...}]` list, a YAML params file, or `--ros-args -p name:=value` on the CLI — don't hardcode values a launch file should own. See `references/interfaces-and-qos.md` and `examples/package-ament-python/ros2_example_pkg/talker_node.py`. **Test a launched process with launch_testing.** `launch_testing` tests a process (a plain `ExecuteProcess` or a `launch_ros.actions.Node`) through its real launch file rather than mocking it: `generate_test_description()` is decorated `@pytest.mark.launch_test` (what makes pytest collect the file) then `@launch_testing.markers.keep_alive` (keeps the launched process alive through the active-test phase instead of exiting immediately), and returns a `LaunchDescription` ending in `launch_testing.actions.ReadyToTest()`; an undecorated `unittest.TestCase` runs while the process is alive, asserting via `proc_output.assertWaitFor(...)` (or `get_node_names()` for a launched node); a second `unittest.TestCase` decorated `@launch_testing.post_shutdown_test()` asserts the exit code with `launch_testing.asserts.assertExitCodes(proc_info)`. This is the scaffold the `testing` skill's `ros2-pytest-vs-launch-testing-split` anchor routes to. Confirmed 2026-08-02 against the `rolling`-branch `ros2/examples` repo; re-verify the decorator/assertion API surface against this skill's default distro (Lyrical Luth) before copying verbatim. **Control callback concurrency with executors + callback groups.** Concurrency under a `MultiThreadedExecutor` is scoped per callback group, not per executor: passing a `MutuallyExclusiveCallbackGroup()` instance as `callback_group=` to `create_timer`/`create_subscription`/ etc. serializes only that group's own callbacks — other callbacks on the same node (or in a different group) can still run concurrently. Without an explicit group, a node's callbacks share one implicit `MutuallyExclusiveCallbackGroup` by default, so a bare `MultiThreadedExecutor(num_threads=N)` alone does not parallelize a single node's own callbacks. Use `ReentrantCallbackGroup` instead when a callback should run concurrently with itself rather than being serialized. Confirmed 2026-08-02 against the `rolling`-branch `ros2/examples` repo; re-verify the callback-group API surface against this skill's default distro before relying on exact signatures. ## Platform gotchas - **macOS has no native ROS 2 — Docker only.** There is no supported native ROS 2 install on macOS/Apple Silicon; every ROS 2 workflow on a Mac dev machine runs inside Docker, even for local iteration. Don't try to `pip install`/homebrew a native ROS 2 as a shortcut. See the `environments` skill's Docker patterns and its ROS 2 base-image guidance. - **`ROS_DOMAIN_ID` collisions are silent.** All ROS 2 nodes default to domain ID `0`; two unrelated ROS 2 systems on the same network segment with the same domain ID will discover and cross-talk with each other with no error. Export a project-unique `ROS_DOMAIN_ID` (`export ROS_DOMAIN_ID=`) in every shell/container that runs this project's nodes, the same way you'd pick a non-default port. - **Shell sourcing order matters.** Source the underlay (`/opt/ros// setup.bash`) before the workspace overlay (`install/setup.bash`) — each `setup.bash` only extends the environment the previous one built, so sourcing the overlay alone (or in the wrong order) silently drops the underlay's paths. A fresh shell that skips sourcing entirely is the most common "package not found" / "command not found: ros2" report — check this before anything else. - **`set -u` before sourcing a ROS setup script kills the script.** ROS's own `setup.bash` reads unset variables, so a strict-mode wrapper (`set -euo pipefail` at the top, then `source /opt/ros// setup.bash`) aborts with an unbound-variable error from inside ROS's script — an alarming failure that has nothing to do with your code. Order it the other way: source first, *then* `set -u`. Verified 2026-07-11 (nav-trial). - **`ros2 launch` as container PID 1 ignores SIGTERM.** The kernel drops unhandled signals to PID 1, and launch installs no SIGTERM handler — so the normal teardown path (`docker stop`, or an in-container `os.kill(1, SIGTERM)`) is a silent no-op and the container sits there until the 10 s timeout escalates to SIGKILL, taking the sim down hard. **SIGINT** hits launch's real shutdown path (clean exit 0, nodes shut down in order — verified in-container 2026-07-12, nav-trial demo). Either send SIGINT, or don't run launch as PID 1: an init shim (`docker run --init`, `tini`) reaps and forwards signals properly and is the better default for any launch-as-entrypoint image. - **TurtleBot 4 with zero ROS topics? Check Wi-Fi before blaming DDS.** `ros2 topic list` empty *and* `turtlebot4.service` FAILED with `rcl node's rmw handle is invalid, at ./src/rcl/node.c:415` means node creation itself failed for lack of a DDS network interface — not a ROS bug or a QoS issue. Root cause (2026-07-24, tb4-teleop): the robot never joined Wi-Fi (`wlan0` DOWN) while `/etc/turtlebot4/cyclonedds_rpi.xml` binds CycloneDDS to `wlan0` only, so DDS had no interface to bind and every node's rmw handle came up invalid. Fix: bring `wlan0` up (join the network), then `systemctl restart turtlebot4.service` → topics return (24 in that session). Verified 2026-07-24 (tb4-teleop). - **TurtleBot 4: when the Create 3 base is invisible to the Pi, restart the base's *application* — the Pi-side config is almost never the problem.** Symptom: `ros2 node list` shows no `/motion_control`, no `/battery_state`, and `/cmd_vel` reaches nothing (the robot won't drive), yet the base pings on `usb0` (`192.168.186.2`). `/scan` keeps streaming because the RPLIDAR is a Pi-local node, which masks the break completely — seeing the scan proves nothing about the base link. The same wedge also follows a Pi reboot or a network flip (signature then: `/motion_control` node count 0, only `/robot_state_publisher` left, no `/wheel_status` or `/battery_state`; seen 3×+, tb4-teleop). The cause is the Create 3's **ROS 2 application getting stuck**, and it's fixed **on the base, not the Pi**. Prefer the scriptable endpoint over clicking the web UI: `curl -X POST -H "Content-Type: application/json" -d '{}' http://192.168.186.2/api/restart-app` — the endpoint REQUIRES a JSON body, so a bare `curl -X POST` hangs (curl exit 28 / HTTP 000). ~30 s later `/motion_control` returns and `/cmd_vel`'s subscription count goes 0→1, so this one-liner can back a self-healing watchdog. Related base endpoints: `/api/reboot`, `/api/forget-wifi`, `/api/restart-ntpd`. Equivalent by hand: the Create 3 web UI → **Application → Restart application**. Reach the web UI headlessly by tunneling it off the Pi-only `usb0` net: `ssh -L 8888:192.168.186.2:80 ubuntu@` → `http://localhost:8888` → Application → Configuration (confirm `RMW_IMPLEMENTATION`, ROS_DOMAIN_ID, and namespace all match the Pi — they usually already do) and Restart application. **Dead-ends — ~10 Pi-side attempts across two builds, none worked:** editing `CYCLONEDDS_URI` (unset / explicit `usb0` / unicast `` to the base), FastDDS discovery-server mode, matching Pi/base clocks, `POST http://192.168.186.2/api/reboot`, and a full physical power-cycle (storage-mode → dock). A `CYCLONEDDS_URI` edit that once *seemed* to fix this did **not** reproduce — the DDS interface config and the clock are red herrings. Verified 2026-07-25 (tb4-teleop): after Restart application, `/motion_control` back, `/battery_state` → 0.97, robot drove. - **Inspecting Create 3 (best-effort) topics from the CLI.** `ros2 topic echo` defaults to RELIABLE QoS and silently receives nothing from the base's best-effort publishers — pass `--qos-reliability best_effort`. And `ros2 topic pub --once /cmd_vel …` HANGS on "Waiting for at least 1 matching subscription" because the base subscribes in a separate DDS realm invisible to the publisher (so `ros2 topic info /cmd_vel` also shows 0 subscribers even when working) — add `-w 0` to publish without waiting. For a base-alive check, echo a *fast* topic (`/imu`, `/wheel_status`) with `--once`, not `/battery_state` — the battery publishes slowly, so `--once` on it returns nothing even on a healthy base and reads as a false "base dead". Verified 2026-07-24 and 2026-07-26 (tb4-teleop). - **TurtleBot 4 / Create 3 stops obeying *backward* commands — it's a safety reflex, not your teleop.** The cliff sensors face forward only, so the base limits reverse travel (it can't see a cliff behind it) and silently drops back commands after a short distance. The `motion_control` node's `safety_override` string parameter controls it: `none` (default, full safety) / `backup_only` (removes the back-up limit, KEEPS cliff safety — usually what you want) / `full` (all safety off). Runtime: `ros2 param set /motion_control safety_override backup_only` (resets on base-app restart). Persist via the Create 3 web UI → Application → "Application ROS 2 Parameters File" (raw YAML, unvalidated): `/motion_control: {ros__parameters: {safety_override: "backup_only"}}`, then Restart application. Verified 2026-07-26 (tb4-teleop: get `none` → set → `backup_only`); docs `iroboteducation.github.io/create3_docs/api/safety/`. ## Customization - **Different ROS 2 distro:** this skill's commands are written against **Lyrical Luth**, the current LTS. Swap `lyrical` for another distro name in `/opt/ros//setup.bash` and in the example package's dependency versions; re-verify package availability for that distro first. The ROS 2 + Nav2 + Gazebo navigation vertical currently defaults to **Jazzy Jalisco** instead, because Nav2 has not yet shipped binaries for Lyrical — see `nav2`'s and `architect`'s Platform gotchas for the current status before picking a distro for that path. - **ament_cmake instead of ament_python:** the workspace/colcon/rosdep/launch mechanics in this skill are build-type-agnostic; only package internals differ (a `CMakeLists.txt` build/install pipeline instead of `setup.py`/`setup.cfg`, with `find_package`/`ament_target_dependencies` instead of Python imports). See `references/workspace-and-packages.md` for both anatomies side by side. - **Different node/topic names in the example package:** `package.xml`'s ``, `setup.py`'s `package_name`/console-script entry point, and the launch file's `package=`/`executable=` must all agree — rename all four places together (see `examples/package-ament-python/`) rather than drifting one and hitting a confusing `ros2 run`/`ros2 launch` "not found". ## References - `references/workspace-and-packages.md` — workspace layout, colcon build mechanics, underlay/overlay sourcing, ament_python vs ament_cmake package anatomy, rosdep workflow, adding dependencies. - `references/launch-patterns.md` — Python launch files in depth: Node actions, launch arguments, parameter files, remapping, includes, and the remap+relay bridging pattern. - `references/interfaces-and-qos.md` — topics/services/actions overview, the full QoS policy set, compatibility rules, preset profiles, and TF2 basics. - `references/debugging.md` — the `ros2 doctor`/`ros2 topic`/`ros2 node` introspection toolkit, common failure signatures (unsourced shell, domain ID collision, QoS mismatch, missing rosdep install) and how to tell them apart. - `examples/package-ament-python/` — a minimal, internally-consistent ament_python package: `package.xml`, `setup.py`, `setup.cfg`, one parameterized publisher node, one launch file (status: unverified — each file links its own upstream source). - Upstream: [ROS 2 documentation](https://docs.ros.org/) (blocked for direct fetch on 2026-07-10 — verified via the `ros2/ros2_documentation` GitHub repo through ctx7 instead; re-check docs.ros.org directly when it's reachable), [colcon documentation](https://colcon.readthedocs.io/), [ros2/launch](https://github.com/ros2/launch), [ros-tooling/topic_tools](https://github.com/ros-tooling/topic_tools). Sibling skills: `nav2`, `gazebo`, `rviz2` (load alongside), `environments` (macOS/Docker setup), `integration` (cross-boundary comms, compose), `architect` (routes here). ## Changelog - 1.7.0 (2026-08-02): annotate SKILL.md; update callback-group-executor-concurrency [reasons: obs-ros2-001, obs-ros2-003] (applied by apply_deltas) - 1.6.0 (2026-08-02): add Usage patterns; add Usage patterns [reasons: obs-ros2-001, obs-ros2-003] (applied by apply_deltas) - 1.5.1 (2026-08-01): anchor IDs added to claim-bearing items (learning-engine Phase 1); no content changes. - 1.5.0 (2026-07-31): tb4-teleop absorption — new gotcha: TB4 zero topics + `turtlebot4.service` "rcl node's rmw handle is invalid (node.c:415)" = Wi-Fi down (`wlan0`) while cyclonedds_rpi.xml binds DDS to `wlan0` only (bring up Wi-Fi, restart the service → 24 topics); and UPGRADED the Create 3 base-app restart from a web-UI click to the scriptable `curl -X POST .../api/restart-app` one-liner (requires a JSON body or it hangs, exit 28 / HTTP 000; ~30 s to recover; enables a self-healing watchdog). - 1.4.0 (2026-07-26): tb4-teleop absorption — two Create 3 gotchas: reverse commands silently dropped by the base backup-limit reflex → set `motion_control` `safety_override=backup_only` (persist via the base web-UI ROS 2 Parameters YAML); and base-alive checks should echo a fast topic (`/imu`, `/wheel_status`), not the slow `/battery_state` (false "base dead"). - 1.3.0 (2026-07-25): tb4-teleop — CORRECTS the 1.2.0 base-invisible fix. The real, reliable fix is the base's web-UI **Application → Restart application** (the Create 3 ROS 2 app gets stuck); the Pi-side `CYCLONEDDS_URI` edit was coincidental and did NOT reproduce (~10 Pi-side attempts failed across two builds). Added the `ssh -L` tunnel for reaching the base web UI headlessly. - 1.2.0 (2026-07-24): tb4-teleop absorption — two TurtleBot 4 / Create 3 gotchas that cost ~7 failed resets: the stock `CYCLONEDDS_URI` interface restriction blocks base discovery over `usb0` (robot won't drive; `/scan` masks it — disable the export), and Create 3 base topics need `--qos-reliability best_effort` to echo plus `-w 0` to `ros2 topic pub` (split-DDS hides the subscriber). Clock-skew ruled out as a red herring. - 1.1.0 (2026-07-13): nav-trial absorption — two container/shell gotchas that cost real debugging time: `set -u` before sourcing a ROS setup script aborts on ROS's own unset vars (source first, then set -u), and `ros2 launch` as PID 1 ignores SIGTERM (kernel drops unhandled signals to PID 1) so teardown must use SIGINT or an init shim. Both were previously captured only in demo-specific notes. - 1.0.1 (2026-07-12): skill-refiner run 1 — provenance claims date-stamped ('this session' → 2026-07-10, the authoring session) so the staleness sweep can age them.