AimRT · AimRT · Nov 21, 2024 · Nov 7, 2024 · Nov 7, 2024 · Nov 8, 2024
diff --git a/.gitignore b/.gitignore
@@ -23,6 +23,7 @@ dist/
 __pycache__/
 *_pb2.py
 *_pb2_grpc.py
+*_aimrt_rpc_ros2.py
 log/
 tmp/
 

diff --git a/document/sphinx-cn/release_notes/v0_9_0.md b/document/sphinx-cn/release_notes/v0_9_0.md
@@ -11,6 +11,7 @@
 - 新增 aimrt_cli trans 命令，用于将 使用 aimrt record_playback 插件录制的 bag 文件转换为 ros2 的 bag 文件；
 - 新增 Echo 插件，用于回显消息；
 - 新增了基于执行器的定时器，方便执行定时任务；
+- aimrt_py channel 和 rpc 支持 ros2 消息类型；
 
 **次要修改**：
 - 缩短了一些 examples 的文件路径长度；

diff --git a/document/sphinx-cn/tutorials/examples/examples_py.md b/document/sphinx-cn/tutorials/examples/examples_py.md
@@ -9,6 +9,8 @@ AimRT 提供了以下 Python 接口使用示例：
   - {{ '[pb_rpc]({}/src/examples/py/pb_rpc)'.format(code_site_root_path_url) }}
   - {{ '[pb_chn_bench]({}/src/examples/py/pb_chn_bench)'.format(code_site_root_path_url) }}
   - {{ '[pb_rpc_bench]({}/src/examples/py/pb_rpc_bench)'.format(code_site_root_path_url) }}
+  - {{ '[ros2_chn]({}/src/examples/py/ros2_chn)'.format(code_site_root_path_url) }}
+  - {{ '[ros2_rpc]({}/src/examples/py/ros2_rpc)'.format(code_site_root_path_url) }}
 
 关于这些示例的说明：
 - 每个示例都有自己独立的 readme 文档，详情请点击示例链接进入后查看；

diff --git a/document/sphinx-cn/tutorials/interface_py/channel.md b/document/sphinx-cn/tutorials/interface_py/channel.md
@@ -7,11 +7,12 @@
 - {{ '[examples_py_pb_chn_publisher_app.py]({}/src/examples/py/pb_chn/examples_py_pb_chn_publisher_app.py)'.format(code_site_root_path_url) }}
 - {{ '[examples_py_pb_chn_subscriber_app.py]({}/src/examples/py/pb_chn/examples_py_pb_chn_subscriber_app.py)'.format(code_site_root_path_url) }}
 
-
-## protobuf 协议
+## 协议
 
 协议用于确定通信各端的消息格式。一般来说，协议都是使用一种与具体的编程语言无关的 IDL ( Interface description language )描述，然后由某种工具转换为各个语言的代码。
 
+### Protobuf
+
 [Protobuf](https://protobuf.dev/)是一种由 Google 开发的、用于序列化结构化数据的轻量级、高效的数据交换格式，是一种广泛使用的 IDL。
 
 当前版本 AimRT Python 只支持 protobuf 协议。在使用 AimRT Python 发送/订阅消息之前，使用者需要先基于 protobuf 协议生成一些 python 的桩代码。
@@ -36,6 +37,32 @@ protoc --python_out=. example.proto
 这将生成`example_pb2.py`文件，包含了根据定义的消息类型生成的 Python 接口，我们的业务代码中需要 import 此文件。
 
 
+### ROS2 Message
+
+ROS2 Message 是一种用于在 ROS2 中进行通信和数据交换的结构化数据格式。在使用时，开发者需要先定义一个 ROS2 Package，在其中定义一个`.msg`文件，比如`example.msg`：
+
+```
+int32   num
+float32 num2
+char    data
+```
+
+然后直接通过 ROS2 提供的 CMake 方法`rosidl_generate_interfaces`，为消息生成 C++ 代码和 CMake Target，例如：
+```cmake
+rosidl_generate_interfaces(
+  example_ros2_msg_gencode
+  "msg/example.msg"
+)
+```
+
+构建之后，还需要设置相应的环境变量，才能在 python 中使用生成的消息类型，在 aimrt 的 build 目录中，执行：
+
+```bash
+source install/share/example_ros2/setup.bash
+```
+
+关于更多生成自定义 ROS2 Message 的详细信息，请参考[ROS2 官方文档](https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Custom-ROS2-Interfaces.html)。
+
 ## ChannelHandle
 
 模块可以通过调用`CoreRef`句柄的`GetChannelHandle()`接口，获取`ChannelHandleRef`句柄，来使用 Channel 功能。其提供的核心接口如下：

diff --git a/document/sphinx-cn/tutorials/interface_py/rpc.md b/document/sphinx-cn/tutorials/interface_py/rpc.md
@@ -6,19 +6,20 @@
 参考示例：
 - {{ '[examples_py_pb_rpc_client_app.py]({}/src/examples/py/pb_rpc/examples_py_pb_rpc_client_app.py)'.format(code_site_root_path_url) }}
 - {{ '[examples_py_pb_rpc_server_app.py]({}/src/examples/py/pb_rpc/examples_py_pb_rpc_server_app.py)'.format(code_site_root_path_url) }}
+- {{ '[examples_py_ros2_rpc_client_app.py]({}/src/examples/py/ros2_rpc/examples_py_ros2_rpc_client_app.py)'.format(code_site_root_path_url) }}
+- {{ '[examples_py_ros2_rpc_server_app.py]({}/src/examples/py/ros2_rpc/examples_py_ros2_rpc_server_app.py)'.format(code_site_root_path_url) }}
 
-## protobuf 协议
+## 协议
 
 
 协议用于确定 RPC 中客户端和服务端的消息格式。一般来说，协议都是使用一种与具体的编程语言无关的 IDL ( Interface description language )描述，然后由某种工具转换为各个语言的代码。对于 RPC 来说，这里需要两个步骤：
 - 参考[Channel](./channel.md)章节中的介绍，开发者需要先利用一些官方的工具为协议文件中的**消息类型**生成指定编程语言中的代码；
 - 开发者需要使用 AimRT 提供的工具，为协议文件中**服务定义**生成指定编程语言中的代码；
 
 
-[Protobuf](https://protobuf.dev/)是一种由 Google 开发的、用于序列化结构化数据的轻量级、高效的数据交换格式，是一种广泛使用的 IDL。它不仅能够描述消息结构，还提供了`service`语句来定义 RPC 服务。
-
-当前版本 AimRT Python 只支持 protobuf 协议。在使用 AimRT Python 发起/处理 RPC 请求之前，使用者需要先基于 protobuf 协议生成一些 python 的桩代码。
+### Protobuf
 
+[Protobuf](https://protobuf.dev/)是一种由 Google 开发的、用于序列化结构化数据的轻量级、高效的数据交换格式，是一种广泛使用的 IDL。它不仅能够描述消息结构，还提供了`service`语句来定义 RPC 服务。
 
 在使用时，开发者需要先定义一个`.proto`文件，在其中定义消息结构和 RPC 服务。例如`rpc.proto`：
 
@@ -57,6 +58,29 @@ protoc --aimrt_rpc_out=. --plugin=protoc-gen-aimrt_rpc=./protoc_plugin_py_gen_ai
 
 这将生成`rpc_aimrt_rpc_pb2.py`文件，包含了根据定义的服务生成的 Python 接口，我们的业务代码中需要 import 此文件。
 
+### ROS2 Srv
+
+ROS2 Srv 是一种用于在 ROS2 中进行 RPC 定义的格式。在使用时，开发者需要先定义一个 ROS2 Package，在其中定义一个`.srv`文件，比如`example.srv`：
+
+```
+byte[]  data
+---
+int64   code
+```
+
+其中，以`---`来分割 Req 和 Rsp 的定义。
+
+aimrt_py 安装时会自动安装一个命令行工具 `aimrt_py-gen-ros2-rpc`，用于根据 ROS2 Srv 文件生成 AimRT Python 的 RPC 桩代码。
+
+```shell
+aimrt_py-gen-ros2-rpc --pkg_name=example_pkg --srv_file=./example.srv --output_path=./
+```
+
+其中 pkg_name 是 ROS2 Package 的名称，srv_file 是 ROS2 Srv 文件的路径，output_path 是生成的桩代码的输出路径。这将生成一个`example_aimrt_rpc_ros2.py`文件，包含了根据定义的服务生成的 Python 接口，我们的业务代码中需要 import 此文件。
+
+需要注意的是，`aimrt_py-gen-ros2-rpc` 只会生成 Req 和 Rsp 的定义，不会生成消息结构部分的代码，消息结构部分代码仍然需要使用者自行生成（即构建 ROS2 Package 并生成消息结构代码, 详情可以参考 [ROS2 官方文档](https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Custom-ROS2-Interfaces.html)）。
+
+
 ## RpcHandle
 
 模块可以通过调用`CoreRef`句柄的`GetRpcHandle()`接口，获取`RpcHandleRef`句柄。一般情况下，开发者不会直接使用`RpcHandleRef`直接提供的接口，而是根据 RPC IDL 文件生成一些桩代码，对`RpcHandleRef`句柄做一些封装，然后在业务代码中使用这些经过封装的接口。
@@ -126,7 +150,7 @@ RpcContext 是 RPC 调用时上下文信息，开发者可以在 RPC 调用时
 
 
 
-以下是一个使用 AimRT Python 进行 RPC Client 调用的示例，通过 Create Module 方式拿到`CoreRef`句柄。如果是基于`Module`模式在`Initialize`方法中拿到`CoreRef`句柄，使用方式也类似：
+以下是一个使用 AimRT Python 基于 protobuf 协议进行 RPC Client 调用的示例，通过 Create Module 方式拿到`CoreRef`句柄。如果是基于`Module`模式在`Initialize`方法中拿到`CoreRef`句柄，使用方式也类似：
 
 ```python
 import aimrt_py
@@ -200,7 +224,7 @@ if __name__ == '__main__':
 - **Step 2**：在`Initialize`阶段调用`RpcHandleRef`的`RegisterService`方法注册 RPC Service；
 
 
-以下是一个使用 AimRT Python 进行 RPC Service 处理的示例，通过 Create Module 方式拿到`CoreRef`句柄。如果是基于`Module`模式在`Initialize`方法中拿到`CoreRef`句柄，使用方式也类似：
+以下是一个使用 AimRT Python 基于 protobuf 协议进行 RPC Service 处理的示例，通过 Create Module 方式拿到`CoreRef`句柄。如果是基于`Module`模式在`Initialize`方法中拿到`CoreRef`句柄，使用方式也类似：
 
 ```python
 import aimrt_py
@@ -281,3 +305,9 @@ def main():
 if __name__ == '__main__':
     main()
 ```
+
+基于 ROS2 Srv 协议的 RPC 调用和处理，除数据类型不同外，其他使用方式与基于 protobuf 协议的 RPC 调用和处理基本一致。
+
+完整示例请参考：
+- {{ '[examples/py/ros2_rpc]({}/src/examples/py/ros2_rpc)'.format(code_site_root_path_url) }}
+- {{ '[examples/py/pb_rpc]({}/src/examples/py/pb_rpc)'.format(code_site_root_path_url) }}
diff --git a/src/examples/py/pb_chn/README.md b/src/examples/py/pb_chn/README.md
@@ -33,7 +33,7 @@
 
 说明：
 - 此示例创建了以下两个模块：
-  - `NormalPublisherPyModule`：会在启动后向配置的 topic 中发布一条 `ExampleEventMsg` 类型的消息，然后结束进程；
+  - `NormalPublisherPyModule`：会在启动后向配置的 topic 中发布若干条 `ExampleEventMsg` 类型的消息，然后结束进程；
   - `NormalSubscriberPyModule`：会订阅配置的 topic 下的 `ExampleEventMsg` 类型的消息；
 - 此示例使用 http 类型的 channel 后端进行通信，请确保相关端口未被占用；
 
@@ -70,7 +70,7 @@
 
 说明：
 - 此示例创建了以下两个模块：
-  - `NormalPublisherPyModule`：会在启动后向配置的 topic 中发布一条 `ExampleEventMsg` 类型的消息，然后结束进程；
+  - `NormalPublisherPyModule`：会在启动后向配置的 topic 中发布若干条 `ExampleEventMsg` 类型的消息，然后结束进程；
   - `NormalSubscriberPyModule`：会订阅配置的 topic 下的 `ExampleEventMsg` 类型的消息；
 - 此示例使用 ros2 类型的 channel 后端进行通信，请确保本地安装有 ROS2 Humble；
 

diff --git a/src/examples/py/pb_chn/examples_py_pb_chn_publisher_app.py b/src/examples/py/pb_chn/examples_py_pb_chn_publisher_app.py
@@ -47,8 +47,9 @@ def main():
     # Sleep for seconds
     time.sleep(1)
 
-    # Publish event
     event_msg = event_pb2.ExampleEventMsg()
+
+    # Publish event
     event_msg.msg = "Publish without ctx or serialization_type"
     event_msg.num = 1
     aimrt_py.Publish(publisher, event_msg)

diff --git a/src/examples/py/ros2_chn/README.md b/src/examples/py/ros2_chn/README.md
@@ -0,0 +1,71 @@
+# ros2 channel examples
+
+
+## ros2 channel http
+
+
+一个基于 ros2 协议与 http 后端的 python channel 示例，演示内容包括：
+- 如何在 python 中使用 ros2 协议作为 channel 传输协议；
+- 如何基于 aimrt_py 创建模块的方式使用 Channel publish 和 subscribe 功能；
+- 如何使用 http 类型的 channel 后端；
+
+
+核心代码：
+- [examples_py_ros2_chn_publisher_app.py](./examples_py_ros2_chn_publisher_app.py)
+- [examples_py_ros2_chn_subscriber_app.py](./examples_py_ros2_chn_subscriber_app.py)
+
+
+配置文件：
+- [examples_py_ros2_chn_http_pub_cfg.yaml](./cfg/examples_py_ros2_chn_http_pub_cfg.yaml)
+- [examples_py_ros2_chn_http_sub_cfg.yaml](./cfg/examples_py_ros2_chn_http_sub_cfg.yaml)
+
+
+
+运行方式（linux）：
+- [安装 `aimrt_py` 包](../../../../document/sphinx-cn/tutorials/quick_start/installation_py.md)；
+- 运行本目录下的[start_examples_py_ros2_chn_http_sub.sh](./start_examples_py_ros2_chn_http_sub.sh)脚本，启动 subscriber；
+- 在新终端里运行本目录下的[start_examples_py_ros2_chn_http_pub.sh](./start_examples_py_ros2_chn_http_pub.sh)脚本，启动 publisher 发布一条消息；
+- 向 subscriber 进程所在终端里键入`ctrl-c`以停止进程；
+
+
+说明：
+- 此示例创建了以下两个模块：
+  - `NormalPublisherPyModule`：会在启动后向配置的 topic 中发布若干条 `ExampleEventMsg` 类型的消息，然后结束进程；
+  - `NormalSubscriberPyModule`：会订阅配置的 topic 下的 `ExampleEventMsg` 类型的消息；
+- 此示例使用 http 类型的 channel 后端进行通信，请确保相关端口未被占用；
+
+
+
+## ros2 channel ros2
+
+一个基于 ros2 协议与 ros2 后端的 python channel 示例，演示内容包括：
+- 如何在 python 中使用 ros2 协议作为 channel 传输协议；
+- 如何基于 aimrt_py 创建模块的方式使用 Channel publish 和 subscribe 功能；
+- 如何使用 ros2 类型的 channel 后端；
+
+
+核心代码：
+- [examples_py_ros2_chn_publisher_app.py](./examples_py_ros2_chn_publisher_app.py)
+- [examples_py_ros2_chn_subscriber_app.py](./examples_py_ros2_chn_subscriber_app.py)
+
+
+配置文件：
+- [examples_py_ros2_chn_ros2_pub_cfg.yaml](./cfg/examples_py_ros2_chn_ros2_pub_cfg.yaml)
+- [examples_py_ros2_chn_ros2_sub_cfg.yaml](./cfg/examples_py_ros2_chn_ros2_sub_cfg.yaml)
+
+
+
+运行方式（linux）：
+- [安装 `aimrt_py` 包](../../../../document/sphinx-cn/tutorials/quick_start/installation_py.md)；
+- 运行本目录下的[start_examples_py_ros2_chn_ros2_sub.sh](./start_examples_py_ros2_chn_ros2_sub.sh)脚本，启动 subscriber；
+- 在新终端里运行本目录下的[start_examples_py_pb_chn_ros2_pub.sh](./start_examples_py_pb_chn_ros2_pub.sh)脚本，启动 publisher 发布一条消息；
+- 向 subscriber 进程所在终端里键入`ctrl-c`以停止进程；
+
+
+说明：
+- 此示例创建了以下两个模块：
+  - `NormalPublisherPyModule`：会在启动后向配置的 topic 中发布若干条 `ExampleEventMsg` 类型的消息，然后结束进程；
+  - `NormalSubscriberPyModule`：会订阅配置的 topic 下的 `ExampleEventMsg` 类型的消息；
+- 此示例使用 ros2 类型的 channel 后端进行通信，请确保本地安装有 ROS2 Humble；
+
+
diff --git a/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_http_pub_cfg.yaml b/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_http_pub_cfg.yaml
@@ -0,0 +1,35 @@
+# Copyright (c) 2024 The AimRT Authors.
+# AimRT is licensed under Mulan PSL v2.
+
+aimrt:
+  plugin:
+    plugins:
+      - name: net_plugin
+        path: ${AIMRT_PLUGIN_DIR}/libaimrt_net_plugin.so
+        options:
+          thread_num: 4
+          http_options:
+            listen_ip: 127.0.0.1
+            listen_port: 50081
+  log:
+    core_lvl: INFO # Trace/Debug/Info/Warn/Error/Fatal/Off
+    default_module_lvl: INFO
+    backends:
+      - type: console
+  channel:
+    backends:
+      - type: http
+        options:
+          pub_topics_options:
+            - topic_name: "(.*)"
+              server_url_list: ["http://127.0.0.1:50080"]
+    pub_topics_options:
+      - topic_name: "(.*)"
+        enable_backends: [http]
+  module:
+    modules:
+      - name: NormalPublisherPyModule
+        log_lvl: INFO
+
+NormalPublisherPyModule:
+  topic_name: test_topic
diff --git a/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_http_sub_cfg.yaml b/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_http_sub_cfg.yaml
@@ -0,0 +1,31 @@
+# Copyright (c) 2024 The AimRT Authors.
+# AimRT is licensed under Mulan PSL v2.
+
+aimrt:
+  plugin:
+    plugins:
+      - name: net_plugin
+        path: ${AIMRT_PLUGIN_DIR}/libaimrt_net_plugin.so
+        options:
+          thread_num: 4
+          http_options:
+            listen_ip: 127.0.0.1
+            listen_port: 50080
+  log:
+    core_lvl: INFO # Trace/Debug/Info/Warn/Error/Fatal/Off
+    default_module_lvl: INFO
+    backends:
+      - type: console
+  channel:
+    backends:
+      - type: http
+    sub_topics_options:
+      - topic_name: "(.*)"
+        enable_backends: [http]
+  module:
+    modules:
+      - name: NormalSubscriberPyModule
+        log_lvl: INFO
+
+NormalSubscriberPyModule:
+  topic_name: test_topic
diff --git a/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_ros2_pub_cfg.yaml b/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_ros2_pub_cfg.yaml
@@ -0,0 +1,30 @@
+# Copyright (c) 2024 The AimRT Authors.
+# AimRT is licensed under Mulan PSL v2.
+
+aimrt:
+  plugin:
+    plugins:
+      - name: ros2_plugin
+        path: ${AIMRT_PLUGIN_DIR}/libaimrt_ros2_plugin.so
+        options:
+          node_name: example_ros2_chn_py_publisher_node
+          executor_type: MultiThreaded # SingleThreaded/StaticSingleThreaded/MultiThreaded
+          executor_thread_num: 2
+  log:
+    core_lvl: INFO # Trace/Debug/Info/Warn/Error/Fatal/Off
+    default_module_lvl: INFO
+    backends:
+      - type: console
+  channel:
+    backends:
+      - type: ros2
+    pub_topics_options:
+      - topic_name: "(.*)"
+        enable_backends: [ros2]
+  module:
+    modules:
+      - name: NormalPublisherPyModule
+        log_lvl: INFO
+
+NormalPublisherPyModule:
+  topic_name: test_topic
diff --git a/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_ros2_sub_cfg.yaml b/src/examples/py/ros2_chn/cfg/examples_py_ros2_chn_ros2_sub_cfg.yaml
@@ -0,0 +1,30 @@
+# Copyright (c) 2024 The AimRT Authors.
+# AimRT is licensed under Mulan PSL v2.
+
+aimrt:
+  plugin:
+    plugins:
+      - name: ros2_plugin
+        path: ${AIMRT_PLUGIN_DIR}/libaimrt_ros2_plugin.so
+        options:
+          node_name: example_ros2_chn_py_subscriber_node
+          executor_type: MultiThreaded # SingleThreaded/StaticSingleThreaded/MultiThreaded
+          executor_thread_num: 2
+  log:
+    core_lvl: INFO # Trace/Debug/Info/Warn/Error/Fatal/Off
+    default_module_lvl: INFO
+    backends:
+      - type: console
+  channel:
+    backends:
+      - type: ros2
+    sub_topics_options:
+      - topic_name: "(.*)"
+        enable_backends: [ros2]
+  module:
+    modules:
+      - name: NormalSubscriberPyModule
+        log_lvl: INFO
+
+NormalSubscriberPyModule:
+  topic_name: test_topic