总线伺服舵机通信协议¶

1. 串口通信配置¶

2. 数据类型说明¶

串口通讯协议里用到的数据类型 (字节大小，取值范围)

注意事项：

• 舵机通讯协议里面使用的字节序为**小端字节序**，例如一个uint16_t的数值4660，它的十六进制表示为0x1234。在发送/接收时，低位字节在前，高位字节在后，即以0x34 0x12形式发送。

计算机电路先处理低位字节，效率比较高，所以在大部分的MCU里面（例如STM32），默认字节序也是**小端字节序**。

拓展阅读: 理解字节序 大端字节序和小端字节序

3. 舵机控制指令¶

总线伺服舵机共支持17种舵机控制指令。其中12种为通用指令，余下5种指令仅限于***磁编码系列舵机***

通用指令

特定指令，仅限于***磁编码系列舵机***

注意事项：

1. 所有的舵机指令都是针对单个舵机的。
2. 批量读/写针对的都是单个舵机的所有的用户自定义数据，而不是所有的舵机。
3. 发送控制指令之前，请确保串联在一起的舵机每个舵机的ID号都不一样。
4. 批量读取跟批量写入针对的都是用户自定义参数区块。

4. 数据包¶

4.1 请求数据包¶

4.2 响应数据包¶

请求数据包跟响应数据包数据结构的唯一区别就在于前两个字节的标识符。

注意事项：

1. 封包内容的第一个字节，往往是舵机的ID号，舵机的ID号取值范围为[0, 254]​ ，255是舵机广播地址。
2. 字节序号是从0开始算的。
3. 请求包的cmd_id 跟响应包的cmd_id 一致。
4. 响应数据的接收流程。

如果你需要自己写舵机的通讯协议，可参考的响应数据包获取流程如下：

响应数据包数据读取伪代码

1. 读取帧头：读取数据帧0x05 0x1c 如果不匹配就继续向下读，直到匹配。

2. 读取控制指令 cmd_id：读入下一个字节赋值给cmd_id，检查ID是否在[1, 10]​之间。

3. 读取字节长度n ：读入下一个字节赋值给n。

4. 读取数据包的内容content：读入后续的连续n个字节，赋值给content。

5. 读取校验码checksum ：读取一个字节，赋值给checksum，并验证checksum 是否正确。

6. 数据包的样例可以参阅#5.1. <指令>舵机通讯检测， #8.1<指令>设置舵机角度 等。

5. 舵机通讯检测¶

5.1 <指令>舵机通讯检测¶

检查舵机是否在线，就需要用到PING指令。PING数据包的内容部分是舵机的ID。

如果ID号的舵机存在且在线，总线伺服舵机在接收到PING指令时，会发送一个响应包。如果ID号的舵机不存在或者掉线，就不会有舵机发送响应数据包。在系统实现时，可以设置一个最大等待时间timeout , 如果等待超过timeout ms 就认为该ID号的舵机不在线。

5.1.1 请求包内容格式¶

5.1.2 响应包内容格式¶

5.1.3 数据包示例¶

ping一下3号舵机

请求数据包

0x12 0x4c 0x01 0x01 0x03 0x63

功能描述 检查一下3号舵机是否在线。

这就需要**PING**（舵机通讯检测）一下编号为3的总线伺服舵机。

• PING指令对应的指令ID cmd_id = 0x01

• 数据包的内容因为只有舵机的IDservo_id = 0x03，所以数据包内容的字节长度n = 0x01

• 计算校验和checksum = (0x12 + 0x4c + 0x01 + 0x01 + 0x03)%256 = 99 = 0x63

接下来分析一下回传数据，假设舵机存在并在线，返回的字节数据为

0x05 0x1c 0x01 0x01 0x03 0x26

• 0x05 0x1c : 响应头标识符

• 0x01: cmd_id 这个包是PING指令的响应数据包

• 0x01: n 响应数据包内容的长度是１

• 0x03: servo_id 舵机的ID是3

• 0x26: checksum 校验和

我们拿到响应数据之后，要通过计算校验和checksum判断响应数据包的合法性。

(0x05 + 0x1c + 0x01 + 0x01 + 0x03)%256 = 38 = 0x26

校验和相等, 所以响应包的数据为合法。

6. 舵机参数¶

舵机参数整体上分为用户只读参数（舵机型号，舵机状态等）和用户自定义参数两大类。

6.1. 舵机参数设置/修改¶

6.1.1. <指令>用户自定义数据重置¶

6.1.1.1. 请求包内容格式¶

6.1.1.2. 响应包内容格式¶

6.1.2. <指令>舵机数据读取¶

6.1.2.1. 请求包内容格式¶

6.1.2.2. 响应包内容格式¶

6.1.3. <指令>用户自定义数据写¶

6.1.3.1. 请求包内容格式¶

6.1.3.2. 响应包内容格式¶

6.2. 舵机只读参数¶

舵机只读参数是指用户只能读取不能写入的数值。只读参数包括舵机当前的电气状态，舵机工作状态以及舵机的自身信息。

6.2.1. 舵机只读参数列表¶

注意事项：

1. 舵机序列号(serial_number)并不是舵机ID，它是舵机的唯一识别符。

2. 部分字段会在后文做详细介绍。

3. 温度输出值与实际温度需要做转换，如下为转换公式（本文有关温度值转换公式同如下）

• 以上为50-79℃ 温度/ADC参照表

6.2.2. <参数>舵机工作状态¶

6.3. 舵机用户自定义参数¶

6.3.1. 舵机用户自定义参数列表¶

注意事项：

1. 舵机用户自定义参数列表里面的参数均可读可写。

2. data_id 只是参数的ID号，并不是寄存器地址。

3. 角度的单位是0.1度 ，例如角度值90.5度，转换为0.1度的意思就是将角度原数值乘10，90.5 * 10 = 905 。

4. 部分字段会在后文做详细介绍。

5. 用户自定义区块的总的字节数为32 ，批量读写指令操作的就是这部分数据。

6. 推荐通过上位机软件进行用户参数设置。

6.3.2. <参数>响应开关¶

此项设置同时具备两个功能，用于控制在轮式模式与角度控制模式下，舵机指令是否可以中断(interruptable)，以及是否产生反馈数据。

注意事项：

1. 部分舵机指令，是否有返回数据是可选的。响应开关里面定义的是否有反馈数据指的就是这部分的指令。并不是所有的指令都没有反馈数据。
2. 当设置为0x01的时候，新的指令添加到等候队列里，等候队列的长度是1，需要自己在程序里面维护一个队列。当新的控制指令超出了缓冲区的大小后，新添加的指令被忽略。

6.3.3. <参数>舵机ID¶

舵机的ID号，取值范围是[0, 254]​

注意事项：

1. 舵机的ID号初始默认设置为0。

2. 相同ID号的舵机不能串联在一起，串联的舵机每一个都需要独立分配ID。（注：相同ID的舵机串联可能会引起上位机卡死，使用时请注意。）

3. 可以通过舵机上位机修改舵机ID号，修改ID号的时候， 一次就连一个舵机。

4. 0xFF=255 号为广播地址，不能赋值给舵机。

6.3.4. <参数>波特率选项¶

串口通讯的波特率选项，取值范围 [0x01,0x08]

注意事项：

1. 波特率设置时即生效。
2. 默认波特率为115200。
3. 这里是波特率选项，而不是波特率的实际的数值。

6.3.5. <参数>舵机堵转保护模式¶

这里的舵机堵转保护模式指的是当发生舵机堵转时，用什么样的策略来应对。

注意事项：

1. 释放舵机锁力 的意思是，不再驱动舵机维持在一个特定的角度，此时可以自由转动舵机的主轴。

6.3.6. <参数>舵机启动加速度处理开关¶

此选项用于设置，舵机在轨迹规划时，选取什么样的控制算法。

注意事项：

1. 舵机目前必须设置启用加速度处理，即只能设置0x01这个选项。
2. 舵机速度控制算法 根据时间t推算加速度，行程前t/4加速，行程中间t/2保持匀速，行程后t/4减速。

6.3.7. <参数>舵机上电锁力开关¶

注意事项：

1. 上电舵机保持锁力 的意思是，舵机上电时，读取舵机当前所在的角度，并让舵机维持在这一角度。
2. 释放舵机锁力 的意思是，不再驱动舵机维持在一个特定的角度，此时可以自由转动舵机的主轴。

6.3.8. <参数>轮式模式刹车开关¶

轮式模式下，舵机停止时，设置是否释放舵机锁力。

6.3.9. <参数>角度限制开关¶

只有打开角度限制开关，舵机角度限制相关的参数才会有效。

注意事项：

1. 建议在主控上做舵机角度约束。

6.3.10. <参数>上电首次缓慢执行¶

舵机在刚开始上电时，执行第一个角度控制指令时，选择是否开启缓慢执行模式。

举例来讲，机械臂刚开始上电时，需要旋转到初始位置，假如原先设定的执行周期是100ms，开启这个模式之后，执行周期会被修改为 上电首次执行时间 。

7. 轮式模式¶

7.1. <指令>轮式模式控制¶

7.1.1. 请求包内容格式¶

@param method

执行方式，是一个字节长度的数值。

bit[7] 用于设定舵机的旋转方向，

• bit[7]=0 舵机逆时针旋转
• bit[7]=1 舵机顺时针旋转

bit[1, 0] 这两个字节用于设定轮式模式的执行方式，

其余的比特位为空余。

@param value

随着执行方式的不同，value就有了不同的含义，

当执行方式为0x00 或0x01 时， value 无意义。

轮式模式控制设置举例

7.1.2. 响应包内容格式(可选)¶

注意事项：

1. 默认没有响应包，只有打开**响应开关**时，才会有响应包。
2. 打开**响应开关**后，舵机在旋转到目标角度之后，才会发送响应包。

7.1.3. 数据包示例¶

8.1.3.1. 持续旋转¶

设置0号舵机逆时针运动，速度300°/s​

请求包数据

0x12 0x4c 0x07 0x06 0x00 0x01 0x2c 0x01 0x00 0x00 0x99 

7.1.3.2. 停止转动¶

设置0号舵机停止转动

请求包数据

0x12 0x4c 0x07 0x06 0x00 0x00 0x00 0x00 0x00 0x00 0x6b 

7.1.3.3 定圈转动¶

设置0号舵机顺时针旋转10圈，速度300°/s​

请求数据包

0x12 0x4c 0x07 0x06 0x00 0x82 0x2c 0x01 0x0a 0x00 0x24 

7.1.3.4 定时运动¶

设置0号舵机顺时针，旋转10000ms，速度300°/s​

请求数据包

0x12 0x4c 0x07 0x06 0x00 0x83 0x2c 0x01 0x10 0x27 0x52 

8. 角度模式¶

8.1. <指令>设置舵机角度¶

8.1.1 请求包内容格式¶

8.1.2 响应包内容格式(可选)¶

注意事项：

1. 默认没有响应包，只有打开**响应开关**的时候，才会有响应包。

2. 打开**响应开关**后，舵机在旋转到目标角度后，才会发送响应包。

3. 在通讯时，字节顺序使用的是**小端字节序** 。

要注意两个字节的数据，例如角度angle = 900 = 0x0384，在发送时就变成了0x84 0x03。

8.1.3数据包示例¶

设置2号舵机在500ms内，旋转到90度

请求数据包

0x12 0x4c 0x08 0x07 0x02 0x84 0x03 0xf4 0x01 0x00 0x00 0xeb

• 角度模式控制-设置舵机角度的指令 cmd_id = 0x08
• 舵机ID servo_id = 2 = 0x02
• 舵机的目标角度为90度，但是angle的单位是0.1度，所以 angle = 900= 0x84 0x03
• 时间间隔interval=500 = 0xf4 0x01
• 执行功率一般设置为0power=0x00 0x00
• 字节长度n= 1+2+2+2 = 7 = 0x07
• 校验和 checksum= (0x12 + 0x4c + 0x08 + 0x07 + 0x02 + 0x84 + 0x03 + 0x0F4 + 0x01 + 0x00 + 0x00)%256 = 235 =0xEB

8.2. <指令>读取舵机角度¶

8.2.1. 请求包内容格式¶

8.2.2. 响应包内容格式¶

8.2.3. 数据包示例¶

查询舵机0x00 的角度

请求数据包

0x12 0x4c 0x0a 0x01 0x00 0x69

响应数据包

0x05 0x1c 0x0a 0x03 0x00 0x86 0x03 0xb7

0x86 0x03是当前的舵机角度，解包后是902，转换为角度制就是90.2度。

8.3. <指令>舵机角度控制-指定时间¶

8.3.1 请求包内容格式¶

8.3.2 响应包内容格式(可选)¶

8.3.3 数据包示例¶

设置0号舵机600ms旋转到90度，其中加速时间100ms，减速时间100ms

请求数据包

0x12 0x4c 0x0b 0x0b 0x00 0x84 0x03 0x58 0x02 0x64 0x00 0x64 0x00 0x00 0x00 0x1d

• 角度模式控制-舵机角度控制-指定时间 cmd_id = 0x0b
• 舵机ID servo_id = 0 = 0x00
• 舵机的目标角度为90度，但是angle的单位是0.1度，所以 angle = 900= 0x84 0x03
• 时间间隔interval= 600 = 0x58 0x02
• 加速段的时间accInterval = 100 = 0x64 0x00
• 减速段时间的时间decInterval = 100 = 0x64 0x00
• 执行功率一般设置为0power=0x00 0x00
• 字节长度n = 1+2+2+2+2+2 = 11 = 0x0b
• 校验和 checksum = (0x12 + 0x4c + 0x0b + 0x0b + 0x00 + 0x84 + 0x03 + 0x58 + 0x02 + 0x64 + 0x00 + 0x64 + 0x00 + 0x00 + 0x00)%256 = 29 = 0x1d

8.4. <指令>舵机角度控制-指定速度¶

8.4.1 请求包内容格式¶

8.4.2 响应包内容格式(可选)¶

8.4.3. 数据包示例¶

设置0号舵机以目标速度200°/s旋转到90度，其中加速时间100ms，减速时间100ms

请求数据包

0x12 0x4c 0x0c 0x0b 0x00 0x84 0x03 0xd0 0x07 0x64 0x00 0x64 0x00 0x00 0x00 0x9b

• 角度模式控制-舵机角度控制-指定时间 cmd_id = 0x0c
• 舵机ID servo_id = 0 = 0x00
• 舵机的目标角度为90度，但是angle的单位是0.1度，所以 angle = 900= 0x84 0x03
• 目标速度，单位是0.1°/s，所以targetVelocity = 2000 = 0xd0 0x07
• 加速段的时间accInterval = 100 = 0x64 0x00
• 减速段时间的时间decInterval = 100 = 0x64 0x00
• 执行功率一般设置为0power=0x00 0x00
• 字节长度n = 1+2+2+2+2+2 = 11 = 0x0b
• 校验和 checksum = (0x12 + 0x4c + 0x0c + 0x0b + 0x00 + 0x84 + 0x03 + 0xd0 + 0x07 + 0x64 + 0x00 + 0x64 + 0x00 + 0x00 + 0x00)%256 = 155 = 0x9b

9. 阻尼模式¶

9.1. <指令> 阻尼模式控制¶

9.1.1. 请求包内容格式¶

@param servo_id

如果设置servo_id = 0xFF (广播地址) ，则所有的舵机都会被设置为阻尼模式。

@param power

如果保持功率power设置为0，或者大于功率上限，则按照功率上限处理。

功率上限的设定请参阅舵机用户自定义参数列表

9.1.2. 响应包内容格式(可选)¶

注意事项：

1. 默认没有响应包，只有打开**响应开关**的时候，才会有响应包。
2. 打开**响应开关**后，舵机在旋转到目标角度之后，才会发送响应包。

9.1.3. 数据包示例¶

设置0号舵机的阻尼模式的保持功率为500mW

请求数据包

0x12 0x4c 0x09 0x03 0x00 0xf4 0x01 0x5f 

10. 多圈角度模式¶

注：仅适用于磁编码舵机

10.1. <指令>设置舵机角度¶

10.1.1 请求包内容格式¶

10.1.2 响应包内容格式(可选)¶

10.1.3 数据包示例¶

设置0号舵机在5000ms内，旋转到400度

请求数据包

0x12 0x4c 0x0d 0x0b 0x00 0xa0 0x0f 0x00 0x00 0x88 0x13 0x00 0x00 0x00 0x00 0xc0

• 角度模式控制-设置舵机角度的指令 cmd_id = 0x0d
• 舵机ID servo_id = 0 = 0x00
• 舵机的目标角度为400度，但是angle的单位是0.1度，所以 angle = 4000= 0xa0 0x0f 0x00 0x00
• 时间间隔interval=5000 = 0x88 0x13 0x00 0x00
• 执行功率一般设置为0power = 0x00 0x00
• 字节长度n= 1 + 4 + 4 + 2 = 11 = 0x0b
• 校验和 checksum= (0x12 + 0x4c + 0x0d + 0x0b + 0x00 + 0xa0 + 0x0f + 0x00 + 0x00 + 0x88 + 0x13 + 0x00 + 0x00 0x00 + 0x00)%256 = 192 =0xc0

10.2. <指令>多圈角度控制-指定时间¶

10.2.1 请求包内容格式¶

10.2.2 响应包内容格式(可选)¶

10.2.3. 数据包示例¶

设置0号舵机1200ms旋转到600度，其中加速时间100ms，减速时间100ms

请求数据包

0x12 0x4c 0x0e 0x0f 0x00 0x70 0x17 0x00 0x00 0xb0 0x04 0x00 0x00 0x64 0x00 0x64 0x00 0x00 0x00 0x7e

• 多圈角度控制-指定时间 cmd_id = 0x0e
• 舵机ID servo_id = 0 = 0x00
• 舵机的目标角度为600度，但是angle的单位是0.1度，所以 angle = 6000= 0x70 0x17 0x00 0x00
• 时间间隔interval= 1200 = 0xb0 0x04 0x00 0x00
• 加速段的时间accInterval = 100 = 0x64 0x00
• 减速段时间的时间decInterval = 100 = 0x64 0x00
• 执行功率一般设置为0power=0x00 0x00
• 字节长度n = 1+4+4+2+2+2 = 15 = 0x0f
• 校验和 checksum = (0x12 + 0x4c + 0x0e + 0x0f + 0x00 + 0x70 + 0x17 + 0x00 + 0x00 + 0xb0 + 0x04 + 0x00 + 0x00 + 0x64 + 0x00 + 0x64 + 0x00 + 0x00 + 0x00)%256 = 126 = 0x7e

10.3. <指令>多圈角度控制-指定速度¶

10.3.1 请求包内容格式¶

10.3.2 响应包内容格式(可选)¶

10.3.3. 数据包示例¶

设置0号舵机以目标速度200°/s旋转到600度，其中加速时间100ms，减速时间100ms

请求数据包

0x12 0x4c 0x0f 0x0d 0x00 0x70 0x17 0x00 0x00 0xd0 0x07 0x64 0x00 0x64 0x00 0x00 0x00 0xa0

• 多圈角度控制-指定时间 cmd_id = 0x0f
• 舵机ID servo_id = 0 = 0x00
• 舵机的目标角度为600度，但是angle的单位是0.1度，所以 angle = 6000= 0x70 0x17 0x00 0x00
• 目标速度，单位是0.1°/s，所以targetVelocity = 2000 = 0xd0 0x07
• 加速段的时间accInterval = 100 = 0x64 0x00
• 减速段时间的时间decInterval = 100 = 0x64 0x00
• 执行功率一般设置为0power=0x00 0x00
• 字节长度n = 1+4+2+2+2+2 = 13 = 0x0d
• 校验和 checksum = (0x12 + 0x4c + 0x0f + 0x0d + 0x00 + 0x70 + 0x17 + 0x00 + 0x00 + 0xd0 + 0x07 + 0x64 + 0x00 + 0x64 + 0x00 + 0x00 + 0x00)%256 = 160 = 0xa0

10.4. <指令>读取多圈角度¶

10.4.1. 请求包内容格式¶

10.4.2. 响应包内容格式¶

10.4.3. 数据包示例¶

查询舵机0x00 的角度

请求数据包

0x12 0x4c 0x10 0x01 0x00 0x6f

响应数据包

0x05 0x1c 0x10 0x07 0x00 0x23 0x13 0x00 0x00 0x01 0x00 0x6f 

0x23 0x13 0x00 0x00是当前的舵机角度，解包后是4899，转换为角度制就是489.9度。

0x01 0x00是当前圈数，解包后是1，即为1圈。

10.5. <指令>重设多圈角度¶

10.5.1 请求包内容格式¶

10.5.2 响应包内容格式(可选)¶

注意事项：

重设多圈命令必须在舵机释放状态有效（即不在角度与轮式模式控制下）。

10.5.3. 数据包示例¶

重设0号舵机圈数

请求数据包

0x12 0x4c 0x11 0x01 0x00 0x70

• 多圈角度控制-重设多圈角度 cmd_id = 0x11
• 舵机ID servo_id = 0 = 0x00
• 字节长度n = 1 = 0x01
• 校验和 checksum = (0x12 + 0x4c + 0x11 + 0x01 + 0x00)%256 = 112 = 0x70

11. 原点设置¶

注：仅适用于无刷磁编码舵机V311版本

11.1. <指令>设置当前舵机角度为原点¶

11.1.1. 请求包内容格式¶

11.1.2. 响应包内容格式¶

11.1.3. 数据包示例¶

设置1号舵机当前角度为原点

请求数据包

0x12 0x4c 0x17 0x02 0x01 0x00 0x78

• 设置当前舵机角度为原点 cmd_id = 0x17
• 字节长度 n = 1+1 = 0x02
• 舵机ID servo_id = 1 = 0x01
• 预设值 reset = 0 = 0x00
• 校验和 checksum = (0x12 + 0x4c + 0x17 + 0x02 + 0x01 + 0x00)%256 = 120 = 0x78