From 5b1ec06009108c62b8f84c992544d0990c9903a8 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Wed, 10 Feb 2021 11:08:18 +0100 Subject: [PATCH 1/5] Initial --- _data/docs.yml | 1 + .../create_custom_static_library/index.md | 139 ++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 _docs/tutorials/advanced/create_custom_static_library/index.md diff --git a/_data/docs.yml b/_data/docs.yml index 26b0c664..6526f889 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -61,6 +61,7 @@ - tutorials/advanced/tracing - tutorials/advanced/benchmarking - tutorials/advanced/zephyr_emulator + - tutorials/advanced/create_custom_static_library - title: Demos docs: diff --git a/_docs/tutorials/advanced/create_custom_static_library/index.md b/_docs/tutorials/advanced/create_custom_static_library/index.md new file mode 100644 index 00000000..6b5a3836 --- /dev/null +++ b/_docs/tutorials/advanced/create_custom_static_library/index.md @@ -0,0 +1,139 @@ +--- +title: Creating custom static micro-ROS library +permalink: /docs/tutorials/advanced/create_custom_static_library/ +--- + +This tutorial starts in a previously created micro-ROS environment. Check [**First micro-ROS application on an RTOS**](../first_application_rtos/) for instructions about how to create a micro-ROS environment for embedded platforms. + +Once your micro-ROS workspace is created, go to `firmware/mcu_ws` and run the package creating command: + +```bash +cd firmware/mcu_ws +ros2 pkg create --build-type ament_cmake my_custom_message +cd my_custom_message +mkdir msg +touch msg/MyCustomMessage.msg +``` + +In the autogenerated `CMakeLists.txt` file you should add the following lines just before `ament_package()`: + +```cmake +... +find_package(rosidl_default_generators REQUIRED) + +rosidl_generate_interfaces(${PROJECT_NAME} + "msg/MyCustomMessage.msg" + ) +... +``` + +In the autogenerated `package.xml` file you should add the following lines: + +```xml +... +rosidl_default_generators +rosidl_default_runtime +rosidl_interface_packages +... +``` + +The content of the `msg/MyCustomMessage.msg` file contains your message defintion. For example, let's include these fields: + +``` +bool bool_test +byte byte_test +char char_test +float32 float32_test +float64 double_test +int8 int8_test +uint8 uint8_test +int16 int16_test +uint16 uint16_test +int32 int32_test +uint32 uint32_test +int64 int64_test +uint64 uint64_test +``` + +Now, you can build your micro-ROS workspace as usual. As explained in [**First micro-ROS application on an RTOS**](../first_application_rtos/), the `ros2 run micro_ros_setup build_firmware.sh` command will build all packages located inside `mcu_ws`. + +In your micro-ROS application code, you can use your new message type as usual: + +```c +#include + +... + +my_custom_message__msg__MyCustomMessage msg; + +msg.byte_test = 3; +msg.uint32_test = 42; + +... + +rclc_publisher_init_default(&publisher, &node, ROSIDL_GET_MSG_TYPE_SUPPORT(my_custom_message, msg, MyCustomMessage), "my_custom_publisher"); +rcl_publish(&publisher, &msg, NULL); + +... +``` + +You can find further information in the [ROS 2 Create custom ROS 2 msg and srv files](https://index.ros.org/doc/ros2/Tutorials/Custom-ROS2-Interfaces). + +## Using type composition + +It is possible to create custom types that include members from another ROS 2 message types packages. For example let's add a member with type `Point32` from the ROS 2 package `geometry_msgs`. + +First of all, you have to include the dependency in the `CMakeLists.txt`: + +```cmake +... +find_package(rosidl_default_generators REQUIRED) +find_package(geometry_msgs REQUIRED) + +rosidl_generate_interfaces(${PROJECT_NAME} + "msg/MyCustomMessage.msg" + ) +... +``` + +Also, include the dependency in `package.xml`: + +```xml +... +rosidl_default_generators +rosidl_default_runtime +rosidl_interface_packages +geometry_msgs +... +``` + +The message definition in `msg/MyCustomMessage.msg` can now include types from the `geometry_msgs` package: + +``` +... +int64 int64_test +uint64 uint64_test +geometry_msgs/Point32 point32_test +``` + +And finally, in your code you can access this new member of your custom type: + + +```c +#include + +... + +my_custom_message__msg__MyCustomMessage msg; + +msg.byte_test = 3; +msg.uint32_test = 42; + +msg.point32_test.x = 1.23; +msg.point32_test.y = 2.31; +msg.point32_test.z = 3.12; + +... +``` + +Note that in order for the micro_ros_agent to register these new types, the package with the custom types you've created above, should also be cloned to the host workspace, e.g. `~/uros_ws/src`, and compiled there as well before running the agent. From 7f673ed1a3e276d0d067690a5e6b1252ce6aadd0 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Wed, 10 Feb 2021 11:33:31 +0100 Subject: [PATCH 2/5] Update --- .../create_custom_static_library/index.md | 197 ++++++++---------- 1 file changed, 87 insertions(+), 110 deletions(-) diff --git a/_docs/tutorials/advanced/create_custom_static_library/index.md b/_docs/tutorials/advanced/create_custom_static_library/index.md index 6b5a3836..0399db7a 100644 --- a/_docs/tutorials/advanced/create_custom_static_library/index.md +++ b/_docs/tutorials/advanced/create_custom_static_library/index.md @@ -3,137 +3,114 @@ title: Creating custom static micro-ROS library permalink: /docs/tutorials/advanced/create_custom_static_library/ --- -This tutorial starts in a previously created micro-ROS environment. Check [**First micro-ROS application on an RTOS**](../first_application_rtos/) for instructions about how to create a micro-ROS environment for embedded platforms. +This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../first_application_rtos/) for instructions about how to create a micro-ROS environment for embedded platforms. -Once your micro-ROS workspace is created, go to `firmware/mcu_ws` and run the package creating command: +Once your micro-ROS workspace is created and the `micro_ros_setup` tool is installed, we are going to prepare the micro-ROS environment: ```bash -cd firmware/mcu_ws -ros2 pkg create --build-type ament_cmake my_custom_message -cd my_custom_message -mkdir msg -touch msg/MyCustomMessage.msg +ros2 run micro_ros_setup create_firmware_ws.sh generate_lib ``` -In the autogenerated `CMakeLists.txt` file you should add the following lines just before `ament_package()`: +Once all the packages are downloaded, we need to create a couple of files in order to crosscompile a custom static library and a set of header files: -```cmake -... -find_package(rosidl_default_generators REQUIRED) - -rosidl_generate_interfaces(${PROJECT_NAME} - "msg/MyCustomMessage.msg" - ) -... -``` - -In the autogenerated `package.xml` file you should add the following lines: - -```xml -... -rosidl_default_generators -rosidl_default_runtime -rosidl_interface_packages -... -``` - -The content of the `msg/MyCustomMessage.msg` file contains your message defintion. For example, let's include these fields: - -``` -bool bool_test -byte byte_test -char char_test -float32 float32_test -float64 double_test -int8 int8_test -uint8 uint8_test -int16 int16_test -uint16 uint16_test -int32 int32_test -uint32 uint32_test -int64 int64_test -uint64 uint64_test +```bash +touch my_custom_toolchain.cmake +touch my_custom_colcon.meta ``` -Now, you can build your micro-ROS workspace as usual. As explained in [**First micro-ROS application on an RTOS**](../first_application_rtos/), the `ros2 run micro_ros_setup build_firmware.sh` command will build all packages located inside `mcu_ws`. +## Example of a CMake toolchain -In your micro-ROS application code, you can use your new message type as usual: +For example for a Cortex M3 a sample toolchain could be: -```c -#include +```cmake +set(CMAKE_SYSTEM_NAME Generic) +set(CMAKE_CROSSCOMPILING 1) +set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY) -... +# SET HERE THE PATH TO YOUR C99 AND C++ COMPILERS +set(CMAKE_C_COMPILER gcc) +set(CMAKE_CXX_COMPILER g++) -my_custom_message__msg__MyCustomMessage msg; +set(CMAKE_C_COMPILER_WORKS 1 CACHE INTERNAL "") +set(CMAKE_CXX_COMPILER_WORKS 1 CACHE INTERNAL "") -msg.byte_test = 3; -msg.uint32_test = 42; +# SET HERE YOUR BUILDING FLAGS +set(FLAGS "-O2 -ffunction-sections -fdata-sections -fno-exceptions -mcpu=cortex-m3 -nostdlib -mthumb --param max-inline-insns-single=500 -DF_CPU=84000000L -D'RCUTILS_LOG_MIN_SEVERITY=RCUTILS_LOG_MIN_SEVERITY_NONE'" CACHE STRING "" FORCE) -... +set(CMAKE_C_FLAGS_INIT "-std=c11 ${FLAGS} -DCLOCK_MONOTONIC=0 -D'__attribute__(x)='" CACHE STRING "" FORCE) +set(CMAKE_CXX_FLAGS_INIT "-std=c++11 ${FLAGS} -fno-rtti -DCLOCK_MONOTONIC=0 -D'__attribute__(x)='" CACHE STRING "" FORCE) -rclc_publisher_init_default(&publisher, &node, ROSIDL_GET_MSG_TYPE_SUPPORT(my_custom_message, msg, MyCustomMessage), "my_custom_publisher"); -rcl_publish(&publisher, &msg, NULL); - -... +set(__BIG_ENDIAN__ 0) ``` -You can find further information in the [ROS 2 Create custom ROS 2 msg and srv files](https://index.ros.org/doc/ros2/Tutorials/Custom-ROS2-Interfaces). - -## Using type composition - -It is possible to create custom types that include members from another ROS 2 message types packages. For example let's add a member with type `Point32` from the ROS 2 package `geometry_msgs`. - -First of all, you have to include the dependency in the `CMakeLists.txt`: - -```cmake -... -find_package(rosidl_default_generators REQUIRED) -find_package(geometry_msgs REQUIRED) - -rosidl_generate_interfaces(${PROJECT_NAME} - "msg/MyCustomMessage.msg" - ) -... +## Example of a colcon meta file + +A sample colcon.meta file with micro-ROS external transports could be: + +```json +{ + "names": { + "tracetools": { + "cmake-args": [ + "-DTRACETOOLS_DISABLED=ON", + "-DTRACETOOLS_STATUS_CHECKING_TOOL=OFF" + ] + }, + "rosidl_typesupport": { + "cmake-args": [ + "-DROSIDL_TYPESUPPORT_SINGLE_TYPESUPPORT=ON" + ] + }, + "rcl": { + "cmake-args": [ + "-DBUILD_TESTING=OFF", + "-DRCL_COMMAND_LINE_ENABLED=OFF", + "-DRCL_LOGGING_ENABLED=OFF" + ] + }, + "rcutils": { + "cmake-args": [ + "-DENABLE_TESTING=OFF", + "-DRCUTILS_NO_FILESYSTEM=ON", + "-DRCUTILS_NO_THREAD_SUPPORT=ON", + "-DRCUTILS_NO_64_ATOMIC=ON", + "-DRCUTILS_AVOID_DYNAMIC_ALLOCATION=ON" + ] + }, + "microxrcedds_client": { + "cmake-args": [ + "-DUCLIENT_PIC=OFF", + "-DUCLIENT_PROFILE_UDP=OFF", + "-DUCLIENT_PROFILE_TCP=OFF", + "-DUCLIENT_PROFILE_DISCOVERY=OFF", + "-DUCLIENT_PROFILE_SERIAL=OFF", + "-UCLIENT_PROFILE_STREAM_FRAMING=ON", + "-DUCLIENT_PROFILE_CUSTOM_TRANSPORT=ON" + ] + }, + "rmw_microxrcedds": { + "cmake-args": [ + "-DRMW_UXRCE_MAX_NODES=1", + "-DRMW_UXRCE_MAX_PUBLISHERS=5", + "-DRMW_UXRCE_MAX_SUBSCRIPTIONS=5", + "-DRMW_UXRCE_MAX_SERVICES=1", + "-DRMW_UXRCE_MAX_CLIENTS=1", + "-DRMW_UXRCE_MAX_HISTORY=4", + "-DRMW_UXRCE_TRANSPORT=custom" + ] + } + } +} ``` -Also, include the dependency in `package.xml`: - -```xml -... -rosidl_default_generators -rosidl_default_runtime -rosidl_interface_packages -geometry_msgs -... -``` +## Building the custom library -The message definition in `msg/MyCustomMessage.msg` can now include types from the `geometry_msgs` package: +Once you have both files ready, just run the build step in the micro-ROS build system: +```bash +ros2 run micro_ros_setup build_firmware.sh $(pwd)/my_custom_toolchain.cmake $(pwd)/my_custom_colcon.meta ``` -... -int64 int64_test -uint64 uint64_test -geometry_msgs/Point32 point32_test -``` - -And finally, in your code you can access this new member of your custom type: +Once the build finishes you will have a precompiled static library with all the micro-ROS functionality in `firmware/build/libmicroros.a` and you will have all the required headers for your application in `firmware/include`. -```c -#include - -... - -my_custom_message__msg__MyCustomMessage msg; - -msg.byte_test = 3; -msg.uint32_test = 42; - -msg.point32_test.x = 1.23; -msg.point32_test.y = 2.31; -msg.point32_test.z = 3.12; - -... -``` - -Note that in order for the micro_ros_agent to register these new types, the package with the custom types you've created above, should also be cloned to the host workspace, e.g. `~/uros_ws/src`, and compiled there as well before running the agent. +Just use them to link against in your development tools, and remember **if you are using a commercially available board we are accepting micro-ROS ports from the community**. \ No newline at end of file From fbed10c401eb178a312755f2b2b8c8f493030c07 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Wed, 10 Feb 2021 11:53:12 +0100 Subject: [PATCH 3/5] Update --- _docs/tutorials/advanced/create_custom_static_library/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_docs/tutorials/advanced/create_custom_static_library/index.md b/_docs/tutorials/advanced/create_custom_static_library/index.md index 0399db7a..a15ee439 100644 --- a/_docs/tutorials/advanced/create_custom_static_library/index.md +++ b/_docs/tutorials/advanced/create_custom_static_library/index.md @@ -3,6 +3,8 @@ title: Creating custom static micro-ROS library permalink: /docs/tutorials/advanced/create_custom_static_library/ --- +This tutorial aims at providing step-by-step guidance for those users interested in compiling micro-ROS as a standalone library in order to integrate it in custom development tools. + This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../first_application_rtos/) for instructions about how to create a micro-ROS environment for embedded platforms. Once your micro-ROS workspace is created and the `micro_ros_setup` tool is installed, we are going to prepare the micro-ROS environment: From 1630654efa8db4adf9957c537b2e96dbf666b2e3 Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Wed, 10 Feb 2021 11:56:12 +0100 Subject: [PATCH 4/5] Fix CI --- _docs/tutorials/advanced/create_custom_static_library/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_static_library/index.md b/_docs/tutorials/advanced/create_custom_static_library/index.md index a15ee439..87dda843 100644 --- a/_docs/tutorials/advanced/create_custom_static_library/index.md +++ b/_docs/tutorials/advanced/create_custom_static_library/index.md @@ -5,7 +5,7 @@ permalink: /docs/tutorials/advanced/create_custom_static_library/ This tutorial aims at providing step-by-step guidance for those users interested in compiling micro-ROS as a standalone library in order to integrate it in custom development tools. -This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../first_application_rtos/) for instructions about how to create a micro-ROS environment for embedded platforms. +This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions about how to create a micro-ROS environment for embedded platforms. Once your micro-ROS workspace is created and the `micro_ros_setup` tool is installed, we are going to prepare the micro-ROS environment: From 42b0e14a3cc8685b0bb7e646ad0f897041fd83fe Mon Sep 17 00:00:00 2001 From: Pablo Garrido Date: Wed, 10 Feb 2021 11:56:49 +0100 Subject: [PATCH 5/5] Address changes --- _docs/tutorials/advanced/create_custom_static_library/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/tutorials/advanced/create_custom_static_library/index.md b/_docs/tutorials/advanced/create_custom_static_library/index.md index 87dda843..d3ee3cbe 100644 --- a/_docs/tutorials/advanced/create_custom_static_library/index.md +++ b/_docs/tutorials/advanced/create_custom_static_library/index.md @@ -5,7 +5,7 @@ permalink: /docs/tutorials/advanced/create_custom_static_library/ This tutorial aims at providing step-by-step guidance for those users interested in compiling micro-ROS as a standalone library in order to integrate it in custom development tools. -This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions about how to create a micro-ROS environment for embedded platforms. +This tutorial starts in a previously created micro-ROS environment. Check the first steps of [**First micro-ROS application on an RTOS**](../../core/first_application_rtos/) for instructions on how to create a micro-ROS environment for embedded platforms. Once your micro-ROS workspace is created and the `micro_ros_setup` tool is installed, we are going to prepare the micro-ROS environment: