micro-ROS · pablogs9 · May 5, 2021 · May 5, 2021 · May 5, 2021 · May 5, 2021
diff --git a/.github/workflows/generate_api_reference.yml 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
diff --git 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
@@ -0,0 +1,9 @@
+---
+title: Overview
+permalink: /docs/api/overview/
+redirect_from:
+  - /docs/api/
+---
+
+* [**RMW Micro XRCE-DDS**](../rmw/)
+* [**RCLC**](../rclc/)
diff --git a/_docs/api/rclc/index.md b/_docs/api/rclc/index.md
@@ -0,0 +1,6 @@
+---
+title: RCLC
+permalink: /docs/api/rclc/
+---
+
+TODO
diff --git a/_docs/api/rmw/index.md b/_docs/api/rmw/index.md
@@ -0,0 +1,6 @@
+---
+title: RMW
+permalink: /docs/api/rmw/
+---
+
+{% include rmw_doc/Modules/group__rmw.md %}
diff --git 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 %}
   <div class="panel panel-default">
     <div class="panel-heading">

diff --git a/_includes/rmw_doc/Modules/group__rmw.md 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)<br>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)<br>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)<br>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)<br>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)<br>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)<br>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)<br>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)<br>Check if micro-ROS Agent is up and running.                                                                                                                                                                     |
+| bool      | **[rmw_uros_epoch_synchronized](#function-rmw_uros_epoch_synchronized)**()<br>Returns the time synchronization state of the epoch time.                                                                                                                                                                                   |
+| int64_t   | **[rmw_uros_epoch_millis](#function-rmw_uros_epoch_millis)**()<br>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)**()<br>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)<br>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. 
+
+
+
+
+
+
+-------------------------------
diff --git a/_includes/rmw_doc/index_groups.md b/_includes/rmw_doc/index_groups.md
@@ -0,0 +1,10 @@
+# Modules
+
+
+
+
+* **group [micro-ROS RMW API](Modules/group__rmw.md)** <br>TODO. 
+
+
+
+-------------------------------
diff --git a/_includes/topnav.html b/_includes/topnav.html
@@ -16,6 +16,7 @@
                 <li {% if page.path contains '_docs/overview' %} class="active" {% endif %}><a href="{{ "/docs/overview/" | prepend: site.baseurl }}">Overview</a></li>
                 <li {% if page.path contains '_docs/concepts' %} class="active" {% endif %}><a href="{{ "/docs/concepts/" | prepend: site.baseurl }}">Concepts</a></li>
                 <li {% if page.path contains '_docs/tutorials' %} class="active" {% endif %}><a href="{{ "/docs/tutorials/" | prepend: site.baseurl }}">Tutorials</a></li>
+                <li {% if page.path contains '_docs/api' %} class="active" {% endif %}><a href="{{ "/docs/api/" | prepend: site.baseurl }}">API</a></li>
                 <li {% if page.sectionid=='posts' %} class="active" {% endif %}><a href="{{ site.posts.first.url | prepend: site.baseurl }}">Blog</a></li>
             </ul>
             <ul class="nav navbar-nav navbar-right">