ROS 2 VS Code Workspace Configuration

This section explains the VS Code workspace configuration used for deploying, running, and debugging ROS 2 applications on the Renesas RZ/V2H RDK platform.

Prerequisites

Complete the Cross compilation environment setup section.
Access the Docker container using VS Code and the Dev Containers extension.
Open the /home/ubuntu/ros2_ws/ directory in the Docker container.

Expected Workspace Structure

The following workspace structure is expected after cross-building the ROS 2 application:

ros2_ws/
├── AGENTS.md        # Documentation for Codex agent
├── build
├── .clang-format
├── .claude          # Skills and tools for Claude agent
├── .github          # Skills and tools for Copilot agent
├── install          # Installation directory generated by the ``cross-colcon-build`` command
├── log
├── src              # Source code directory for ROS 2 packages, must use `src` as the directory name
└── .vscode          # VS Code configuration directory

If your workspace does not contain the .vscode/ directory, you can copy it manually from the $TOOLCHAIN_WS directory.

Install Recommended VS Code Extensions

Install the extra VS Code extensions recommended for ROS 2 development:

Open the Command Palette in VS Code (Ctrl+Shift+P).
Run Extensions: Show Recommended Extensions.
Install the workspace-recommended extensions, including the C/C++ Extension Pack and Task Buttons.

VS Code Configuration Files

VS Code configuration files are located in the .vscode/ directory of your ROS 2 workspace:

.vscode/
├── c_cpp_properties.json      # C/C++ extension configuration file
├── deploy.sh                  # Deployment script to copy files to target
├── launch.json                # Debugger launch configuration file
├── run_program.sh             # Script to run the program on target
├── settings.json              # VS Code workspace settings file
├── start_target_gdbserver.sh  # Script to start gdbserver on target
└── tasks.json                 # Task runner configuration file

By default, the Dockerfile creates these configuration files when the Docker container is built.

Workspace Settings

Open the settings.json file and edit the following variables to match your development environment.

Attention

These variables are essential for the remote debugging and deployment workflow.

Please ensure they are set correctly before using the VS Code tasks.

Debug Configuration Variables
Variable	Required	Description	`ros2 run`	`ros2 launch`
`HOST_GDB_PATH`	No	Path to the GDB executable on the host machine.	No	No
`TARGET_LOCAL_SYSROOT`	No	Path to the target device sysroot on the host machine.	No	No
`TARGET_IP`	Yes	IP address of the target device.	Yes	Yes
`TARGET_GDB_PORT`	No	GDB server port on the target device.	No	No
`TARGET_USER`	No	Username for connecting to the target device.	No	No
`TARGET_PASSWORD`	No	Password for authenticating to the target device.	No	No
`TARGET_ROS2_WS`	No	ROS 2 workspace path on the target device.	No	No
`NODE_PACKAGE_NAME`	Yes	ROS 2 package name that contains the executable.	Yes	Debug only
`NODE_EXECUTABLE_NAME`	Yes	Name of the executable to start.	Yes	Debug only
`LAUNCH_PACKAGE_NAME`	Yes	ROS 2 package name that contains the launch file.	No	Yes
`LAUNCH_FILE_NAME`	Yes	Launch file name used to start the ROS 2 application.	No	Yes

Note

Variables marked as No should be modified only if your development environment differs from the default environment provided by the Docker image.
Variables marked as Yes must be set correctly each time you run the workflow.

Supported VS Code Tasks

The following VS Code tasks are available in the workspace.

These tasks are defined in the tasks.json file and can be executed from the Command Palette (Ctrl+Shift+P) by searching for Run Task and selecting the desired task.

Supported VS Code Tasks
Task	Description
ROS2: SSH to Target	Starts an SSH session to the target board.
ROS2: Debug Run (GDB)	Starts remote debugging for a ROS 2 node by using the `ros2 run` command with `gdbserver`.
ROS2: Debug Launch (GDB)	Starts remote debugging for a ROS 2 node in a launch file by using the `ros2 launch` command with `gdbserver`.
ROS2: Run Package Executable	Runs a ROS 2 node by using the `ros2 run` command.
ROS2: Launch Package LaunchFile	Runs ROS 2 nodes by using the `ros2 launch` command.
ROS2: Deploy to Target	Deploys the `install` directory to the target board.
ROS2: Build Debug	Builds the workspace with the `Debug` configuration.
ROS2: Build Release	Builds the workspace with the `Release` configuration.
ROS2: Clean All	Cleans all build artifacts, including the `build`, `install`, and `log` directories.

Task Buttons

For added convenience, you can use the Task Buttons extension to run these tasks directly from buttons in the VS Code interface.

Task buttons are defined in the settings.json file, and you can customize which tasks are shown.

The following tasks are configured as buttons by default. You can access them from the bottom toolbar.

Default Task Buttons
Button Label	Task	Description
`Deploy`	`ROS2: Deploy to Target`	Deploys built binaries to the target device ROS 2 workspace.
`Clean All`	`ROS2: Clean All`	Cleans the `build`, `install`, and `log` directories on the host.
`Run LaunchFile`	`ROS2: Launch Package LaunchFile`	Launches the specified launch file from the specified package on the target device. Make sure `LAUNCH_PACKAGE_NAME` and `LAUNCH_FILE_NAME` are configured correctly in `settings.json`.
`Run ExecutableFile`	`ROS2: Run Package Executable`	Runs the specified executable from the specified package on the target device. Make sure `NODE_PACKAGE_NAME` and `NODE_EXECUTABLE_NAME` are configured correctly in `settings.json`.
`SSH to Target`	`ROS2: SSH to Target`	Opens an SSH session to the target device.

Available AI Agent Skills

The workspace ships a shared library of Agent Skills — focused, self-contained workflow guides that AI coding agents read before acting on a task. The same library is shared by three agents so that build, deploy, debug, and packaging behavior is consistent regardless of which assistant is driving.

Agent entry points

Each agent reads a different top-level file, but all of them route to the same skills under .github/skills/:

AI Agent Entry Points
Agent	Entry point	Role
GitHub Copilot	`.github/copilot-instructions.md`	Primary router. Defines the skill table and general rules.
Claude (Claude Code)	`.claude/` (`skills` symbol-linked to `.github/skills`)	Reuses the same skills; permissions set in `.claude/settings.json`.
Codex	`AGENTS.md`	Points the agent at `copilot-instructions.md` and its router.

Because .claude/skills is a symbolic link to .github/skills, a single edit to a SKILL.md file updates every agent at once.

Skill router

Agents pick a skill by the primary verb of the request, as defined in .github/copilot-instructions.md:

Skill Router
Intent	Skill
Build / cross-compile / rosdep / sysroot / clean	`arm64-cross-build`
Deploy / run / launch / GDB via VS Code tasks	`arm64-deploy-debug`
SSH on board for agent-driven validation, OTA test	`arm64-target-autonomous-test`
Create / edit / review a ROS 2 package’s structure	`arm64-ros2-package-conventions`

If more than one could apply, agents follow the workflow order conventions → build → deploy → on-device test.

Skill reference

Available Skills
Skill	Purpose
`arm64-cross-build`	Build, clean, or install dependencies in the ARM64 ROS 2 Jazzy cross-compilation workspace; investigate cross-compile failures and produce debug builds for GDB.
`arm64-deploy-debug`	Interactive, VS Code task-driven deployment, running, launching, and remote GDB debugging on the target board.
`arm64-target-autonomous-test`	Unattended, agent-driven SSH validation on the board: smoke tests, journal inspection, reproducing issues, OTA verification.
`arm64-ros2-package-conventions`	Package layout, naming, formatting, dependency declaration, and `ros2_control` structure for packages under `src/`.
`git-commit`	Compose Conventional Commits messages with intelligent staging and message generation from the diff.

General rules for agents

The shared guidance instructs all agents to:

Prefer existing workspace tasks, launch configurations, and scripts under .vscode/ over ad hoc shell commands.
Avoid generic ROS 2 workflows when this repository already defines a workspace-specific one.
Never invent target-board credentials, IPs, or paths — always read them from .vscode/settings.json.
Treat the board as shared lab hardware: surface intent before any mutation, capture state before changes, and restore it afterward.