From 266e4e0c712bad948bd02b5bed6a6ac387861c6b Mon Sep 17 00:00:00 2001 From: Antonio cuadros Date: Wed, 5 May 2021 07:44:20 +0200 Subject: [PATCH 1/4] Add API reference tab --- _data/docs.yml | 6 + _docs/api/overview/index.md | 16 + _docs/api/rclc/index.md | 6 + _docs/api/rmw/index.md | 6 + _includes/docs_nav.html | 3 + _includes/rmw_doc/Modules/group__rmw.md | 285 ++++++++++++++++ _includes/rmw_doc/index_groups.md | 10 + _includes/topnav.html | 1 + utils/doxy_config | 56 ++++ utils/doxy_templates/breadcrumbs.tmpl | 6 + .../doxy_templates/class_members_details.tmpl | 104 ++++++ .../class_members_inherited_tables.tmpl | 303 ++++++++++++++++++ .../doxy_templates/class_members_tables.tmpl | 285 ++++++++++++++++ utils/doxy_templates/details.tmpl | 189 +++++++++++ utils/doxy_templates/footer.tmpl | 1 + utils/doxy_templates/header.tmpl | 5 + utils/doxy_templates/index.tmpl | 10 + utils/doxy_templates/index_classes.tmpl | 5 + utils/doxy_templates/index_examples.tmpl | 5 + utils/doxy_templates/index_files.tmpl | 5 + utils/doxy_templates/index_groups.tmpl | 5 + utils/doxy_templates/index_namespaces.tmpl | 5 + utils/doxy_templates/index_pages.tmpl | 5 + utils/doxy_templates/kind_class.tmpl | 40 +++ utils/doxy_templates/kind_example.tmpl | 5 + utils/doxy_templates/kind_file.tmpl | 22 ++ utils/doxy_templates/kind_group.tmpl | 17 + utils/doxy_templates/kind_nonclass.tmpl | 17 + utils/doxy_templates/kind_page.tmpl | 5 + utils/doxy_templates/member_details.tmpl | 86 +++++ utils/doxy_templates/meta.tmpl | 0 .../nonclass_members_details.tmpl | 24 ++ .../nonclass_members_tables.tmpl | 147 +++++++++ 33 files changed, 1685 insertions(+) create mode 100644 _docs/api/overview/index.md create mode 100644 _docs/api/rclc/index.md create mode 100644 _docs/api/rmw/index.md create mode 100644 _includes/rmw_doc/Modules/group__rmw.md create mode 100644 _includes/rmw_doc/index_groups.md create mode 100644 utils/doxy_config create mode 100644 utils/doxy_templates/breadcrumbs.tmpl create mode 100644 utils/doxy_templates/class_members_details.tmpl create mode 100644 utils/doxy_templates/class_members_inherited_tables.tmpl create mode 100644 utils/doxy_templates/class_members_tables.tmpl create mode 100644 utils/doxy_templates/details.tmpl create mode 100644 utils/doxy_templates/footer.tmpl create mode 100644 utils/doxy_templates/header.tmpl create mode 100644 utils/doxy_templates/index.tmpl create mode 100644 utils/doxy_templates/index_classes.tmpl create mode 100644 utils/doxy_templates/index_examples.tmpl create mode 100644 utils/doxy_templates/index_files.tmpl create mode 100644 utils/doxy_templates/index_groups.tmpl create mode 100644 utils/doxy_templates/index_namespaces.tmpl create mode 100644 utils/doxy_templates/index_pages.tmpl create mode 100644 utils/doxy_templates/kind_class.tmpl create mode 100644 utils/doxy_templates/kind_example.tmpl create mode 100644 utils/doxy_templates/kind_file.tmpl create mode 100644 utils/doxy_templates/kind_group.tmpl create mode 100644 utils/doxy_templates/kind_nonclass.tmpl create mode 100644 utils/doxy_templates/kind_page.tmpl create mode 100644 utils/doxy_templates/member_details.tmpl create mode 100644 utils/doxy_templates/meta.tmpl create mode 100644 utils/doxy_templates/nonclass_members_details.tmpl create mode 100644 utils/doxy_templates/nonclass_members_tables.tmpl diff --git a/_data/docs.yml b/_data/docs.yml index cc8fd177..0f04dc25 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -83,3 +83,9 @@ - tutorials/demos/thumper_demo - tutorials/demos/combined_demos - tutorials/demos/moveit2_demo + +- title: API reference + docs: + - api/overview + - api/rmw + - api/rclc diff --git a/_docs/api/overview/index.md b/_docs/api/overview/index.md new file mode 100644 index 00000000..9a13b02f --- /dev/null +++ b/_docs/api/overview/index.md @@ -0,0 +1,16 @@ +--- +title: Overview +permalink: /docs/api/overview/ +redirect_from: + - /docs/api/ +--- + +TODO + +* [**RMW Micro XRCE-DDS**](../rmw/) + + TODO + +* [**RCLC**](../rclc/) + + TODO \ No newline at end of file diff --git a/_docs/api/rclc/index.md b/_docs/api/rclc/index.md new file mode 100644 index 00000000..0495cfc5 --- /dev/null +++ b/_docs/api/rclc/index.md @@ -0,0 +1,6 @@ +--- +title: RCLC +permalink: /docs/api/rclc/ +--- + +TODO \ No newline at end of file diff --git a/_docs/api/rmw/index.md b/_docs/api/rmw/index.md new file mode 100644 index 00000000..8bab3698 --- /dev/null +++ b/_docs/api/rmw/index.md @@ -0,0 +1,6 @@ +--- +title: RMW +permalink: /docs/api/rmw/ +--- + +{% include rmw_doc/Modules/group__rmw.md %} \ No newline at end of file diff --git a/_includes/docs_nav.html b/_includes/docs_nav.html index 284e5fb2..c4677341 100644 --- a/_includes/docs_nav.html +++ b/_includes/docs_nav.html @@ -28,6 +28,9 @@ {% if page.path contains "_docs/tutorials" and section.title == "Demos" %} {% assign should_show_this_menu = true %} {% endif %} + {% if page.path contains "_docs/api" and section.title == "API reference" %} + {% assign should_show_this_menu = true %} + {% endif %} {% if should_show_this_menu == true %}
diff --git a/_includes/rmw_doc/Modules/group__rmw.md b/_includes/rmw_doc/Modules/group__rmw.md new file mode 100644 index 00000000..4756d291 --- /dev/null +++ b/_includes/rmw_doc/Modules/group__rmw.md @@ -0,0 +1,285 @@ +# micro-ROS RMW API + +TODO. + +## Functions + +| | Name | +| -------------- | -------------- | +| void | **[rmw_uros_set_continous_serialization_callbacks](#function-rmw_uros_set_continous_serialization_callbacks)**(rmw_publisher_t * publisher, rmw_uros_continous_serialization_size size_cb, rmw_uros_continous_serialization serialization_cb)
Sets the callback functions for continous serialization for a publisher. | +| rmw_ret_t | **[rmw_uros_set_custom_transport](#function-rmw_uros_set_custom_transport)**(bool framing, void * args, open_custom_func open_cb, close_custom_func close_cb, write_custom_func write_cb, read_custom_func read_cb)
Check if micro-ROS Agent answers to micro-ROS client. | +| rmw_ret_t | **[rmw_uros_discover_agent](#function-rmw_uros_discover_agent)**(rmw_init_options_t * rmw_options)
Fills rmw implementation-specific options with the autodicovered address of an micro-ROS Agent. | +| rmw_ret_t | **[rmw_uros_init_options](#function-rmw_uros_init_options)**(int argc, const char *const argv[], rmw_init_options_t * rmw_options)
Parses command line args and fills rmw implementation-specific options. | +| rmw_ret_t | **[rmw_uros_options_set_serial_device](#function-rmw_uros_options_set_serial_device)**(const char * dev, rmw_init_options_t * rmw_options)
Fills rmw implementation-specific options with the given parameters. | +| rmw_ret_t | **[rmw_uros_options_set_udp_address](#function-rmw_uros_options_set_udp_address)**(const char * ip, const char * port, rmw_init_options_t * rmw_options)
Fills rmw implementation-specific options with the given parameters. | +| rmw_ret_t | **[rmw_uros_options_set_client_key](#function-rmw_uros_options_set_client_key)**(uint32_t client_key, rmw_init_options_t * rmw_options)
Fills rmw implementation-specific options with the given parameters. | +| rmw_ret_t | **[rmw_uros_ping_agent](#function-rmw_uros_ping_agent)**(const int timeout_ms, const uint8_t attempts)
Check if micro-ROS Agent is up and running. | +| bool | **[rmw_uros_epoch_synchronized](#function-rmw_uros_epoch_synchronized)**()
Returns the time synchronization state of the epoch time. | +| int64_t | **[rmw_uros_epoch_millis](#function-rmw_uros_epoch_millis)**()
Returns the epoch time in milliseconds taking into account the offset computed during the time synchronization. | +| int64_t | **[rmw_uros_epoch_nanos](#function-rmw_uros_epoch_nanos)**()
Returns the epoch time in nanoseconds taking into account the offset computed during the time synchronization. | +| rmw_ret_t | **[rmw_uros_sync_session](#function-rmw_uros_sync_session)**(const int timeout_ms)
Synchronizes the session time using the NTP protocol. | + + +## Functions Documentation + +### function rmw_uros_set_continous_serialization_callbacks + +```cpp +void rmw_uros_set_continous_serialization_callbacks( + rmw_publisher_t * publisher, + rmw_uros_continous_serialization_size size_cb, + rmw_uros_continous_serialization serialization_cb +) +``` + +Sets the callback functions for continous serialization for a publisher. + +**Parameters**: + + * **publisher** publisher where continous serialization is being configured + * **size_cb** callback that should modify the total serialization size + * **serialization_cb** callback that should serialize the user part of the message + + +### function rmw_uros_set_custom_transport + +```cpp +rmw_ret_t rmw_uros_set_custom_transport( + bool framing, + void * args, + open_custom_func open_cb, + close_custom_func close_cb, + write_custom_func write_cb, + read_custom_func read_cb +) +``` + +Check if micro-ROS Agent answers to micro-ROS client. + +**Parameters**: + + * **framing** Enable XRCE framing. + * **args** Arguments for open function. + * **open_cb** Open transport callback. + * **close_cb** Close transport callback. + * **write_cb** Write transport callback. + * **read_cb** Read transport callback. + + +**Return**: + + * RMW_RET_OK If correct. + * RMW_RET_ERROR If invalid. + + +### function rmw_uros_discover_agent + +```cpp +rmw_ret_t rmw_uros_discover_agent( + rmw_init_options_t * rmw_options +) +``` + +Fills rmw implementation-specific options with the autodicovered address of an micro-ROS Agent. + +**Parameters**: + + * **rmw_options** Updated options with rmw specifics. + + +**Return**: + + * RMW_RET_OK If arguments were valid and set in rmw_init_options. + * RMW_RET_TIMEOUT If micro-ROS agent autodiscovery is timeout. + * RMW_RET_INVALID_ARGUMENT If rmw_init_options is not valid or unexpected arguments. + + +### function rmw_uros_init_options + +```cpp +rmw_ret_t rmw_uros_init_options( + int argc, + const char *const argv[], + rmw_init_options_t * rmw_options +) +``` + +Parses command line args and fills rmw implementation-specific options. + +**Parameters**: + + * **argc** Number of arguments. + * **argv** Arguments. + * **rmw_options** Updated options with rmw specifics. + + +**Return**: + + * RMW_RET_OK If arguments were valid and set in rmw_init_options. + * RMW_RET_INVALID_ARGUMENT If rmw_init_options is not valid or unexpected arguments. + + +`rmw_init_options allocator` is used to allocate the specific rmw options. + + +### function rmw_uros_options_set_serial_device + +```cpp +rmw_ret_t rmw_uros_options_set_serial_device( + const char * dev, + rmw_init_options_t * rmw_options +) +``` + +Fills rmw implementation-specific options with the given parameters. + +**Parameters**: + + * **dev** Serial device. + * **rmw_options** Updated options with rmw specifics. + + +**Return**: + + * RMW_RET_OK If arguments were valid and set in rmw_init_options. + * RMW_RET_INVALID_ARGUMENT If rmw_init_options is not valid or unexpected arguments. + + +### function rmw_uros_options_set_udp_address + +```cpp +rmw_ret_t rmw_uros_options_set_udp_address( + const char * ip, + const char * port, + rmw_init_options_t * rmw_options +) +``` + +Fills rmw implementation-specific options with the given parameters. + +**Parameters**: + + * **ip** Agent IP address. + * **port** Agent UDP port. + * **rmw_options** Updated options with rmw specifics. + + +**Return**: + + * RMW_RET_OK If arguments were valid and set in rmw_init_options. + * RMW_RET_INVALID_ARGUMENT If rmw_init_options is not valid or unexpected arguments. + + +### function rmw_uros_options_set_client_key + +```cpp +rmw_ret_t rmw_uros_options_set_client_key( + uint32_t client_key, + rmw_init_options_t * rmw_options +) +``` + +Fills rmw implementation-specific options with the given parameters. + +**Parameters**: + + * **client_key** MicroXRCE-DDS client key. + * **rmw_options** Updated options with rmw specifics. + + +**Return**: + + * RMW_RET_OK If arguments were valid and set in rmw_init_options. + * RMW_RET_INVALID_ARGUMENT If rmw_init_options is not valid or unexpected arguments. + + +### function rmw_uros_ping_agent + +```cpp +rmw_ret_t rmw_uros_ping_agent( + const int timeout_ms, + const uint8_t attempts +) +``` + +Check if micro-ROS Agent is up and running. + +**Parameters**: + + * **timeout_ms** Timeout in ms (per attempt). + * **attempts** Number of tries before considering the ping as failed. + + +**Return**: + + * RMW_RET_OK If micro-ROS Agent is available. + * RMW_RET_ERROR If micro-ROS Agent is not available. + + +This function can be called even when the micro-ROS context has not yet been initialized by the application logics. + + +### function rmw_uros_epoch_synchronized + +```cpp +bool rmw_uros_epoch_synchronized() +``` + +Returns the time synchronization state of the epoch time. + +**Return**: true if last time synchronization succeded and false otherwise + +### function rmw_uros_epoch_millis + +```cpp +int64_t rmw_uros_epoch_millis() +``` + +Returns the epoch time in milliseconds taking into account the offset computed during the time synchronization. + +**Return**: + + * epoch time in milliseconds. + * 0 if session is not initialized. + + +### function rmw_uros_epoch_nanos + +```cpp +int64_t rmw_uros_epoch_nanos() +``` + +Returns the epoch time in nanoseconds taking into account the offset computed during the time synchronization. + +**Return**: + + * epoch time in nanoseconds. + * 0 if session is not initialized. + + +### function rmw_uros_sync_session + +```cpp +rmw_ret_t rmw_uros_sync_session( + const int timeout_ms +) +``` + +Synchronizes the session time using the NTP protocol. + +**Parameters**: + + * **timeout_ms** The waiting time in milliseconds. + + +**Return**: + + * RMW_RET_OK when success. + * RMW_RET_ERROR If no session is running or the synchronization fails. + + + + + + +------------------------------- \ No newline at end of file diff --git a/_includes/rmw_doc/index_groups.md b/_includes/rmw_doc/index_groups.md new file mode 100644 index 00000000..93ebc176 --- /dev/null +++ b/_includes/rmw_doc/index_groups.md @@ -0,0 +1,10 @@ +# Modules + + + + +* **group [micro-ROS RMW API](Modules/group__rmw.md)**
TODO. + + + +------------------------------- diff --git a/_includes/topnav.html b/_includes/topnav.html index cbbb96ec..ff2231db 100644 --- a/_includes/topnav.html +++ b/_includes/topnav.html @@ -16,6 +16,7 @@
  • Overview
  • Concepts
  • Tutorials
  • +
  • API reference
  • Blog