木鸢通讯协议

修改日志

日期	版本	维护者	修改记录
2021.3.15	V1.0	Ligcox	首次发布
2021.11.7	V2.0	Ligcox	针对的BCP for ROS2进行修改
2022.8.15	V2.1	Ligcox	移植木鸢通讯手册pdf文档至reStructuredText

声明

木鸢通讯协议是一个针对RMU定制的上下位机通讯协议， 木鸢通讯协议包含在BTPDM、Bubble等开源项目中，鼓励在尊重著作权基础上对木鸢通讯协议进行使用、修改和二次发布。

1 前言

为了适应Robomaster赛场多种数据类型的传输，保证高效的通信效率，MCU与上位机之间的数据传输遵守BCP（Birdiebot Communication Protocol，Birdiebot通讯协议）格式。 BCP在确保通信高效、源码简单、可移植性高的基础上，实现数据正确性判断，有效避免数据传输过程中出现的错误数据的错误解析。 BCP提供对RMU机器人多种类型功能的操作，能够在不同架构下稳定运行，实现RMU赛场的数据传输和解析需求。

木鸢通讯协议在实现过程中参考了 匿名通讯协议 和 RoboMaster裁判系统串口协议 。 通过木鸢上位机和其他拓展工具，能够快速查看机器人状态和交互信息，仅需编写相应的下位机程序接收BCP数据，即可实现对不同种类机器人的控制。

2 通讯协议介绍

2.1 通讯帧基本格式

	帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
	HEAD	D_ADDR	ID	LEN	DATA	SC	AC
数据长度	1	1	1	1	N	1	1
备注	固定值0xFF	数据发送的接收机器人 参考硬件地址定义	操作功能码	数据内容字段的长度	具体数据内容， N=数据长度	计算方法附后

DATA 数据内容中的数据，采用小端模式，低字节在前，高字节在后。

为了提高数据传输的效率，当有浮点数类型数据需要传输时，根据数据类型的特点，适当截取小数点后固定几位,将浮点数转化成整数类型进行传输，可缩短数据长度，并且避免浮点数传输时发生异常，解析成非法浮点数。类似数据会在协议中标注，如 A*100，就代表将数据 A 只保留两位小数，乘以100进行传输，下位机使用时将收到的数据除以100即可。

• 和校验 SUM_CHECK 计算方法：从帧头0xFF字节开始，一直到 DATA 区结束，对每一字节进行累加操作，只取低8位。

• 附加校验 ADD_CHECK 计算方法： 计算和校验时，每进行一字节的加法运算，同时进行一次 SUM_CHECK 的累加操作，只取低8位。

• 校验计算示例： 假设数据帧缓存为 data_buf 数组，0xFF存放于数组起始位置，那么 data_buf[3] 存放的是数据长度，校验程序如下：

def sumcheck_cal(self):
    sumcheck = 0
    addcheck = 0
    for i in [(k, v) for k, v in self.INFO.items()][:-3]:
        sumcheck += i[1]
        addcheck += sumcheck

    for i in self.INFO["DATA"]:
        sumcheck += i
        addcheck += sumcheck

    self.INFO["SUM_CHECK"] = int(sumcheck) & 0XFF
self.INFO["ADD_CHECK"] = int(addcheck) & 0XFF

2.2 基本配置

2.2.1 COM设置

在Manifold2-G Ubuntu18.04条件下，UART0在系统内核中对应的设备是ttyS0，UART1对应的设备是ttyTHS2。Manifold2-G推荐使用UART1作为BCP配置的COM口。 Jetson开发套件推荐使用40pin引脚的6、8口配置的ttyTHS0作为BCP配置的COM口

2.2.2 波特率配置

在使用BCP时，需要将波特率调整为与MCU配置相同，默认为921600，但推荐不应小于115200。

3 数据帧介绍

3.1 心跳数据

为保证上位机与下位机正常通讯，在BCP开始工作时，会始终向下位机发送心跳数据。心跳数据默认每隔50ms发送，数据内容为0/1交替发送。

当下位机一段时间无法收到心跳数据时，说明MCU与上位机连接以断开，应执行相应操作。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0xF0	1	格式如下	程序计算	程序计算

心跳数据定义如下：

数据域	heartbeat
数据类型	UINT8
数据内容	交替发送0/1

3.2 底盘数据

底盘数据提供了上位机与MCU需要控制的信息。

3.2.1 速度方式控制

当上位机发送至MUC时，MUC应设置底盘x,y方向速度及底盘朝向。

当MUC发送至上位机时，表示当前机器人x,y方向速度及底盘朝向。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x10	6	格式如下	程序计算	程序计算

速度方式控制数据定义如下：

数据域	chassis_vx	chassis_vy	chassis_angle
数据类型	INT8	INT8	INT32
数据内容	底盘x轴速度	底盘y轴速度	底盘朝向位置，放大100倍发送，4长度

3.2.2 里程计方式控制

当上位机发送至MUC时，MUC应设置底盘期望的x,y坐标及底盘朝向。

当MUC发送至上位机时，表示当前机器人的x,y坐标及底盘朝向。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x11	28	格式如下	程序计算	程序计算

里程计方式控制数据，均放大10000倍，4长度，定义如下：

数据域	odom_position_x	odom_position_y	odom_position_z	odom_orientation_x	odom_orientation_y	odom_orientation_z	odom_orientation_w
数据类型	INT32	INT32	INT32	INT32	INT32	INT32	INT32
数据内容	底盘x坐标	底盘y坐标	底盘z坐标	底盘朝向四元数x	底盘朝向四元数y	底盘朝向四元数z	底盘朝向四元数w

3.2.3 角/线速度方式控制

当MUC发送至上位机时，表示当前机器人的x,y,z方向的线速度及x,y,z轴的角速度。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x12	24	格式如下	程序计算	程序计算

角/线速度方式控制数据，均放大10000倍，4长度，定义如下：

数据域	chassis_target_linear_x	chassis_target_linear_y	chassis_target_linear_z	chassis_target_angular_x	chassis_target_angular_y	chassis_target_angular_z
数据类型	INT32	INT32	INT32	INT32	INT32	INT32
数据内容	底盘x方向线速度	底盘y方向线速度	底盘z方向线速度	底盘x轴角速度	底盘y轴角速度	底盘z轴角速度

3.3 云台数据

云台数据提供了上位机与MCU需要的云台控制信息。

3.3.1 欧拉角rpy方式控制

当上位机发送至MUC时，MUC应控制云台偏转到相应的角度。

当MUC发送至上位机时，表示当前机器人云台朝向。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x20	13	格式如下	程序计算	程序计算

欧拉角rpy方式控制数据定义如下：

数据域	gimbal_ctrl_mode	gimbal_yaw	gimbal_pitch	gimbal_roll
数据类型	INT8	INT32	INT32	INT32
数据内容	控制方式	云台yaw偏转角度	云台pitch偏转角度	云台roll偏转角度
备注	0为绝对角度控制	放大1000倍发送，4长度	放大1000倍发送，4长度	放大1000倍发送，4长度
	1为相对角度控制

3.3.2 四元数方式控制

TODO

3.4 裁判系统数据

裁判系统数据主要由裁判系统发送至MUC，MUC通过BCP转发至上位机，裁判系统详细数据定义参考 RoboMaster裁判系统串口协议。

3.4.1 比赛类型数据

该数据帧为当前比赛状态数据。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x30	9	格式如下	程序计算	程序计算

比赛状态数据定义如下：

数据域	game_type	game_progress	stage_remain_time
数据类型	INT8	INT8	INT16
数据内容	比赛类型	当前比赛阶段	当前阶段剩余时间
备注			放大100倍发送，2长度

3.4.2 机器人血量数据

该数据帧为当前比赛机器人血量数据。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x31	36	格式如下	程序计算	程序计算

血量数据定义如下：

数据域	red_1_robot_HP	red_2_robot_HP	red_3_robot_HP	red_4_robot_HP	red_5_robot_HP	red_7_robot_HP	red_outpost_HP	red_base_HP	blue_1_robot_HP	blue_2_robot_HP	blue_3_robot_HP	blue_4_robot_HP	blue_5_robot_HP	blue_7_robot_HP	blue_outpost_HP	blue_base_HP
数据类型	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16	INT16
数据内容	红1英雄机器人血量	红2工程机器人血量	红3步兵机器人血量	红4步兵机器人血量	红5步兵机器人血量	红7哨兵机器人血量	红方前哨战血量	红方基地血量	蓝1英雄机器人血量	蓝2工程机器人血量	蓝3步兵机器人血量	蓝4步兵机器人血量	蓝5步兵机器人血量	蓝7哨兵机器人血量	蓝方前哨站血量	蓝方基地血量

3.4.3 增益区数据

该数据帧为ICRA人工智能挑战赛加成与惩罚区状态。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x32	16	格式如下	程序计算	程序计算

增益区数据定义如下：

数据域	F1_zone_status	F1_zone_buff_debuff_status	F2_zone_status	F2_zone_buff_debuff_status	F3_zone_status	F3_zone_buff_debuff_status	F4_zone_status	F4_zone_buff_debuff_status	F5_zone_status	F5_zone_buff_debuff_status	F6_zone_status	F6_zone_buff_debuff_status	red1_bullet_left	red2_bullet_left	blue1_bullet_left	blue2_bullet_left
数据类型	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8	INT8
数据内容	F1激活状态	F2激活状态	F3激活状态	F4激活状态	F5激活状态	F6激活状态	F1状态信息	F2状态信息	F3状态信息	F4状态信息	F5状态信息	F6状态信息	红方1号剩余弹量	红方2号剩余弹量	蓝方1号剩余弹量	蓝方2号剩余弹量

3.4.4 机器人颜色数据

该数据帧为当前机器人的颜色信息。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x33	1	格式如下	程序计算	程序计算

机器人颜色数据定义如下：

数据域	game_mode
数据类型	INT8
数据内容	当前机器人颜色信息，蓝色方为0，红色方为1，未定义为2

3.4.5 当前机器人位置信息

该数据帧裁判系统下发至MUC的信息，通过BCP转发。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x34	15	格式如下	程序计算	程序计算

机器人位置信息数据定义如下：

数据域	target_position_x	target_position_y	target_position_z	commd_keyboard	target_robot_ID
数据类型	INT32	INT32	INT32	UINT8	UINT16
数据内容	目标x位置坐标	目标y位置坐标	目标z位置坐标	发送指令时，云台手按下的键盘信息	要作用的目标机器人ID

3.4.6 雷达发送目标位置信息

该数据帧通过上位机发至MUC，MUC转发至裁判系统，通过BCP转发。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	0x08	0x35	10	格式如下	程序计算	程序计算

雷达发送目标位置信息数据定义如下：

数据域	target_robot_ID	target_position_x	target_position_y
数据类型	UINT16	INT32	INT32
数据内容	目标机器人ID	目标x位置坐标	目标y位置坐标

3.5 发射机构数据

该数据帧为当前发射机构数据。

当上位机发送至MUC时，MCU应控制发射机构按照射速进行发射。

当MCU发送至上位机时，表示当前机器人是否发射、发射的射速信息及剩余发弹量。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x40	7	格式如下	程序计算	程序计算

比赛状态数据定义如下：

数据域	is_shoot	bullet_vel	remain_bullet
数据类型	UINT8	INT32	INT16
数据内容	发射机构是否发射	弹丸发射速度	剩余发弹量

3.6 模式控制

3.6.1 控制模式

该数据帧为当前上位机执行的任务模式控制。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0x50	1	格式如下	程序计算	程序计算

控制模式数据定义如下：

数据域	mode_ctrl
数据类型	UINT8
数据内容	当前控制模式，空任务为0，自瞄模式为1，能量机关模式为2

3.7 故障信息

Attention

在后续的Bubble版本中，可能对机器人状态发布的BCP部分发生小范围的改动

该数据帧为当上位机模块发生异常时，应该向MUC发送的当前错误信息。

帧头	目标地址	功能码	数据长度	数据内容	和校验	附加校验
0xFF	机器人编号	0xE0	3	格式如下	程序计算	程序计算

故障信息数据定义如下：

数据域	error_level	error_module	error_code
数据类型	UINT8	UINT8	UINT8
数据内容	故障等级	故障模组	故障码

附录I 目标地址表

目标地址字段	目标地址名称	目标地址
broadcast	广播	0x00
mainfold	上位机	0x01
sentry_up	哨兵机器人上云台	0x02
sentry_down	哨兵机器人下云台	0x03
infantry	步兵机器人	0x04
engineer	工程机器人	0x05
hero	英雄机器人	0x06
air	空中机器人	0x07
radar	雷达站	0x08
gather	视觉采集台	0x09
standard	AI机器人/全自动步兵机器人	0x10

附录II 功能码表

功能码字段	功能码名称	功能码
chassis	速度方式控制	0x10
chassis_odom	里程计方式控制	0x11
chassis_ctrl	角/线速度方式控制	0x12
gimbal	欧拉角rpy方式控制	0x20
game_status	比赛类型数据	0x30
robot_HP	机器人血量数据	0x31
ICRA_buff_debuff_zone	增益区数据	0x32
game_mode	机器人颜色数据	0x33
robot_command	机器人位置信息	0x34
client_map_command	雷达发送目标位置信息	0x35
barrel	发射机构数据	0x40
manifold_ctrl	控制模式	0x50
mode	模式控制	0x60
dev_error	故障信息	0xE0
heartbeat	心跳数据	0xF0