diff --git a/.github/workflows/generate_api_reference.yml b/.github/workflows/generate_api_reference.yml new file mode 100644 index 00000000..d6a72022 --- /dev/null +++ b/.github/workflows/generate_api_reference.yml @@ -0,0 +1,47 @@ +name: API reference generator +on: + workflow_dispatch: + inputs: + name: + description: "Manual trigger" + schedule: + - cron: '0 6 * * *' + +jobs: + generate_api_reference: + runs-on: ubuntu-latest + container: ros:foxy + steps: + - uses: actions/checkout@v2 + - name: Get date + id: date + run: echo "::set-output name=date::$(date +'%d-%m-%Y %H:%M')" + - name: Update libraries + run: | + apt update + apt install -y doxygen wget git unzip cmake + + pushd / + wget https://github.com/matusnovak/doxybook2/releases/download/v1.3.3/doxybook2-linux-amd64-v1.3.3.zip + unzip doxybook2-linux-amd64-v1.3.3.zip -d doxybook2 + + mkdir -p ros2_ws/src; cd ros2_ws + git clone -b foxy https://github.com/eProsima/Micro-CDR src/Micro-CDR + git clone -b foxy https://github.com/eProsima/Micro-XRCE-DDS-Client src/Micro-XRCE-DDS-Client + git clone -b foxy https://github.com/micro-ROS/rosidl_typesupport_microxrcedds src/rosidl_typesupport_microxrcedds + git clone -b foxy https://github.com/micro-ROS/rmw-microxrcedds src/rmw-microxrcedds + + source /opt/ros/$ROS_DISTRO/setup.bash + colcon build --packages-up-to rmw_microxrcedds --cmake-args -DBUILD_DOCUMENTATION=ON + popd + + /doxybook2/bin/doxybook2 --input /ros2_ws/build/rmw_microxrcedds/doc/xml --output _includes/rmw_doc -c utils/doxy_config -t utils/doxy_templates + - name: Create Pull Request + uses: peter-evans/create-pull-request@v3 + with: + commit-message: micro-ROS API reference auto-update ${{ steps.date.outputs.date }} + title: micro-ROS API reference auto-update ${{ steps.date.outputs.date }} + body: This PR is autogenerated and updates the micro-ROS API reference. Close and reopen to trigger CI. + branch: autoupdate_micro_ros_api_reference + delete-branch: true + base: master \ No newline at end of file diff --git a/_data/docs.yml b/_data/docs.yml index cc8fd177..62b90f4e 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 + 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..bb6ae483 --- /dev/null +++ b/_docs/api/overview/index.md @@ -0,0 +1,9 @@ +--- +title: Overview +permalink: /docs/api/overview/ +redirect_from: + - /docs/api/ +--- + +* [**RMW Micro XRCE-DDS**](../rmw/) +* [**RCLC**](../rclc/) \ 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..3b7e2ac8 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" %} + {% 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..e6b46e94 --- /dev/null +++ b/_includes/rmw_doc/Modules/group__rmw.md @@ -0,0 +1,283 @@ +# micro-ROS RMW API + +## 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..1ce5ebcc 100644 --- a/_includes/topnav.html +++ b/_includes/topnav.html @@ -16,6 +16,7 @@
  • Overview
  • Concepts
  • Tutorials
    • +
  • API
  • Blog