WebSocket Gateway 总览

通道兼容说明（PCAN + slcan + Damiao 串口桥）

Linux SocketCAN 直接使用网卡名：can0、can1、slcan0。
串口类 USB-CAN 需先创建并拉起 slcan0：sudo slcand -o -c -s8 /dev/ttyUSB0 slcan0 && sudo ip link set slcan0 up。
仅 Damiao 可选串口桥链路：--transport dm-serial --serial-port /dev/ttyACM0 --serial-baud 921600。
Damiao 串口桥完整接口与命令模板见 motor_cli/README.zh-CN.md 第 3.6 节（英文见 motor_cli/README.md）。
Linux SocketCAN 下 --channel 不要带 @bitrate（例如 can0@1000000 无效）。
Windows（PCAN 后端）中，can0/can1 映射 PCAN_USBBUS1/2，可选 @bitrate 后缀。

高性能 Rust WebSocket 网关（V1：JSON over WS）。

状态

WS API 主链路已实现。内置网页上位机（tools/ws_test_client.html）仍在持续开发中。

传输

协议：WebSocket
V1 载荷：JSON 文本帧
按 --dt-ms 周期推送状态

统一模式映射（草案）

目标：应用层优先使用统一操作集；厂商专属操作保留可用，但不作为默认推荐路径。

统一控制模式（应用层，固定基线）

统一模式	统一操作	核心参数
`mit`	`{"op":"mit", ...}`	`pos`, `vel`, `kp`, `kd`, `tau`
`pos_vel`	`{"op":"pos_vel", ...}`	`pos`, `vlim`
`vel`	`{"op":"vel", ...}`	`vel`
`force_pos`	`{"op":"force_pos", ...}`	`pos`, `vlim`, `ratio`

若某厂商不支持这四种基线模式，网关统一返回 unsupported。

厂商映射表（统一模式 -> 厂商原生）

厂商	`mit`	`pos_vel`	`vel`	`force_pos`	参数差异	备注
damiao	原生 MIT	原生 POS_VEL	原生 VEL	原生 FORCE_POS	参数完整对齐	基线参考实现
robstride	原生 MIT	映射到原生 Position（`run_mode=1` + `limit_spd` + `loc_ref`）	原生 Velocity 模式	不支持	`vel` 映射到 vendor velocity target；`pos_vel` 映射到 vendor Position	参数读写走 `robstride_*`
hexfellow	原生 MIT	原生 POS_VEL	不支持	不支持	`mit` 支持 `kp/kd/tau`，无独立 `vel`	CAN-FD 链路
myactuator	不支持	Position 设定流程	原生速度设定	不支持	`pos_vel` 通过 position setpoint 实现；基线里 `vel` 可用	强项是 current/position/version/mode-query
hightorque	原生 MIT（ht_can 映射）	映射到原生 pos+vel+tqe	原生速度帧	映射到原生 pos+vel+tqe	`mit/vel` 为原生帧映射；`kp/kd` 保留但协议侧忽略；`pos_vel/force_pos` 映射到 pos+vel+tqe	当前子集 scan/read/mit/vel/pos-vel/force-pos/stop；`enable/disable` 接受但为 no-op

统一核心操作支持矩阵

厂商	`scan`	`set_id`	`enable`	`disable`	`stop`	`state_once/status`
damiao	支持	支持	支持	支持	支持	支持
robstride	支持	支持	支持	支持	支持	支持
hexfellow	支持	不支持	支持	支持	支持	支持
myactuator	支持	不支持	支持	支持	支持	支持
hightorque	支持	不支持	接受（no-op）	接受（no-op）	支持	支持

模式参数差异说明

mit：统一字段一致，但各厂商内部缩放/编码不同，由网关适配层处理。 HighTorque 细节：当前协议路径会忽略 kp/kd。
pos_vel：仅对具备等价模式的厂商可用。
vel：方向与量纲转换由厂商适配层内部处理。
force_pos：Damiao 原生支持；HighTorque 映射到 pos+vel+tqe；其他厂商不支持。

WS `capabilities` 响应结构（草案）

建议：客户端连接后先调用 {"op":"capabilities"}，根据返回能力矩阵自动适配 UI 与流程。

响应示例

{
  "ok": true,
  "op": "capabilities",
  "data": {
    "api_version": "v1",
    "gateway_version": "v0.5.0",
    "batch_scan": true,
    "robstride_exact_host_scan": true,
    "default_vendor": "damiao",
    "vendors": {
      "damiao": {
        "transports": ["auto", "socketcan", "socketcanfd", "dm-serial", "dm-device"],
        "modes": ["mit", "pos_vel", "vel", "force_pos"],
        "ops_unified": ["scan", "set_id", "enable", "disable", "stop", "state_once", "status", "verify", "damiao_state_many"],
        "ops_vendor_native": ["write_register_u32", "write_register_f32", "get_register_u32", "get_register_f32"]
      },
      "robstride": {
        "transports": ["auto", "socketcan", "socketcanfd"],
        "modes": ["mit", "vel"],
        "ops_unified": ["scan", "set_id", "enable", "disable", "stop", "state_once", "status", "verify"],
        "ops_vendor_native": ["robstride_ping", "robstride_read_param", "robstride_write_param"]
      },
      "hexfellow": {
        "transports": ["auto", "socketcanfd"],
        "modes": ["mit", "pos_vel"],
        "ops_unified": ["scan", "enable", "disable", "stop", "state_once", "status", "verify"],
        "ops_vendor_native": []
      },
      "myactuator": {
        "transports": ["auto", "socketcan", "socketcanfd"],
        "modes": ["pos_vel", "vel"],
        "ops_unified": ["scan", "enable", "disable", "stop", "state_once", "status", "verify"],
        "ops_vendor_native": ["status", "version", "mode-query"]
      },
      "hightorque": {
        "transports": ["auto", "socketcan"],
        "modes": ["mit", "pos_vel", "vel", "force_pos"],
        "ops_unified": ["scan", "stop", "state_once", "status", "verify"],
        "ops_vendor_native": ["read"]
      }
    },
    "unsupported_behavior": "return {ok:false,error:'unsupported ...'}"
  }
}

多关节状态与鉴权说明

damiao_state_many： 通过 dm-serial 一次逻辑请求刷新所有已发现达妙关节。状态快照包含 motor_id、feedback_id 与 model，浏览器上位机可按关节合并整臂遥测，而非把所有反馈都当作当前 target。状态读取在返回前以有界超时请求新鲜反馈。
Token 鉴权： 浏览器客户端可在 WebSocket URL query 中带 ?motorbridge_ws_token=... 传入 MOTORBRIDGE_WS_TOKEN（header 鉴权与非回环 token 要求不变）。
单电机命令收敛： 单电机操作不再向多个已发现电机扩散，而是收敛到显式 target。
RobStride 扫描： 逐个、精确、顺序地探测 host/feedback ID（Windows PCAN 安全）。后续轮次会跳过已发现的 ID。
param_stream enabled=false： 关闭流不再打开或重开硬件会话。

构建

cargo build -p ws_gateway --release

运行

cargo run -p ws_gateway --release -- \
  --bind 127.0.0.1:9002 --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

cargo run -p ws_gateway --release -- \
  --bind 127.0.0.1:9002 --vendor robstride --channel can0 --model rs-06 --motor-id 127 --feedback-id 0xFD --dt-ms 20

安全说明：

默认推荐使用 127.0.0.1:9002（本机回环）。
若绑定到非回环地址（例如 0.0.0.0:9002），必须设置环境变量 MOTORBRIDGE_WS_TOKEN。
WS 客户端需在握手请求中带上 x-motorbridge-token: <token> 或 Authorization: Bearer <token>。

Windows 实验支持（PCAN-USB）

项目主线仍以 Linux 为主。Windows 支持为实验性能力，当前通过 PEAK PCAN 后端实现。

安装 PEAK 驱动与 PCAN-Basic 运行时（PCANBasic.dll）。
Windows 启动网关时可使用 can0@1000000：

cargo run -p ws_gateway --release -- --bind 127.0.0.1:9002 --vendor damiao --channel can0@1000000 --model 4340P --motor-id 0x01 --feedback-id 0x11 --dt-ms 20

Windows 电机验证命令：

cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode scan --start-id 1 --end-id 16
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode pos-vel --pos 3.1416 --vlim 2.0 --loop 1 --dt-ms 20
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4310 --motor-id 0x07 --feedback-id 0x17 --mode pos-vel --pos 3.1416 --vlim 2.0 --loop 1 --dt-ms 20

入站命令示例

{"op":"ping"}
{"op":"enable"}
{"op":"disable"}
{"op":"set_target","vendor":"robstride","channel":"can0","model":"rs-06","motor_id":127,"feedback_id":255}
{"op":"mit","pos":0.0,"vel":0.0,"kp":20.0,"kd":1.0,"tau":0.0,"continuous":true}
{"op":"pos_vel","pos":3.1,"vlim":1.5,"continuous":true}
{"op":"vel","vel":0.5,"continuous":true}
{"op":"force_pos","pos":0.8,"vlim":2.0,"ratio":0.3,"continuous":true}
{"op":"stop"}
{"op":"state_once"}
{"op":"clear_error"}
{"op":"set_zero_position"}
{"op":"ensure_mode","mode":"mit","timeout_ms":1000}
{"op":"request_feedback"}
{"op":"store_parameters"}
{"op":"set_can_timeout_ms","timeout_ms":1000}
{"op":"write_register_u32","rid":10,"value":1}
{"op":"write_register_f32","rid":31,"value":5.0}
{"op":"get_register_u32","rid":7,"timeout_ms":1000}
{"op":"get_register_f32","rid":21,"timeout_ms":1000}
{"op":"robstride_ping","timeout_ms":200}
{"op":"robstride_read_param","param_id":28697,"type":"f32","timeout_ms":200}
{"op":"robstride_write_param","param_id":28682,"type":"f32","value":0.3,"verify":true}
{"op":"poll_feedback_once"}
{"op":"shutdown"}
{"op":"close_bus"}
{"op":"scan","start_id":1,"end_id":16,"feedback_base":16,"timeout_ms":100}
{"op":"scan","vendor":"robstride","start_id":120,"end_id":135,"feedback_ids":"0xFF,0xFE,0x00","timeout_ms":120}
{"op":"set_id","vendor":"damiao","old_motor_id":2,"old_feedback_id":18,"new_motor_id":5,"new_feedback_id":21,"store":true,"verify":true}
{"op":"set_id","vendor":"robstride","old_motor_id":127,"new_motor_id":126,"feedback_id":255,"verify":true}
{"op":"verify","motor_id":5,"feedback_id":21,"timeout_ms":1000}
{"op":"verify","vendor":"robstride","motor_id":127,"feedback_id":255,"timeout_ms":500}

出站帧

成功响应：

{"ok":true,"op":"vel","data":{"op":"vel","continuous":true}}

失败响应：

{"ok":false,"op":"set_id","error":"..."}

状态流：

{"type":"state","data":{"has_value":true,"pos":0.12,"vel":0.01,"torq":0.0,"status_code":1}}

说明

--vendor damiao|robstride|hexfellow|myactuator|hightorque 用于设置会话默认厂商。
set_target 可在单个会话中动态切换厂商/transport/通道/串口/型号/ID。
continuous=true 会在每个 tick 持续发送该控制命令。
stop 用于清除持续控制。
set_id 按厂商处理：
- Damiao：先写 MST_ID，再写 ESC_ID。
- RobStride：使用 SET_DEVICE_ID 更新设备 ID。
Damiao 专属操作：write/get_register_* 与 dm-serial transport。
RobStride 专属操作：robstride_ping、robstride_read_param、robstride_write_param。
MyActuator 专属操作：current、pos、version、mode-query。
HighTorque 专属操作：read。
后续 V2 可升级为二进制帧，同时保留同一语义。

简易上位机（快速联调）

文件：integrations/ws_gateway/tools/ws_test_client.html
四电机同步专用示例：examples/web/ws_quad_sync_hmi.html
直接浏览器打开（双击或 xdg-open），连接 ws://127.0.0.1:9002。
当前状态：开发中（界面与交互会持续调整）。
若要稳定联调，建议优先使用 JSON 直连客户端（wscat/websocat/自定义客户端）。
动态设备工作流：
- 同一页面扫描 Damiao 与 RobStride
- 扫描结果进设备表（vendor + motor_id + feedback_id + model）
- 可选择任意扫描到的设备作为当前目标，执行使能/失能/速度/MIT
- 支持勾选批量操作：批量使能/停转/失能、批量 MIT 同步到角度
四电机同角度拖杆控制建议用本地静态服务打开：
- python3 -m http.server 18080
- 浏览器访问 http://127.0.0.1:18080/examples/web/ws_quad_sync_hmi.html

快速开始

教程

接口手册

最佳实践

参考

源码：仓库

源码：项目文档

源码：Python Binding

源码：C++ Binding

源码：Rust CLI

源码：示例

源码：传输

源码：集成

源码：工具与厂商

通道兼容说明（PCAN + slcan + Damiao 串口桥）

状态

传输

统一模式映射（草案）

统一控制模式（应用层，固定基线）

厂商映射表（统一模式 -> 厂商原生）

统一核心操作支持矩阵

模式参数差异说明

WS `capabilities` 响应结构（草案）

响应示例

多关节状态与鉴权说明

构建

运行

Windows 实验支持（PCAN-USB）

入站命令示例

出站帧

说明

简易上位机（快速联调）

​通道兼容说明（PCAN + slcan + Damiao 串口桥）

​状态

​传输

​统一模式映射（草案）

​统一控制模式（应用层，固定基线）

​厂商映射表（统一模式 -> 厂商原生）

​统一核心操作支持矩阵

​模式参数差异说明

​WS capabilities 响应结构（草案）

​响应示例

​多关节状态与鉴权说明

​构建

​运行

​Windows 实验支持（PCAN-USB）

​入站命令示例

​出站帧

​说明

​简易上位机（快速联调）

通道兼容说明（PCAN + slcan + Damiao 串口桥）

状态

传输

统一模式映射（草案）

统一控制模式（应用层，固定基线）

厂商映射表（统一模式 -> 厂商原生）

统一核心操作支持矩阵

模式参数差异说明

WS `capabilities` 响应结构（草案）

响应示例

多关节状态与鉴权说明

构建

运行

Windows 实验支持（PCAN-USB）

入站命令示例

出站帧

说明

简易上位机（快速联调）