PR0001 JxServo Studio USB 通信协议
| 项目 | 信息 |
|---|---|
| 文档编号 | PR0001 |
| 文档版本 | Rev. 1.0 |
| 适用产品 | JxServo Studio / JxServo 伺服设备 |
| 语言 | 简体中文 |
| 最后更新 | 2026-05-11 |
JxServo Studio 提供面向伺服设备调试、系统集成和二次开发的开放 USB 通信接口。开发者可以基于本协议接入自研测试软件、自动化测试平台、数据采集系统或上层业务应用，在不依赖 JxServo Studio 图形界面的情况下完成设备识别、参数管理、命令触发、日志接收和实时运行数据采集。
本协议采用统一帧格式和动态能力发现机制。参数列表、命令列表和设备信息均由设备侧返回，上位应用无需固化完整功能清单，可随不同产品型号和版本自动适配。JxServo Studio 同样基于该接口与设备通信，因此本文档也可作为第三方工具接入 JxServo 设备的公开参考。
开放接口能力
| 能力 | 开放能力 |
|---|---|
| 设备识别 | 读取设备地址、版本信息和设备名称，便于软件自动识别连接对象 |
| 参数管理 | 动态读取参数数量、类型、名称、说明和值，支持上位应用完成参数查看与配置 |
| 命令发现 | 动态读取设备当前开放的命令集合，避免上位应用维护固定命令表 |
| 命令执行 | 按设备返回的命令描述组装执行帧，支持自动化调试和应用集成 |
| 日志接收 | 接收设备侧状态、错误和提示信息，便于集成软件给出清晰反馈 |
| 实时遥测 | 获取位置、速度、电流、电压、温度、控制环状态和总线原始数据等运行信息 |
本文聚焦可直接对接的公开 USB 接口。不同产品型号的参数内容、命令内容和遥测启用策略可能不同，上位应用应优先采用动态读取结果构建界面和业务逻辑。
协议基础
USB 链路使用 CDC 字节流承载协议帧。每一帧都包含源地址、目标地址、功能码、数据长度、数据载荷和双字节校验，便于上位应用在连续字节流中稳定恢复帧边界并校验数据完整性。
所有报文使用如下帧格式：
0xAB | S_ADDR | D_ADDR | ID | LEN_L | LEN_H | DATA... | SUM_CHECK | ADD_CHECK
| 字段 | 长度 | 说明 |
|---|---|---|
0xAB | 1 | 帧头固定值 |
S_ADDR | 1 | 源地址 |
D_ADDR | 1 | 目标地址 |
ID | 1 | 帧功能码 |
LEN | 2 | DATA 字节数，小端 |
DATA | N | 载荷数据 |
SUM_CHECK | 1 | 和校验 |
ADD_CHECK | 1 | 附加校验 |
公开地址定义如下：
| 地址 | 含义 |
|---|---|
0x01 | 伺服设备默认地址 |
0xFE | JxServo Studio |
0xFF | 广播地址 |
多字节整数和 float 均采用小端传输。float 为 IEEE 754 binary32。设备接收单帧 DATA 长度必须小于 128 字节；上位应用解析设备发送数据时，建议按 DATA <= 120 字节设计接收缓冲。
校验从帧头开始，到 DATA 最后一个字节结束：
uint8_t sum = 0;
uint8_t add = 0;
for (uint16_t i = 0; i < 6 + len; ++i) {
sum = (uint8_t)(sum + frame[i]);
add = (uint8_t)(add + sum);
}
frame[6 + len] = sum;
frame[7 + len] = add;
读取设备信息示例：
AB FE 01 E0 01 00 00 8B 2B
接口帧概览
公开 USB 接口由少量基础帧组成。上位应用通常先读取设备信息，再动态读取参数列表和命令列表，最后按业务需要读写参数、执行命令或开启遥测。
| ID | 方向 | 名称 | 说明 |
|---|---|---|---|
0x00 | 设备 -> Studio | 应答校验 | 对参数写入、命令执行等需要确认的帧返回处理应答 |
0xA0 | 设备 -> Studio | 日志字符串 | 输出状态、错误和提示文本 |
0xC0 | Studio -> 设备 | 命令执行 | 执行通过命令发现流程读取到的命令 |
0xC1 | 双向 | 命令数量/读取命令信息 | Studio 查询命令数量或指定命令描述 |
0xC2 | 设备 -> Studio | 命令信息 | 返回命令描述、参数类型、名称和说明 |
0xE0 | 双向 | 参数命令 | 读取设备信息、参数数量、参数值或参数信息 |
0xE1 | 双向 | 参数值 | Studio 写入参数值，或设备返回参数值 |
0xE2 | 设备 -> Studio | 参数信息 | 返回参数类型、名称和说明 |
0xE3 | 设备 -> Studio | 设备信息 | 返回设备地址、版本号和设备名称 |
0xF1 - 0xF8 | 设备 -> Studio | 遥测数据 | 实时波形和运行数据 |
应答校验 0x00
需要确认的写入类或执行类操作会收到 0x00 应答帧。上位应用应使用该帧确认设备已经收到并处理了对应报文。
DATA 固定 3 字节：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | ID_GET | 被确认帧的 ID |
| 1 | uint8 | SC_GET | 被确认帧的 SUM_CHECK |
| 2 | uint8 | AC_GET | 被确认帧的 ADD_CHECK |
上位应用应同时匹配 ID_GET、SC_GET 和 AC_GET，确认应答对应当前发送帧。参数写入类帧收到应答表示设备已处理该帧；若设备同时输出错误日志，应以日志和重新读取结果判断参数是否实际生效。
日志字符串 0xA0
设备可通过日志帧向上位应用输出状态、告警和操作结果。集成软件可将不同颜色编码映射为普通提示、错误提示、成功提示或调试信息。
DATA 格式：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | COLOR | 0 默认，1 红色，2 绿色，3 蓝色 |
| 1..N | bytes | TEXT | 文本字节，不包含结尾 0x00 |
设备单条日志文本最长按 100 字节处理。
参数读写
参数接口用于构建设备配置页、调试面板或自动化配置流程。上位应用不需要预置参数表，应通过 0xE0、0xE2 动态读取参数元信息，再根据类型读写参数值。
参数类型编码：
| 编码 | 类型 | 长度 |
|---|---|---|
0 | uint8 | 1 |
1 | int8 | 1 |
2 | uint16 | 2 |
3 | int16 | 2 |
4 | uint32 | 4 |
5 | int32 | 4 |
8 | float | 4 |
参数命令 0xE0
参数命令用于读取设备信息、参数数量、参数值和参数说明。推荐上位应用在连接设备后先读取设备信息和参数数量，再按参数 ID 顺序读取参数信息。
Studio 发送：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | CMD | 参数命令 |
| 1..2 | uint16 | VAL | 命令参数；无参数命令可省略或填 0 |
CMD | VAL | 返回 | 说明 |
|---|---|---|---|
0x00 | 无 | 0xE3 | 读取设备信息 |
0x01 | 无 | 0xE0 | 读取参数数量 |
0x02 | 参数 ID | 0xE1 | 读取参数值 |
0x03 | 参数 ID | 0xE2 | 读取参数信息 |
设备返回参数数量时，DATA 为：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | CMD | 固定 0x01 |
| 1..2 | uint16 | COUNT | 当前参数数量 |
参数 ID 从 0 开始，最大有效值为 COUNT - 1。
参数值 0xE1
参数值帧既用于 Studio 写入参数，也用于设备返回参数当前值。上位应用写入前应使用参数信息中的类型和取值范围约束用户输入。
Studio 写入参数值：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0..1 | uint16 | PAR_ID | 参数 ID |
| 2..N | 按参数类型 | PAR_VAL | 参数值 |
设备收到后返回 0x00 应答校验。写入会进行 ID、读写属性、长度和范围检查；失败时设备会通过 0xA0 输出原因。
设备返回参数值：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0..1 | uint16 | PAR_ID | 参数 ID |
| 2..N | 按参数类型 | PAR_VAL | 参数当前值 |
参数信息 0xE2
参数信息由设备维护，包含参数 ID、类型、名称和说明。集成软件应以该信息作为界面显示和数据解析依据。
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0..1 | uint16 | PAR_ID | 参数 ID |
| 2 | uint8 | PAR_TYPE | 参数类型编码 |
| 3..22 | bytes[20] | PAR_NAME | 参数名称，不足部分为 0x00 |
| 23..N | bytes | PAR_INFO | 参数说明文本 |
设备信息 0xE3
设备信息用于确认当前连接对象和版本信息。上位应用可将其用于设备选择、兼容性提示和日志记录。
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | DEV_ID | 设备地址 |
| 1..2 | uint16 | HW_VER | 硬件版本 |
| 3..4 | uint16 | SW_VER | 软件版本 |
| 5..6 | uint16 | BL_VER | Bootloader 版本 |
| 7..8 | uint16 | PT_VER | 协议版本 |
| 9..N | bytes | DEV_NAME | 设备名称，最长 20 字节 |
命令发现与执行
命令接口采用动态发现方式，适合开放集成和二次开发。设备返回当前可用命令的标识、参数类型、命令名称和说明，上位应用据此生成按钮、表单或自动化动作。
推荐流程：
- Studio 发送
0xC1，CMD=0，读取命令数量。 - 设备返回
0xC1，给出当前命令数量。 - Studio 按命令序号发送
0xC1，CMD=1，读取每条命令信息。 - 设备返回
0xC2，包含命令三字节标识、参数类型、名称和说明。 - Studio 根据
0xC2描述组装0xC0执行帧。
命令读取 0xC1
命令读取帧用于查询命令数量或读取指定命令的元信息。上位应用应以设备返回的命令数量为准，逐条读取完整命令描述。
Studio 发送：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | CMD | 0 读取数量，1 读取命令信息 |
| 1..2 | uint16 | VAL | CMD=1 时为命令序号 |
设备返回命令数量：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | CMD | 固定 0 |
| 1..2 | uint16 | COUNT | 当前命令数量 |
命令信息 0xC2
命令信息帧描述一条可执行命令。上位应用应按 VAL0..VAL7 的参数类型顺序组织输入参数，并按小端格式写入执行帧。
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0..1 | uint16 | CMD_ID | 命令序号 |
| 2 | uint8 | CMD0 | 命令模块标识 |
| 3 | uint8 | CMD1 | 命令动作标识 |
| 4 | uint8 | CMD2 | 命令功能标识 |
| 5..12 | uint8[8] | VAL0..VAL7 | 命令参数类型 |
| 13..32 | bytes[20] | CMD_NAME | 命令名称，不足部分为 0x00 |
| 33..N | bytes | CMD_INFO | 命令说明文本 |
命令参数类型编码：
| 编码 | 类型 | 长度 |
|---|---|---|
0x00 | 无参数 | 0 |
0x01 | uint8 | 1 |
0x02 | int8 | 1 |
0x03 | uint16 | 2 |
0x04 | int16 | 2 |
0x05 | uint32 | 4 |
0x06 | int32 | 4 |
0x09 | float | 4 |
命令执行 0xC0
命令执行帧用于触发设备侧开放的操作。命令含义由 0xC2 返回的信息定义，公开文档不要求上位应用提前维护完整命令清单。
Studio 发送：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0 | uint8 | CMD0 | 来自 0xC2 |
| 1 | uint8 | CMD1 | 来自 0xC2 |
| 2 | uint8 | CMD2 | 来自 0xC2 |
| 3..N | 按 VAL0..VAL7 | ARGS | 命令参数，按顺序紧凑排列 |
设备匹配到命令后返回 0x00 应答校验，并执行对应操作。若命令参数不合法，设备会通过 0xA0 输出原因。
遥测数据
遥测接口用于实时观察设备运行状态，可接入波形显示、数据记录、性能分析或自研监控系统。帧 0xF1 到 0xF8 可由命令层启停或调整发送分频；遥测帧不需要上位应用返回应答。
0xF1 位置、速度与电流
DATA 长度 40 字节，全部为 float：
| 序号 | 名称 | 单位 |
|---|---|---|
| 1 | 目标位置 | deg |
| 2 | 反馈位置 | deg |
| 3 | 位置误差 | deg |
| 4 | 目标速度 | rpm |
| 5 | 反馈速度 | rpm |
| 6 | 速度误差 | rpm |
| 7 | Iq 目标 | A |
| 8 | Iq 反馈 | A |
| 9 | Id 目标 | A |
| 10 | Id 反馈 | A |
0xF2 母线、关节与温度
DATA 长度 32 字节，全部为 float：
| 序号 | 名称 | 单位 |
|---|---|---|
| 1 | 母线电流 | A |
| 2 | 母线电压 | V |
| 3 | 关节速度 | rpm |
| 4 | 关节角度 | deg |
| 5 | 电机速度 | rpm |
| 6 | Iq 反馈 | A |
| 7 | 功率器件温度 | degC |
| 8 | 电机温度 | degC |
0xF3 采样与编码器原始量
DATA 长度 24 字节：
| 偏移 | 类型 | 名称 | 单位 |
|---|---|---|---|
| 0 | float | U 相电流 | A |
| 4 | float | V 相电流 | A |
| 8 | uint32 | 电机侧定向计数 | counts |
| 12 | uint32 | 关节侧定向计数 | counts |
| 16 | uint32 | 电机编码器原始值 | counts |
| 20 | uint32 | FOC 最近周期数 | cycles |
0xF4 速度环与转矩状态
DATA 长度 44 字节：
| 偏移 | 类型 | 名称 | 单位 |
|---|---|---|---|
| 0 | float | 速度目标 | rad/s |
| 4 | float | 速度反馈 | rad/s |
| 8 | float | 速度环比例项 | Nm |
| 12 | float | 速度环积分项 | Nm |
| 16 | float | 控制器转矩命令 | Nm |
| 20 | float | 扰动估计 | Nm |
| 24 | float | 扰动补偿 | Nm |
| 28 | float | 转矩前馈 | Nm |
| 32 | float | 输出转矩命令 | Nm |
| 36 | float | 滤波后转矩命令 | Nm |
| 40 | uint8 | 转矩限幅标志 | 0/1 |
| 41 | uint8 | 电压限幅标志 | 0/1 |
| 42 | uint8[2] | 保留 | 固定补零 |
0xF5 位置环状态
DATA 长度 64 字节：
| 偏移 | 类型 | 名称 | 单位 |
|---|---|---|---|
| 0 | float | 目标位置 | deg |
| 4 | float | 反馈位置 | deg |
| 8 | float | 反馈速度 | rad/s |
| 12 | float | 位置误差 | rad |
| 16 | float | 抱闸占空比 | pu |
| 20 | float | 位置环比例项 | - |
| 24 | float | 位置环积分项 | - |
| 28 | float | 位置环微分项 | - |
| 32 | float | 积分累计值 | - |
| 36 | float | 保留 | 固定 0 |
| 40 | float | 限幅前输出 | - |
| 44 | float | 限幅后输出 | - |
| 48 | float | 速度前馈 | rad/s |
| 52 | float | 速度命令 | rad/s |
| 56 | float | 保留 | 固定 0 |
| 60 | uint8 | 振动滤波使能 | 0/1 |
| 61 | uint8 | 输出限幅标志 | 0/1 |
| 62 | uint8 | 积分限幅标志 | 0/1 |
| 63 | uint8 | 到位标志 | 0/1 |
0xF6 轨迹状态
DATA 长度 40 字节：
| 偏移 | 类型 | 名称 | 单位 |
|---|---|---|---|
| 0 | float | 目标位置 | deg |
| 4 | float | 反馈位置 | deg |
| 8 | float | 位置误差 | deg |
| 12 | float | 速度命令 | rpm |
| 16 | float | 电机速度 | rpm |
| 20 | float | 目标位置 | rad |
| 24 | float | 轨迹位置 | rad |
| 28 | float | 速度命令 | rad/s |
| 32 | float | 保留 | 固定 0 |
| 36 | uint8 | 到位标志 | 0/1 |
| 37 | uint8 | 轨迹结果 | 4 未就绪，5 完成 |
| 38 | uint8 | 轨迹完成标志 | 0/1 |
| 39 | uint8 | 保留 | 固定 0 |
0xF7 保留遥测
DATA 长度 4 字节，当前为 float 0.0。
0xF8 CAN FIFO0 原始帧透传
DATA 长度为 4 + N，其中 1 <= N <= 64：
| 偏移 | 类型 | 名称 | 说明 |
|---|---|---|---|
| 0..1 | uint16 | CAN_ID | CAN 标识符低 16 位 |
| 2 | uint8 | BUS_FORMAT | 总线数据格式 |
| 3 | uint8 | PAYLOAD_LEN | 后续原始数据长度 N |
| 4..N | bytes | PAYLOAD | 原始数据 |
接入建议
为保证集成软件具备良好的兼容性和现场稳定性，建议按以下方式实现：
- 接收端应按字节流状态机查找
0xAB，读取LEN后再等待完整帧和校验字节。 - 校验失败的帧直接丢弃，不要尝试解析
DATA。 - 参数和命令流程应设置超时重试；重试时以
0x00应答中的校验字段确认对应关系。 - 上位应用应动态读取设备信息、参数数量和命令数量，不建议把具体参数表或命令表写死在软件中。
- 遥测字段可能随产品系列和版本扩展，上位应用应保留未知字段的兼容处理能力。