From becf73edf1960c0fb5e476aa553b143a3b765072 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9B=BE=E6=93=8E=E7=A6=B9?= Date: Wed, 16 Jul 2025 11:22:03 +0800 Subject: [PATCH 1/2] add information of service definition. --- .../5-heterogeneous-robot-data-factory.md | 54 ++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/use-case/5-heterogeneous-robot-data-factory.md b/docs/use-case/5-heterogeneous-robot-data-factory.md index e5c5374ce..054e30070 100644 --- a/docs/use-case/5-heterogeneous-robot-data-factory.md +++ b/docs/use-case/5-heterogeneous-robot-data-factory.md @@ -50,7 +50,59 @@ sidebar_position: 5 ## 准备与启动 ROS node - 机器人本体上需要有可以提供 **service** 的**数据录制节点**，并且提供 **开始录制** （如/start_record）， **取消录制** （如/cancel_record）， **结束录制** （如/stop_record）之类的服务供刻行时空调用。 - -- **注意：**： 目前只支持**service** 类型的消息。 + -- **注意：** + 1. 目前只支持**service** 类型的消息。 + 2. 消息的格式需要符合 ROS/ROS2 消息定义规范，如： + ``` + std_srvs/Empty "start_record" + std_srvs/Empty "cancel_record" + std_srvs/Empty "stop_record" + ``` + 3. 各接口请求和返回，需要满足一定的要求，如： + ``` + - /start_record + - Request + { + "record_opt": "-a" //可选，取决于您的服务是否支持传参 + } + - Response + { + "success": true / false , // 表示是否成功启动录制，必须返回 + "message": "" + } + ``` + ``` + - /cancel_record + - Request + { + "auto_remove": true //可选，取决于您的服务是提供对应删除废弃数据的能力 + } + - Response + { + "success": true / false, // 表示是否成功取消录制，必须返回 + "message": "" // 可选，是否返回必要信息 + } + ``` + ``` + - /stop_record + - Request + { } //可支持传参 + - Response + { + "success": true, // 如果 success 为 true 则读取 type 来判断行为, + // "NORMAL" - 需要把生成的bag上传 + // "SKIP_CAPTURE" - 采集出现问题(e.g.: 未能通过bag质量检测),不需要上传，非必须。 + "type": "NORMAL" | "SKIP_CAPTURE" , + "message": "", // 可选，是否返回必要信息 + "record_name": "", // 可选，是否要指定平台记录的名称 + "tags": ["01", "02"], // 可选，是否要指定平台记录的标签 + "files": [ // 必须返回此次录制数据的绝对路径 + "/home/cos/bags/1.bag", + "/home/cos/bags/2.bag", + "/home/cos/bags/3.bag" + ] + } + - 启动 coBridge 前需 source **数据录制节点** 的 workspace 环境变量。 - 示例启动脚本（请根据实际情况修改）： ```bash From af68388a77b9de61bbff4c674a6dab44537c3858 Mon Sep 17 00:00:00 2001 From: "fei.gao" Date: Wed, 16 Jul 2025 16:39:25 +0800 Subject: [PATCH 2/2] nit --- .../5-heterogeneous-robot-data-factory.md | 119 +++++++++++------- 1 file changed, 71 insertions(+), 48 deletions(-) diff --git a/docs/use-case/5-heterogeneous-robot-data-factory.md b/docs/use-case/5-heterogeneous-robot-data-factory.md index 054e30070..a461700fb 100644 --- a/docs/use-case/5-heterogeneous-robot-data-factory.md +++ b/docs/use-case/5-heterogeneous-robot-data-factory.md @@ -51,57 +51,80 @@ sidebar_position: 5 - 机器人本体上需要有可以提供 **service** 的**数据录制节点**，并且提供 **开始录制** （如/start_record）， **取消录制** （如/cancel_record）， **结束录制** （如/stop_record）之类的服务供刻行时空调用。 -- **注意：** - 1. 目前只支持**service** 类型的消息。 - 2. 消息的格式需要符合 ROS/ROS2 消息定义规范，如： +1. /start_record service + + e.g.: + ```C++ + # request + string record_opt + --- + # response + bool success + string message ``` - std_srvs/Empty "start_record" - std_srvs/Empty "cancel_record" - std_srvs/Empty "stop_record" + start_record request 无任何要求,可以在此处添加一些例如 `saving directory` 等字段, 供`数据录制节点`使用。 + + start_record response 必须需包含 `success` 和 `message` 字段, 用于通知 web 端是否已经成功开启了录制功能。 + +2. /cancel_record service + + e.g.: + ```C++ + # request + bool auto_remove # remove bags that are recorded + --- + # response + bool success + string message ``` - 3. 各接口请求和返回，需要满足一定的要求，如： + cancel_record request 无任何要求,可以在此处添加一些例如 `auto_remove` 等字段, 供`数据录制节点`使用。 + + cancel_record response 必须需包含 `success` 和 `message` 字段, 用于通知 web 端是否已经成功取消了录制功能。 + +3. /stop_record service + + e.g.: + ```C++ + # request + --- + # response + bool success + string type + string message + string record_name + string[] tags + string[] files ``` - - /start_record - - Request - { - "record_opt": "-a" //可选，取决于您的服务是否支持传参 - } - - Response - { - "success": true / false , // 表示是否成功启动录制，必须返回 - "message": "" - } - ``` - ``` - - /cancel_record - - Request - { - "auto_remove": true //可选，取决于您的服务是提供对应删除废弃数据的能力 - } - - Response - { - "success": true / false, // 表示是否成功取消录制，必须返回 - "message": "" // 可选，是否返回必要信息 - } - ``` - ``` - - /stop_record - - Request - { } //可支持传参 - - Response - { - "success": true, // 如果 success 为 true 则读取 type 来判断行为, - // "NORMAL" - 需要把生成的bag上传 - // "SKIP_CAPTURE" - 采集出现问题(e.g.: 未能通过bag质量检测),不需要上传，非必须。 - "type": "NORMAL" | "SKIP_CAPTURE" , - "message": "", // 可选，是否返回必要信息 - "record_name": "", // 可选，是否要指定平台记录的名称 - "tags": ["01", "02"], // 可选，是否要指定平台记录的标签 - "files": [ // 必须返回此次录制数据的绝对路径 - "/home/cos/bags/1.bag", - "/home/cos/bags/2.bag", - "/home/cos/bags/3.bag" - ] - } + stop_record request 无任何要求,可以在此处添加一些字段, 供`数据录制节点`使用。 + + stop_record response 必须需包含示例中的所有字段。 + + | 字段 | 含义 | 备注 | + |-------------|--------------------------------------|--------------------------------------------------------------------------------------------------| + | success | 停止录制是否成功 | 不可为空 | + | type | 是否需要上传录制的包 | 不可为空,type 的值为以下之一:
"NORMAL": 需要把生成的bag上传
"SKIP_CAPTURE":采集出现问题(e.g.: 未能通过bag质量检测),不需要上传 | + | message | success 为 false时, 用于返回 error message | 可以为空 | + | record_name | 指定平台记录的名称 | 如果record_name=="", 则使用默认 record 名称 "deviceSN-startTime" | + | tags | 对 record 添加的 tag | 可以为空 | + | files | 需要上传的文件列表 | 不可为空 | + +**response示例:** +```json +{ + "success": true, + "type": "NORMAL", + "message": "采集成功", + "record_name": "", + "tags": ["01", "02"], + "files": [ + "/home/cos/bags/1.bag", + "/home/cos/bags/2.bag", + "/home/cos/bags/3.bag" + ] +} +``` + + - 启动 coBridge 前需 source **数据录制节点** 的 workspace 环境变量。 - 示例启动脚本（请根据实际情况修改）：