6.3.8. micro-ROS Utilities¶

Table of Contents

micro-ROS String Utilities
micro-ROS Types Utilities

micro_ros_utilities is a package that provides a set of tools for easing the use of micro-ROS on different platforms. Currently, it has two APIs:

micro-ROS type utils.
micro-ROS rosidl_runtime_c__String wrapper that reduces dynamic memory operations.

Note

A full example can be found on how to use this API can be found here

6.3.8.1. micro-ROS String Utilities¶

This API helps developers to manage strings in micro-ROS by means of providing a set of methods that allow initialization, destruction, set, and other common operations.

Warning

It is important to note that, unlike in ROS 2 rclcpp, in micro-ROS rclc memory in types is not initialized by default. It is required that the user initializes the memory for each type that is used in any micro-ROS procedure.

6.3.8.1.1. micro_ros_string_utilities_init¶

Create a rosidl_runtime_c__String from a char pointer.

const char * str = "Hello World";
rosidl_runtime_c__String ros_str = micro_ros_string_utilities_init(str);

Operation	Action
Allocate	Yes, it does not take ownership of `char*`
Reallocate	No
Free	No

6.3.8.1.2. micro_ros_string_utilities_init_with_size¶

Create a rosidl_runtime_c__String from a size.

size_t size = 10;
rosidl_runtime_c__String ros_str = micro_ros_string_utilities_init_with_size(size);

Operation	Action
Allocate	Yes
Reallocate	No
Free	No

6.3.8.1.3. micro_ros_string_utilities_set¶

Create a rosidl_runtime_c__String from a char pointer reallocating an actual rosidl_runtime_c__String.

const char * str = "Hello World";
size_t size = strlen(str) + 1;  // Add null terminator

rosidl_runtime_c__String ros_str = micro_ros_string_utilities_init_with_size(size);
ros_str = micro_ros_string_utilities_set(ros_str, str);

Operation	Action
Allocate	No
Reallocate	Reallocates input `rosidl_runtime_c__String`, does not take ownership of `char*`
Free	No

6.3.8.1.4. micro_ros_string_utilities_get_c_str¶

Returns the char pointer to the rosidl_runtime_c__String data.

const char * str = "Hello World";
rosidl_runtime_c__String ros_str = micro_ros_string_utilities_init(str);

char * ptr_str = micro_ros_string_utilities_get_c_str(ros_str);

6.3.8.1.5. micro_ros_string_utilities_append¶

Appends a char pointer to the end of a rosidl_runtime_c__String.

const char * str = "Hello World";
rosidl_runtime_c__String ros_str = micro_ros_string_utilities_init(str);

ros_str = micro_ros_string_utilities_append(ros_str, "!");

Operation	Action
Allocate	No
Reallocate	Yes if input `rosidl_runtime_c__String` is not big enough
Free	No

6.3.8.1.6. micro_ros_string_utilities_remove_tail_chars¶

Removes characters from the end of a rosidl_runtime_c__String.

const char * str = "Hello World";
rosidl_runtime_c__String ros_str = micro_ros_string_utilities_init(str);

ros_str = micro_ros_string_utilities_remove_tail_chars(ros_str, 5);

Operation	Action
Allocate	No
Reallocate	No
Free	No

6.3.8.1.7. micro_ros_string_utilities_destroy¶

Destroys a rosidl_runtime_c__String.

const char * str = "Hello World";
rosidl_runtime_c__String ros_str = micro_ros_string_utilities_init(str);

micro_ros_string_utilities_destroy(ros_str);

Operation	Action
Allocate	No
Reallocate	No
Free	Yes

6.3.8.2. micro-ROS Types Utilities¶

This API helps developers to manage ROS types in micro-ROS. It handles the types structures recursively in order to initialize each member with the required memory size.

6.3.8.2.1. micro_ros_utilities_memory_conf_t¶

micro_ros_utilites provides a functionality to instantiate sequences and strings of fixed sizes.

Memory can be allocated in two ways:

statically: in an user provided buffer.
dynamically: using ROS 2 allocators

Memory allocation can be configured using configuration structure that has the following members:

max_string_capacity: Maximum string capacity to use for message fields.
max_ros2_type_sequence_capacity: Maximum capacity to use for sequence type msg fields (ie: unbounded arrays and lists) which contain ROS 2 msg types.
max_basic_type_sequence_capacity: Maximum capacity to use for sequence type msg fields (ie: unbounded arrays and lists) which contain basic types (ie: primitive field types).

static micro_ros_utilities_memory_conf_t conf = {0};
// OPTIONALLY this struct can configure the default size of strings, basic sequences and composed sequences
conf.max_string_capacity = 50;
conf.max_ros2_type_sequence_capacity = 5;
conf.max_basic_type_sequence_capacity = 5;

All message members will follow this configuration, unless they have a custom rule assigned to them.

6.3.8.2.2. micro_ros_utilities_type_info¶

Returns a rosidl_runtime_c__String with the type introspection data.

#include <control_msgs/msg/joint_jog.h>

rosidl_runtime_c__String ros_str = micro_ros_utilities_type_info(ROSIDL_GET_MSG_TYPE_SUPPORT(control_msgs, msg, JointJog));

6.3.8.2.3. micro_ros_utilities_get_static_size¶

Returns the static memory size that will be used for a type with a given memory configuration.

#include <control_msgs/msg/joint_jog.h>

static micro_ros_utilities_memory_conf_t conf = {0};

// OPTIONALLY this struct can configure the default size of strings, basic sequences and composed sequences
conf.max_string_capacity = 50;
conf.max_ros2_type_sequence_capacity = 5;
conf.max_basic_type_sequence_capacity = 5;

control_msgs__msg__JointJog msg;
rosidl_runtime_c__String ros_str = micro_ros_utilities_get_static_size(ROSIDL_GET_MSG_TYPE_SUPPORT(control_msgs, msg, JointJog) conf);

6.3.8.2.4. micro_ros_utilities_create_message_memory¶

Allocates dynamic memory for a message.

#include <control_msgs/msg/joint_jog.h>

static micro_ros_utilities_memory_conf_t conf = {0};

// OPTIONALLY this struct can configure the default size of strings, basic sequences and composed sequences
conf.max_string_capacity = 50;
conf.max_ros2_type_sequence_capacity = 5;
conf.max_basic_type_sequence_capacity = 5;

control_msgs__msg__JointJog msg;
bool success = micro_ros_utilities_create_message_memory(
    ROSIDL_GET_MSG_TYPE_SUPPORT(control_msgs, msg, JointJog),
    &msg,
    conf
);

6.3.8.2.5. micro_ros_utilities_create_static_message_memory¶

Allocates memory for a message in a user-provided buffer.

#include <control_msgs/msg/joint_jog.h>

uint8_t my_buffer[1000];
static micro_ros_utilities_memory_conf_t conf = {0};

// OPTIONALLY this struct can configure the default size of strings, basic sequences and composed sequences
conf.max_string_capacity = 50;
conf.max_ros2_type_sequence_capacity = 5;
conf.max_basic_type_sequence_capacity = 5;

control_msgs__msg__JointJog msg;
bool success = micro_ros_utilities_create_static_message_memory(
    ROSIDL_GET_MSG_TYPE_SUPPORT(control_msgs, msg, JointJog),
    &msg_static,
    conf,
    my_buffer,
    sizeof(my_buffer)
);

6.3.8.2.6. micro_ros_utilities_destroy_message_memory¶

Deallocates the dynamic memory of a message.

#include <control_msgs/msg/joint_jog.h>

static micro_ros_utilities_memory_conf_t conf = {0};

// OPTIONALLY this struct can configure the default size of strings, basic sequences and composed sequences
conf.max_string_capacity = 50;
conf.max_ros2_type_sequence_capacity = 5;
conf.max_basic_type_sequence_capacity = 5;

control_msgs__msg__JointJog msg;
bool success = micro_ros_utilities_create_message_memory(
    ROSIDL_GET_MSG_TYPE_SUPPORT(control_msgs, msg, JointJog),
    &msg,
    conf
);

success &= micro_ros_utilities_destroy_message_memory(
    ROSIDL_GET_MSG_TYPE_SUPPORT(control_msgs, msg, JointJog),
    &msg,
    conf
);