# 新松DucoCobot双臂
本章介绍如何使用新松（SONGYI）DucoCobot双臂适配器接入CloudRobo平台。新松DucoCobot双臂以**第三方适配器包** songyi-robot 的形式提供，通过 r2c_sdk.adapters entry_point 注册，可独立 pip install，无需修改SDK主干。
硬件说明
新松DucoCobot双臂机器人包含左右两个机械臂（各7关节）、腰部（4关节，末关节可控）及双夹爪（485总线），通过新松SDK 3.8.5 Thrift RPC 通信。适配器同时提供Mock仿真版本（SongyiMockAdapter），无需硬件即可运行全链路。
硬件信息
| **组件** | **数量** | **说明**                                  |
|:---|:---|:---|
| 机械臂   | 2（左/右）   | 各7关节，DucoCobot Thrift RPC（左臂7003/右臂7004） |
| 腰部     | 4关节  | 末关节可控（waist_command），前3关节固定不可控         |
| 夹爪     | 2（左/右）  | 485总线，开度0\~1                            |
| 相机    | 可选       | 支持 teleimager（pyzmq）或回放模式               |
   
依赖与环境
| **依赖**       | **说明**                                         |
|:---|:---|
| songyi-robot | 第三方适配器包（pip install -e examples/songyi/robot） |
| pyzmq\>=24.0   | teleimager 相机后端（懒加载，不进SDK主依赖）                   |
| 新松SDK 3.8.5 | 真机Thrift RPC（demo/目录提供，懒加载）                     |
| hw-r2c-sdk   | 官方R2C SDK（同仓开发环境已editable安装）                     |
   
安装适配器包
```
# 安装新松适配器包（第三方entry_point模式）
pip install -e examples/songyi/robot
# 验证安装
python -c "from r2c_sdk.robots.robot_factory import AdapterRegistry; print(AdapterRegistry.available_types())"
# 输出应包含: 'songyi', 'songyi_mock'
```
配置文件
新松双臂提供两份配置文件：
- **真机配置**：examples/songyi/config/robot_config.yaml（SongyiHardwareAdapter，Thrift RPC连真机）
- **Mock仿真配置**：examples/songyi/config/robot_mock_config.yaml（SongyiMockAdapter，软件仿真，无硬件依赖）
关键配置项
| **参数**                               | **类型** | **默认值**                                           | **说明**                          |
|:---|:---|:---|:---|
| hardware.type                         | str       | "custom"                                          | 硬件类型（新松使用custom + class_path）     |
| hardware.class_path                   | str      | SongyiHardwareAdapter / SongyiMockAdapter           | 适配器类路径                        |
| runtime.publish_hz                      | float     | 30.0                                              | 动作执行频率（控制循环按此速率消费action chunk） |
| runtime.dry_run                        | bool      | false                                              | sync_client层干跑（只观测不下发action）     |
| runtime.max_enqueue_actions_per_chunk | int     | 30                                               | 单批入队动作数上限                       |
| runtime.heartbeat                      | dict     | {enabled: true, interval_ms: 500, jitter_ms: 50} | 心跳自动发布（2Hz + jitter）            |
| runtime.mode_control                 | dict     | 见下文                                                | 遥操/协助进出 + 心跳mode联动            |
| hardware.topics                         | dict      | 见下文                                               | 自定义topic四绑定（全部走主session）        |
| hardware.custom_config.dry_run        | bool       | false                                              | 硬件层干跑（send_action只打印不下发）          |
   
自定义topic绑定（hardware.topics）
新松双臂通过 hardware.topics 声明自定义topic，全部运行在**主session**上：
```
hardware:
  type: "custom"
  class_path: "songyi_robot.songyi_adapter.SongyiHardwareAdapter"
  topics:
    # 状态发布（定频率发布）
    "{project_id}/{device_id}/state/current":
      proto: "r2c_sdk.common.models:RunTimeMessage"
      direction: "publish"
      rate_hz: 2
      collector: "get_runtime"
    # 腰部控制（订阅命令）
    "{project_id}/{device_id}/waist_command":
      proto: "songyi.waist_command"    # r2c_sdk.protos 注册名（新松专属proto）
      direction: "subscribe"
      on_message: "on_waist_command"
    # 告警事件不走绑定：AlarmManager经EventManager推送
    # topic固定 {project_id}/{device_id}/event
```
**说明**：songyi.waist_command 是通过 r2c_sdk.protos entry_point 注册的私有proto（songyi_robot.models.generated.waist_command_pb2:WaistCommand），不进SDK主干、不经云gateway转发，只在本机解析。
心跳mode联动
新松双臂支持遥操/协助模式切换时的心跳mode联动（AUTO/CONTROLLED/ASSISTED）：
```
runtime:
  heartbeat: { enabled: true, interval_ms: 500, jitter_ms: 50,
               status: ONLINE, mode: AUTO }
  mode_control:
    teleop_enter_cb: "teleop_enter"    # 遥操进入 → mode=CONTROLLED
    teleop_exit_cb: "teleop_exit"     # 遥操退出 → mode=AUTO
    assist_enter_cb: "assist_enter"   # 协助进入 → mode=ASSISTED
    assist_exit_cb: "assist_exit"      # 协助退出 → mode=AUTO
```
启动命令
**方式A：云端证书bundle（正式接入CloudRobo平台）**
```
python -m r2c_sdk.cloudroboclient --robot-config examples/songyi/config/robot_config.yaml --bundle       config/cert_xxx.zip
```
**方式B：本地YAML配置（无bundle，本地/局域网联调）**
```
python -m r2c_sdk.cloudroboclient --robot-config examples/songyi/config/robot_config.yaml --client-config config/client_config.yaml
```
**Mock仿真（无硬件）**
```
python -m r2c_sdk.cloudroboclient --robot-config examples/songyi/config/robot_mock_config.yaml --client-config config/client_config.yaml
```
**本地多端协作部署（进程内forwarder + 独立[zenohd](https://github.com/eclipse-zenoh/zenoh/releases)）**
```
# 1. 启动独立zenohd（本地中心总线）
zenohd -l tcp/127.0.0.1:7447  # -l tcp/127.0.0.1:7447 仅本机端可通信，  -l tcp/0.0.0.0:7447为局域网内可通信
# 2. 启动cloudroboclient（主session连本地zenohd + forwarder_session连云）
python -m r2c_sdk.cloudroboclient --robot-config examples/songyi/config/robot_config.yaml --client-config config/client_config.yaml --forwarder-config config/forwarder_config.yaml --bundle config/cert_xxx.zip
```
**说明**：--forwarder-config 声明 forwarder_session（云，--bundle 连云身份/证书），--client-config 声明本地主session（mode=client 连独立进程 zenohd）。--bundle 缺省时不启动 forwarder_session，仅纯本地主线。forwarder_config.yaml 顶层 topic_defaults 全局默认参数（sample_factor、sample_max_interval_s、sample_min_interval_s、rewrite_timestamp、cache_size），route 级相同键可覆盖。
**去中心化部署（peer模式 + 进程内forwarder，无需独立zenohd）**
```
# 单条命令启动（peer模式 + 进程内forwarder，无需独立zenohd）
python -m r2c_sdk.cloudroboclient --robot-config examples/songyi/config/robot_config.yaml --bundle config/cert_xxx.zip --forwarder-config config/forwarder_config.yaml
```
**说明**：主 session 使用 --client-config（默认 config/client_config.yaml），默认 client 模式连接，失败后降级为 peer 模式（mode=peer、endpoint_role=listen），peer 模式下无需独立 zenohd。--bundle 仅用于 forwarder_session 连云。进程内 forwarder 按 routes 配置双向转发：上行转发 observations/event/job/task/state/current/state/heartbeats/data_ingestion/upload_status，下行转发 inference/actions、job/command。
双层dry_run安全门控
新松双臂接入提供**双层dry_run**安全门控，真机执行前两层都必须为 false：
1. **sync_client层**（runtime.dry_run）：action不下发到硬件适配器
2. **硬件层**（hardware.custom_config.dry_run）：send_action 只打印 \[DRY_RUN\] observation/action 供链路比对，不下发硬件
⚠️ **安全提醒**：真机测试时人员远离工作空间，随时可按急停。首次联调务必保持两层 dry_run: true，验证后再改 false。
联调工具
新松双臂提供以下联调工具（位于 examples/songyi/）：
| **工具**                    | **说明**                              |
|:---|:---|
| cloud_adapter.py           | 云适配器（订阅观测→回发安全位姿，支持joint/cartesian模式） |
| waist_command_publisher.py | 腰部命令发布工具                             |
| taskprocess_voice.py       | 任务进度声音告警（订阅job/task）                 |
| assist_voice.py            | 现场协助声音告警（订阅command）                  |
   
键盘控制
新松双臂键盘控制支持以下按键（runtime.keyboard_control.enabled: true 时生效）：
| **按键** | **功能**                            |
|:---|:---|
| a/d键  | 腰部末关节点动（+step/-step）          |
| s键    | 腰部末关节回0                         |
| l键  | 左臂位姿四步循环（位姿1→home→位姿2→home，每按一步） |
| r键    | 右臂位姿四步循环（位姿1→home→位姿2→home，每按一步） |
| g键     | 切换夹爪开合                          |
| h键   | 双臂复位到reset_pose及夹爪张开            |
| 空格键   | 暂停/恢复                            |
| q键   | 优雅退出                            |
   
----结束
