Awesome

micro-ROS for Renesas e² studio

This package eases the integration of micro-ROS in a Renesas e² studio. This components targets Renesas RA family, an ARM Cortex-M based MCU series, enabling a full micro-ROS compatibility for developing robotics and IoT applications.

• micro-ROS for Renesas e2 studio
  • Supported platforms
  • Requirements
  • Getting started
  • Using the micro-ROS Agent
  • Integrating micro-ROS in your project
  • Adding custom packages to the micro-ROS build
  • License
  • Known Issues / Limitations

Supported platforms

Requirements

• Renesas e² studio for Linux¹
• FSP v5.6.0 board packs for Renesas e² studio: Details.
• GNU Arm Embedded Toolchain v10.3.1.20210824 (Other compatible toolchain may work).
• Install rsync: apt -y install rsync
• Install colcon and dependencies, for example with:

pip3 install colcon-common-extensions catkin_pkg lark-parser empy

¹ Currently only support for Linux is available

Getting started

A ready-to-use example of this component can be found in micro-ROS demos for Renesas e² studio repo.

Using the micro-ROS Agent

It is possible to use a micro-ROS Agent just by using this docker command:

# UDPv4 micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO udp4 --port 8888 -v6

# TCPv4 micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO tcp4 --port 8888 -v6

# Serial micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO serial --dev [YOUR BOARD PORT] -v6

# CAN-FD micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO canfd --dev [YOUR CAN INTERFACE] -v6

There are some other options for using the micro-ROS Agent:

• Building it in a ROS 2 environment: Details.
• Using a snap package.

Integrating micro-ROS in your project

micro-ROS can be integrated with a Renesas e² studio project following these steps:

1. Clone this repository in your Renesas e² studio project folder.

2. Go to Project -> Properties -> C/C++ Build -> Settings -> Build Steps Tab and in Pre-build steps add:

cd ../micro_ros_renesas2estudio_component/library_generation && ./library_generation.sh "${cross_toolchain_flags}"

3. Add <b>micro-ROS include directory</b>.

   <details> <summary>Steps</summary>

   In Project -> Settings -> C/C++ Build -> Settings -> Tool Settings Tab -> GNU ARM Cross C Compiler -> Includes

   • add "${workspace_loc:/${ProjName}/micro_ros_renesas2estudio_component/libmicroros/include}" in Include paths (-l)
   </details>

4. Add the micro-ROS precompiled library.

   <details> <summary>Steps</summary>

   In Project -> Settings -> C/C++ Build -> Settings -> Tool Settings Tab -> GNU ARM Cross C Linker -> Libraries

   • add "${workspace_loc:/${ProjName}/micro_ros_renesas2estudio_component/libmicroros}" in Library search path (-L)
   • add microros in Libraries (-l)
   </details>

5. Add the following source code files to your project, dragging them to source folder.

   • extra_sources/microros_time.c
   • extra_sources/microros_allocators.c
   • extra_sources/microros_allocators.h
   • extra_sources/microros_transports.h

6. Configure micro-ROS time reference.

   <details> <summary>Steps</summary>

   Configure g_timer0 as an r_agt

   1. Double click on the configuration.xml file of your project and go to the Stacks tab.

   2. Select New Stack -> Timer Low-Power (r_agt).

   3. Modify the clock period on the component properties (Module g_timer0 Timer, Low-Power (r_agt) -> General -> Period) to 100

   4. Modify the clock period unit on the component properties (Module g_timer0 Timer, Low-Power (r_agt) -> General -> Period Unit) to Microseconds

   5. Modify the count source on the component properties (Module g_timer0 Timer, Low-Power (r_agt) -> General -> Count Source) to PCLKB

   6. Modify the interrupt callback on the component properties (Module g_timer0 Timer, Low-Power (r_agt) -> Interrupt -> Callback) to micro_ros_timer_cb

   7. Modify the underflow interrupt priority on the component properties (Module g_timer0 Timer, Low-Power (r_agt) -> Interrupt -> Underflow Interrupt Priority) to Priority 12

      

   8. Save the modifications by clicking on Generate Project Content.

   </details>

7. Configure micro-ROS memory requirements.

   <details> <summary>Bare Metal</summary>

   Configure the stack and heap size:

   1. On the configuration.xml menu, go to the BSP tab.

   2. Go to the RA Common section and set the Main stack size (bytes) and Heap size (bytes) fields to 5000 B:

      

   3. Save the modifications by clicking on Generate Project Content.

   </details> <details> <summary>FreeRTOS</summary>

   Create and configure the micro-ROS FreeRTOS task:

   1. On the configuration.xml menu, go to the Stacks tab and create a new thread for micro-ROS.

   2. Click on the created thread, then select New Stack -> FreeRTOS Heap 4.

   3. Configure the micro-ROS thread properties:

      1. Set the name of the thread entry function under Thread -> Symbol to micro_ros_thread.
      2. Set Thread -> Stack size (bytes) to 5000 B.
      3. Set Common -> Memory Allocation -> Support Dynamic Allocation to Enable.
      4. Set Common -> Memory Allocation -> Support Static Allocation to Enable.
      5. Set Common -> Memory Allocation -> Total Heap Size to 65000 B.

      

   4. On the configuration.xml menu, go to the BSP tab.

   5. Go to the RA Common section and set the Main stack size (bytes) and Heap size (bytes) fields to 5000 B:

      

      Note: It is required to have some heap outside FreeRTOS heap because newlib will use it

   6. Save the modifications clicking on Generate Project Content.

   7. Check that the file thread_microros_entry.c has been created on the project source directory.

   </details> <details> <summary>ThreadX</summary>

   Create and configure the micro-ROS ThreadX thread:

   1. On the configuration.xml menu, go to the Stacks tab and create a new thread for micro-ROS.

   2. Configure the micro-ROS thread properties:

      1. Set the name of the thread entry function under Thread -> Symbol to micro_ros_thread.
      2. Set and the thread stack size Thread -> Stack size (bytes) to 5000 B.
      3. Increase thread timer resolution Common -> Timer -> Timer Ticks Per Second to 1000 ticks per second.

      

   3. On the configuration.xml menu, go to the BSP tab.

   4. Go to the RA Common section and set the Main stack size (bytes) and Heap size (bytes) fields to 5000 B:

      

   5. Save the modifications by clicking on Generate Project Content.

   6. Check that the file thread_microros_entry.c has been created on the project source directory.

   </details>

8. Configure the micro-ROS transports: Details.

9. Add micro-ROS code in your codebase.

10. Build and run your project.

Adding custom packages to the micro-ROS build

In order to include a custom package in the micro-ROS build, just copy the package folder into library_generation/extra_packages folder. The build system will automatically detect the package and build it along with the micro-ROS library.

Note that a library rebuild is needed to include the package, this can be achieved by deleting the libmicroros generated folder and building your project afterwards.

License

This repository is open-sourced under the Apache-2.0 license. See the LICENSE file for details.

For a list of other open-source components included in this repository, see the file 3rd-party-licenses.txt.

Known Issues / Limitations

There are no known limitations.