MAVLink 协议解析之XML定义篇

文章目录

1 MAVLink XML 文件的基本结构
2 message
3 enum

1 MAVLink XML 文件的基本结构

下面的代码块是 mavlink 消息定义的 xml 数据文档

代码块 1

<?xml version="1.0"?>
<mavlink><version>3</version><dialect>0</dialect><enums><enum name="aaaa"></enum><enum name="bbbb"></enum></enums><messages><message id='1' name="somename"></message><message id="2" name="anothername"></message></messages>
</mavlink>

xml 结构主要可以分为版本信息块、enums包括的枚举数据定义块以及messages 消息定义块。版本信息块如下

<version>3</version>
<dialect>0</dialect>

enums 枚举数据定义块是<enums></enums> 标签包括的内容，其中包括了很多通过<enum></enum>标签定义的数据。
messages 消息定义块是<messages></messages> 标签包括的内容，其中包括了很多通过<message></message> 定义的数据。

对于<enum></enum>和<message></message>内部的具体结构在 mavschema.xsd 中有定义。这里我们专注于 common.xml 的剖析，跳过mavschema.xsd 并不会影响我们对 common.xml 的理解。
下面分别分析 <enum></enum> 的结构和<message></message> 的结构。由于 <message></message> 包含了<enum></enum> 中的内容所以，这里先分析<message></message> 。

2 message

这里我们摘取名为SYS_STATUS 的 message 进行分析

代码块 2

    <message id="1" name="SYS_STATUS"><description>The general system state. If the system is following the MAVLink standard, the system state is mainly defined by three orthogonal states/modes: The system mode, which is either LOCKED (motors shut down and locked), MANUAL (system under RC control), GUIDED (system with autonomous position control, position setpoint controlled manually) or AUTO (system guided by path/waypoint planner). The NAV_MODE defined the current flight state: LIFTOFF (often an open-loop maneuver), LANDING, WAYPOINTS or VECTOR. This represents the internal navigation state machine. The system status shows whether the system is currently active or not and if an emergency occurred. During the CRITICAL and EMERGENCY states the MAV is still considered to be active, but should start emergency procedures autonomously. After a failure occurred it should first move from active to critical to allow manual intervention and then move to emergency after a certain timeout.</description><field type="uint32_t" name="onboard_control_sensors_present" enum="MAV_SYS_STATUS_SENSOR" display="bitmask" print_format="0x%04x">Bitmap showing which onboard controllers and sensors are present. Value of 0: not present. Value of 1: present.</field><field type="uint32_t" name="onboard_control_sensors_enabled" enum="MAV_SYS_STATUS_SENSOR" display="bitmask" print_format="0x%04x">Bitmap showing which onboard controllers and sensors are enabled:  Value of 0: not enabled. Value of 1: enabled.</field><field type="uint32_t" name="onboard_control_sensors_health" enum="MAV_SYS_STATUS_SENSOR" display="bitmask" print_format="0x%04x">Bitmap showing which onboard controllers and sensors have an error (or are operational). Value of 0: error. Value of 1: healthy.</field><field type="uint16_t" name="load" units="d%">Maximum usage in percent of the mainloop time. Values: [0-1000] - should always be below 1000</field><field type="uint16_t" name="voltage_battery" units="mV">Battery voltage, UINT16_MAX: Voltage not sent by autopilot</field><field type="int16_t" name="current_battery" units="cA">Battery current, -1: Current not sent by autopilot</field><field type="int8_t" name="battery_remaining" units="%">Battery energy remaining, -1: Battery remaining energy not sent by autopilot</field><field type="uint16_t" name="drop_rate_comm" units="c%">Communication drop rate, (UART, I2C, SPI, CAN), dropped packets on all links (packets that were corrupted on reception on the MAV)</field><field type="uint16_t" name="errors_comm">Communication errors (UART, I2C, SPI, CAN), dropped packets on all links (packets that were corrupted on reception on the MAV)</field><field type="uint16_t" name="errors_count1">Autopilot-specific errors</field><field type="uint16_t" name="errors_count2">Autopilot-specific errors</field><field type="uint16_t" name="errors_count3">Autopilot-specific errors</field><field type="uint16_t" name="errors_count4">Autopilot-specific errors</field></message>

可以看到 message 的结构比较简单，主要由<description> 段和<field> 组成。<description> 是对这个消息的描述，<field>是消息中所包含数据的每个域的具体说明，包含域的数据类型（type），域的数据名称（name)，及对该域数据的描述(嵌入在<field></field>标签中的文本)。可以看到<field> 中还有enum 、display、print_format 和 units等其他属性。enum属性的内容即上面通过<enum></enum> 标签定义的枚举数据类型，例如onboard_control_sensors_present 中引用的名称是MAV_SYS_STATUS_SENSOR 枚举数据类型。display 定义这个域主要是用来显示给用户的，print_format 则指定了打印格式。这个message 实际上就是传输中的数据的具体结构，message中定义的每个field 在数据中一定存在，且大小按其type 域指定的数据类型相一致。

3 enum

下面来剖析enum 节点，这里以上一节提到的MAV_SYS_STATUS_SENSOR为例来说明。

代码块 3

<enum name="MAV_SYS_STATUS_SENSOR"><description>These encode the sensors whose status is sent as part of the SYS_STATUS message.</description><entry value="1" name="MAV_SYS_STATUS_SENSOR_3D_GYRO"><description>0x01 3D gyro</description></entry><entry value="2" name="MAV_SYS_STATUS_SENSOR_3D_ACCEL"><description>0x02 3D accelerometer</description></entry><entry value="4" name="MAV_SYS_STATUS_SENSOR_3D_MAG"><description>0x04 3D magnetometer</description></entry><entry value="8" name="MAV_SYS_STATUS_SENSOR_ABSOLUTE_PRESSURE"><description>0x08 absolute pressure</description></entry><entry value="16" name="MAV_SYS_STATUS_SENSOR_DIFFERENTIAL_PRESSURE"><description>0x10 differential pressure</description></entry><entry value="32" name="MAV_SYS_STATUS_SENSOR_GPS"><description>0x20 GPS</description></entry><entry value="64" name="MAV_SYS_STATUS_SENSOR_OPTICAL_FLOW"><description>0x40 optical flow</description></entry><entry value="128" name="MAV_SYS_STATUS_SENSOR_VISION_POSITION"><description>0x80 computer vision position</description></entry><entry value="256" name="MAV_SYS_STATUS_SENSOR_LASER_POSITION"><description>0x100 laser based position</description></entry><entry value="512" name="MAV_SYS_STATUS_SENSOR_EXTERNAL_GROUND_TRUTH"><description>0x200 external ground truth (Vicon or Leica)</description></entry><entry value="1024" name="MAV_SYS_STATUS_SENSOR_ANGULAR_RATE_CONTROL"><description>0x400 3D angular rate control</description></entry><entry value="2048" name="MAV_SYS_STATUS_SENSOR_ATTITUDE_STABILIZATION"><description>0x800 attitude stabilization</description></entry><entry value="4096" name="MAV_SYS_STATUS_SENSOR_YAW_POSITION"><description>0x1000 yaw position</description></entry><entry value="8192" name="MAV_SYS_STATUS_SENSOR_Z_ALTITUDE_CONTROL"><description>0x2000 z/altitude control</description></entry><entry value="16384" name="MAV_SYS_STATUS_SENSOR_XY_POSITION_CONTROL"><description>0x4000 x/y position control</description></entry><entry value="32768" name="MAV_SYS_STATUS_SENSOR_MOTOR_OUTPUTS"><description>0x8000 motor outputs / control</description></entry><entry value="65536" name="MAV_SYS_STATUS_SENSOR_RC_RECEIVER"><description>0x10000 rc receiver</description></entry><entry value="131072" name="MAV_SYS_STATUS_SENSOR_3D_GYRO2"><description>0x20000 2nd 3D gyro</description></entry><entry value="262144" name="MAV_SYS_STATUS_SENSOR_3D_ACCEL2"><description>0x40000 2nd 3D accelerometer</description></entry><entry value="524288" name="MAV_SYS_STATUS_SENSOR_3D_MAG2"><description>0x80000 2nd 3D magnetometer</description></entry><entry value="1048576" name="MAV_SYS_STATUS_GEOFENCE"><description>0x100000 geofence</description></entry><entry value="2097152" name="MAV_SYS_STATUS_AHRS"><description>0x200000 AHRS subsystem health</description></entry><entry value="4194304" name="MAV_SYS_STATUS_TERRAIN"><description>0x400000 Terrain subsystem health</description></entry><entry value="8388608" name="MAV_SYS_STATUS_REVERSE_MOTOR"><description>0x800000 Motors are reversed</description></entry><entry value="16777216" name="MAV_SYS_STATUS_LOGGING"><description>0x1000000 Logging</description></entry><entry value="33554432" name="MAV_SYS_STATUS_SENSOR_BATTERY"><description>0x2000000 Battery</description></entry><entry value="67108864" name="MAV_SYS_STATUS_SENSOR_PROXIMITY"><description>0x4000000 Proximity</description></entry><entry value="134217728" name="MAV_SYS_STATUS_SENSOR_SATCOM"><description>0x8000000 Satellite Communication </description></entry><entry value="268435456" name="MAV_SYS_STATUS_PREARM_CHECK"><description>0x10000000 pre-arm check status. Always healthy when armed</description></entry><entry value="536870912" name="MAV_SYS_STATUS_OBSTACLE_AVOIDANCE"><description>0x20000000 Avoidance/collision prevention</description></entry></enum>

可以看出每个<enum></enum>中包括了很多的<entry></entry> ，每条<entry></entry>可以看作枚举的一个值，value 属性对应于值的具体大小，name 则可以看成是值的别名。
可以看出enum 类型不过是普通的数据型数据，那为什么要把这些数据类型单独拿出来定义呢。一个原因是，每个值都有确定的含义，假想两个系统之间进行通讯，虽然采用同样的协议，但是如果对值的约定不一样，这边用1 代表四旋翼,那边用1代表固定翼这样显然不匹配。另一个原因是，协议要自洽，尽量在协议文档里把协议的内容都包括进来，避免模糊和歧义。所以关于数值含义的约定也是协议的重要部分，单独列出来可以让协议结构更清晰明确。