RZV2H RDK Multi-OS Example Packages

This section contains a collection of Multi-OS packages designed for applications on Renesas RZ/V MPU platforms, specifically targeting the RZ/V2H RDK.

These packages provide practical examples demonstrating how to operate and integrate Multi-OS environments on the RZ/V2H RDK, helping developers understand cross-core communication, system setup, and interaction between Linux and RTOS components.

Additionally, a demo showcasing Micro-ROS (uROS) running on the real-time CR8 core is supported. It demonstrates the implementation of Micro-ROS on an MCU-class core within the device.

Hardware supported

Platform: Renesas RZ/V2H MPU
Development Board: RZ/V2H RDK (SoC: R9A09G057H44GBG)

Software supported

Target RZ/V2H RDK image: ubuntu-24.04-server-arm64-rzv2h-rdk.img.xz
RZ/V Multi-OS Package version 3.2
RZ/V FSP version 3.1
Micro XRCE-DDS Agent version 3.0.1
Micro ROS Client Jazzy
ROS2 Distribution: ROS2 Jazzy

Package Specification

The following table provides an overview of the Multi-OS example packages, including their target cores, operating systems, and main functionalities.

You can access the source code and detailed documentation for each package through the provided links.

Important

Please use the shortest path possible. If you place the project in a deeply nested path, you may encounter issues when building the project with e² studio.

The recommended workspace path for e² studio on Windows is C:\rzv2h_e2_workspace.

Package	Target Core	Purpose / Description
Micro XRCE-DDS Agent	CA55 (Linux)	Provides the middleware agent running on the Linux core (CA55) for communication between Micro-ROS clients (running on RTOS CR8_0 core) and the ROS 2 environment on Linux via the XRCE-DDS protocol.
RZ/V2H RDK Blinky	CM33 (RTOS)	A simple LED blinking demo running on the CM33 core that verifies basic GPIO functionality and confirms that the RTOS environment is running correctly on the RZ/V2H RDK.
RZ/V2H RDK CM33 RPMsg Linux-RTOS Demo	CM33 (RTOS)	Demonstrates inter-core communication (RPMsg) between the Linux core (CA55) and the CM33 RTOS core, showing message exchange and synchronization.
RZ/V2H RDK CR8 Core0 RPMsg Linux-RTOS Demo	CR8_0 (RTOS)	Demonstrates RPMsg-based communication between the Linux core (CA55) and the CR8_0 real-time core, validating message passing and core coordination.
RZ/V2H RDK CR8 Core0 RPMsg Micro-ROS Demo	CR8_0 (RTOS)	Showcases Micro-ROS running on the CR8_0 real-time core, integrating the uROS client with the custom RPMsg transport layer for communication with Linux and ROS 2.

Installation Guide

To set up and use the Multi-OS example packages on the RZ/V2H RDK, follow the steps below:

Firmware Code for CM33/CR8

This section describes how to build and flash the firmware for the CM33/CR8 core using e² studio and the provided sample project.

Clone the CM33/CR8 project into your host machine.
Open e² studio and import the above project using “Import Existing Project”.
Open the configuration file.
Click “Generate” to generate configuration files.
Click “Build Project” and wait for the build process to complete.
Flash the firmware to the CM33/CR8 core using your preferred method (e.g., J-Link).

Important

The preceding project for all of CR8_0 packages is RZ/V2H RDK CM33 RPMsg Linux-RTOS Demo. Please import this CM33 project into your e² studio workspace and build it before using the CR8_0 packages.

Special Note for RZ/V2H RDK CR8 Core0 RPMsg Micro-ROS Demo Package

This demo includes a pre-built libmicroros library. If you want to rebuild this library, use this project on the Ubuntu host PC machine and perform the following steps:

Go to Project → Properties → C/C++ Build → Settings → Build Steps tab and in Pre-build steps, add the command:
```
cd ../micro_ros_renesas2estudio_component/library_generation && ./library_generation.sh "${cross_toolchain_flags}"
```
Then click Apply and Close → Build the project.
The code includes a 30-second delay (in main_task_entry.c line 168) before initializing MCU tasks to prevent issues with PWM and I2C pin control on the CR8 core. By default, this delay is commented out.
- If flashing via J-Link, this delay can be skipped.
- However, when invoking the firmware from U-Boot, please enable this delay.

Usage Guide

To run the Multi-OS example packages on the RZ/V2H RDK, follow the instructions below for each package.

Install the libsysfs-dev package on the target board, which is required by the Multi-OS applications:

sudo apt update
sudo apt install -y libsysfs-dev

RPMsg Linux-RTOS Demo

This demo behaves identically to the version released in the RZ/V Multi-OS Package.

For more details, refer to the RZ/V2H Quick Start Guide: Section 4.4 CM33/CR8 Sample Program Invocation for communicating with Linux for the RZ/V Multi-OS Package.

Flash the RPMsg Linux-RTOS Demo firmware to the target board.

On the board’s terminal, run the rpmsg_sample_client with sudo privilege:

sudo rpmsg_sample_client

Example output:

[694] proc_id:0 rsc_id:0 mbx_id:1
metal: warning:   metal_linux_irq_handling: Failed to set scheduler: -1.
metal: info:      metal_uio_dev_open: No IRQ for device 10480000.mbox-uio.
[694] Successfully probed IPI device
...

Based on the firmware you have flashed, select the corresponding option below and press Enter when prompted.

Input Option	Target Core / Firmware	Description
1	CM33 (Linux <=> RTOS RPMsg Demo)	Select this if you have flashed the `RZ/V2H RDK CM33 RPMsg Linux-RTOS Demo` firmware.
4	CR8_0 (Linux <=> RTOS RPMsg Demo)	Select this if you have flashed the `RZ/V2H RDK CR8 Core0 RPMsg Linux-RTOS Demo` firmware.

Note

Ensure that the firmware on your target board matches the selected option to avoid communication errors.

Example output:

If the Input Option is 1:

[CM33]  received payload number 469 of size 486
[CM33] sending payload number 470 of size 487
[828] cond signal 1 sync:0
...

If the Input Option is 4:

[CR8_0 ]  received payload number 469 of size 486
[CR8_0 ] sending payload number 470 of size 487
[790] cond signal 2 sync:0
...

By typing e, the sample program should terminate with the message shown below:

please input
> e
[xxx] 42f00000.rsctbl closed
[xxx] 43000000.vring-ctl0 closed
...

uROS and Custom Micro XRCE-DDS Agent

This section describes how to run the Micro-ROS Client demo and the custom XRCE-DDS RPMsg Agent.

Prerequisite

Install ROS 2 Jazzy on the CA55 core (Ubuntu side). You can find and use the provided script here: apt_install_ros2.sh.

Quick installation steps:

wget https://raw.githubusercontent.com/renesas-rdk/ros2_demo_workspace/refs/heads/main/common_utils/apt_install_ros2.sh
chmod +x apt_install_ros2.sh
sudo ./apt_install_ros2.sh

For detailed installation instructions, refer to the official ROS 2 documentation: ROS 2 Jazzy Installation Guide.

Cross Compile the Micro XRCE-DDS Agent

Before running the Micro-ROS demo on the CR8 core, you need to cross-compile the custom Micro XRCE-DDS Agent for the Linux CA55 core.

Note

If you have already set up this Docker container (e.g., when building a ROS 2 application), you can use the same container to compile the Micro XRCE-DDS Agent without needing to set up a new environment.

Make sure your machine have the Docker engine installed and running. You can use Windows, Linux, or macOS as your host machine.

For the best experience, it is recommended to use a Ubuntu 24.04 host machine for cross-compilation.

If you are using Windows or macOS, please ensure that Docker Desktop is properly set up and configured to use Linux containers.

Clone the Micro-XRCE-DDS-Agent to your local machine:

git clone https://github.com/renesas-rdk/Micro-XRCE-DDS-Agent.git

Pull the Docker image provided by Renesas RDK for cross-compilation:
```
docker pull ghcr.io/renesas-rdk/rzv2h_ubuntu_xbuild:latest
```

Create a new Docker container:

docker run -it --rm -v /path/to/Micro-XRCE-DDS-Agent:/home/ubuntu/Micro-XRCE-DDS-Agent ghcr.io/renesas-rdk/rzv2h_ubuntu_xbuild:latest

Replace /path/to/Micro-XRCE-DDS-Agent with the actual path on your host machine where the repository is located.

Navigate to the Micro-XRCE-DDS-Agent directory inside the Docker container:
```
cd Micro-XRCE-DDS-Agent/
```

Build the project:

mkdir build && cd build

cmake .. -DCMAKE_TOOLCHAIN_FILE=$TOOLCHAINS_WS/cross.cmake \
         -DUAGENT_BUILD_USAGE_EXAMPLES=ON \
         -DUAGENT_LOGGER_PROFILE=OFF \
         -DCMAKE_BUILD_TYPE=Release \
         -DCMAKE_INSTALL_PREFIX=./arm64-install

make -j$(nproc)
make install

Note

Note that the -DUAGENT_LOGGER_PROFILE is set to OFF due to incompatibility during cross-building.

If you want to see the logs, please build the libraries natively on the RZ/V2H RDK without the -DUAGENT_LOGGER_PROFILE=OFF flag.

Wait until the build process completes.

Deploy the output to the target board by copying the output artifact:

On the Host machine:

# Copy the built CustomXRCEAgent binary to the arm64-install folder for deployment
cp ./examples/custom_agent/CustomXRCEAgent arm64-install/bin

# Compress the arm64-install folder
tar -cf libdds_agent.tar.bz2 -C arm64-install .

Then copy libdds_agent.tar.bz2 to the target board using scp or another file transfer method.

On the Target machine:

# Extract the archive
mkdir tmp-install
sudo tar -xf libdds_agent.tar.bz2 -C tmp-install

# Install libdds_agent to the system
cd tmp-install
sudo cp -r * /usr/local/
sudo ldconfig

(Optional) Connect the UART-to-TTL cable to GPIO 40 pins on the RDK board to view log output from the CR8 core over UART channel 5.

UART5 Interface Pins

Pin Name

Function

Description

P72 - GPIO14 - Pin number 8

TXD5

UART5 transmit data (TX) signal.

P73 - GPIO15 - Pin number 10

RXD5

UART5 receive data (RX) signal.
Flash the RZ/V2H RDK CR8 Core0 RPMsg Micro-ROS Demo firmware to the target board.

On the board’s terminal, run the CustomXRCEAgent with sudo privilege:

sudo CustomXRCEAgent

Example output:

[787] proc_id:0 rsc_id:0 mbx_id:1
metal: warning:   metal_linux_irq_handling: Failed to set scheduler: -1.
...

On another terminal, use the following ROS 2 commands to verify communication:

Note

Because the custom Micro XRCE-DDS Agent bridges the CR8 core and the ROS 2 environment on Linux by using sudo privileges, you must also run ROS 2 commands with sudo to view the relevant topics and messages.
```
sudo su
source /opt/ros/jazzy/setup.bash
ros2 topic list
ros2 topic echo /cr8/heartbeat
```

Behavior:

The CR8 firmware creates the topic /cr8/heartbeat and continuously publishes data to it.
The custom Micro XRCE-DDS Agent makes this topic available in the ROS 2 environment running on the CA55 core.
From the CA55 core, you can subscribe to and retrieve data from the /cr8/heartbeat topic.

sudo su
source /opt/ros/jazzy/setup.bash
ros2 topic list

Example output:

/cr8/heartbeat
/parameter_events
/rosout

See the data from the CR8 core by running:

ros2 topic echo /cr8/heartbeat

Example output:

data: 328
---
data: 329
---
data: 330
...

Troubleshooting

Can’t see the heartbeat topic or data?

Make sure you have run the CustomXRCEAgent with sudo privileges and that the agent is running without errors.

Check the terminal where you ran the CustomXRCEAgent for any error messages or logs that might indicate issues with the agent or communication.

Also, ensure that you are running the ROS 2 commands with sudo privileges to access the topics bridged by the agent.
Can’t open the configuration.xml of CR8 e² studio project?

Confirm the RZ/V FSP version is 3.1 and import the CM33 project into the workspace and build it first, then try opening the CR8 project again.
The behavior of the RPMsg demo is strange?

Reboot the RDK board to reset the RPMsg endpoint.
Unknown status of the micro-ROS demo?

Use a USB-to-TTL module to read logs from the UART interface of the RDK board (baud rate: 115200).

You should see output similar to the following:
```
[CR8] Start main_task_entry
[CR8] RPMsg endpoint ready
[CR8] Heartbeat publisher ready on /cr8/heartbeat
[CR8] Heartbeat #50 (uptime=16061 ms)
```
You should run the CustomXRCEAgent only after the message [CR8] RPMsg endpoint ready appears on the UART log.
Can’t flash the firmware over J-Link?

Make sure you are using the correct J-Link firmware version and that DIP switch SW1-6 is turned ON.

UART5 Interface Pins
Pin Name	Function	Description
P72 - GPIO14 - Pin number 8	TXD5	UART5 transmit data (TX) signal.
P73 - GPIO15 - Pin number 10	RXD5	UART5 receive data (RX) signal.