mavlink（二）xml文件结构

1. xml文件框架和语法

1.1. 文件结构

MaVLink XML 文件的大致结构如下:

下面列出了主要标签 (所有标签都是可选的):
include: 此标签用于指定语支文件（dialect）中包含的任何其他 xml 文件。

• 通常, 语支文件将include common.xml， 如上所示；
• 可以使用多个<include> </include>标记，以包含多个文件；
• 包含文件的路径可以相对于当前语支文件；
• 不支持嵌套 include 文件 (仅导入顶层 include 中指定的文件)；
• 构建时，生成器工具链将合并/附加所有文件中的枚举，并报告重复的枚举条目和消息；

version: 版本的次要版本号, 包含在 HEARTBEAT消息 mavlink_version 字段

• 对于包含 common.xml 的语支，应删除该标签，以便使用来自 common.xml 的版本号（如果指定，将使用来自顶级文件的版本号）；
• 对于私人自定义的语支文件, 版本号无限制，可任意制定；

dialect: 此标签指定的数字对语支来说是独一无二的。

enums: 可以在此块中定义语支特定的枚举。

messages: 可以在此块中定义特定于语支的消息 。

1.2. 枚举定义

1.2.1. 语法

xml中的enums，用于定义消息中可能用到的一些枚举值, 例如定义错误、状态或模式。 还有一个特别的枚举 MAV_CMD 用于定义MAVLink 命令。

所有枚举都是定义在 <enums>... </enums> 标签块中，而各个枚举类型的具体定义在其内子标签块<enum>...</enum>中。具体的枚举值定义则在<entry>... </entry> 标签中。

比如, LANDING_TARGET_TYPE 消息的定义如下：

<enum>...</enum> 标签内字段:

• name: 枚举类型的名称 (必填)。 这是一系列大写的、以下划线分隔的词；
• description(可选): 描述枚举用途的字符串，即注释；
• entry(可选)：条目 (可以为每个列表指定零或多个条目)，即具体的枚举值定义；
• deprecated(可选)：该标签用以显示已废弃的枚举定义；

<entry>...</entry> 标签内字段:

• name: 枚举值的名称 (必填)。 这是一系列大写的、以下划线分隔的词。
• value(可选)：条目 值 (数字)，即具体枚举值。
• description(可选)：条目的描述，即注释。
• deprecated / wip (可选)：指示枚举已弃用或“正在使用中”。

需要重点关注的是枚举类型中的MAV_CMD定义。详见命令定义一节。

1.2.2. 约束

枚举的主要规则如下：

• 枚举 必须 包括 name 属性。对于相同 name 的所有枚举, 将合并entry;
• 枚举 应当 (非常强烈推荐) 包括 description。 如果枚举（enums）被合并，通常仅使用第一个description;
• 枚举 可以 标记为已弃用;
• 枚举（enums） 必须 至少有一个枚举项（enum）;
• Entries：
  • 必须 具有 name 属性。name 在枚举中（enum）的所有条目中必须是唯一的。按照惯例，该名称应以枚举名称为前缀（例如，枚举 LANDING_TARGET_TYPE 具有条目 LANDING_TARGET_TYPE_LIGHT_BEACON）;
  • 应当 具有 value 属性, 如果分配了该属性, 则在 (合并) 枚举中必须是唯一的。 不分配值则将自动按顺序分配（如果未分配第一个值，则从 1 开始），建议分配值，因为这样可以在范围内添加新条目而不会破坏兼容性;
  • 应当(非常强烈建议) 包括 description 元素;
  • 可以表示位掩码, 在这种情况下, 值将以2的幂递增;
  • 可以标记为已弃用;

不能依赖生成器来完全测试是否符合上述规则

更改名称或删除枚举将使任何使用此枚举的消息与生成的库的旧版本不兼容。 同样，更改枚举条目名称（entry name）或值，或删除枚举条目，将使使用枚举的消息与生成的库的旧版本不兼容。

添加新的枚举条目/值时必须小心，因为这可能会使生成的库不兼容（自动生成entry values可能更改；客户端代码可能无法处理新值）。

如果需要修改枚举，可以如下操作：

• 可以创建新枚举，设置所需的entry。并且，旧的枚举标记为 deprecated。
• 可以更新枚举, 同时迭代语支版本号。

无论哪种情况，枚举的所有用户都需要使用新生成的库进行更新。

枚举很少被删除，因为这可能会破坏与不太可能更新到新版本的旧 MAVLink 1 硬件的兼容性。

1.3. 消息定义

1.3.1. 语法

所有消息都是在<messages> ... </messages>中定义的。 具体消息定义在<message>... </message> 标签块中。 消息有效负载中编码的各个字段是使用<field>...</field>标签块定义。每条消息必须至少有一个field。

例如，以下是对BATTERY_STATUS 消息的定义 （选择了该消息因为它包含了许多主要字段和属性）：

message: 每个消息被 message 标签封装，包含以下属性

• id：是这一消息的索引编号，在所有消息中唯一。
  • 对于 MAVLink 1:
    • 有效数字介于 0 到 255；
    • ID 0-149 和 230-255 为common.xml保留。 语支可以使用180-229 用于自定义消息；
  • 对于 MAVLink 2 :
    • 有效数字介于0-1677215；
    • 255以下所有值都被认为是保留的，除非报文也打算用于 MAVLink 1。 注意 ID 在 MAVLink 1 中很宝贵！
• name：消息名称，代码生成器使用该命名，生成的库中的辅助函数；
• description(可选)：对消息的描述，即注释；
• deprecated / wip (可选)：指示消息已启用或正在使用中；
• extensions (可选)：指示后续字段仅适用于 MAVLink 2，该标记应仅用于已在 MAVLink 2 中扩展的 MAVLink 1 消息 (id < 256)；
• field：消息中的字段，用于消息编码。字段值是它在 GUI 文档中使用的名称/文本字符串（但不通过网络发送）。每条消息必须至少有一个field；
  • type: 类似于 C struct 中的数据类型。可以是有符号或无符号的8、16、32、64字节大小的整数类型（uint8_t/int8_t/uint16_t/int16_t/uint32_t/int32_t/uint64_t/int64_t），也可以是单精度或双精度的浮点类型（float/double），也可以是数组类型（如uint16_t[10]）；
  • name：字段名称 (在代码中使用)；
  • enum(可选)：字段可能的值的枚举名称 (例如：MAV_BATERY_CHRRE_STATE)；
  • units(可选)：filed 字段对应数字的单位；
  • display(可选)：这个字段用来显示给用户的。设置为 display="bitmask" 用于 bitsword 字段 (指示地面站枚举值必须显示为复选框)；
  • print_format(可选)：TBD。
  • default(可选)：TBD。
  • instance: 如果为true，则表示该消息包含特定传感器或电池（例如电池 1、电池 2 等）的信息，并且该字段指示哪个传感器。 默认为false。此字段允许接收方自动关联特定传感器的消息并将它们绘制在同一系列中。
  • invalid：指定可以在字段上设置的值以指示数据无效：如果该字段具有此值，则收件人应忽略该字段。例如，BATTERY_STATUS.current_battery 指定 invalid="-1"，因此不测量供电电流的电池应将 BATTERY_STATUS.current_battery 设置为 -1。

invalid补充说明：在可能的情况下，指示字段无效的值应选择在字段的预期/有效范围之外（如果它不是字段可接受的值，则首选 0）。对于整数，我们通常选择可能的最大值（即 UINT16_MAX、INT16_MAX、UINT8_MAX、UINT8_MAX）。对于浮点数，我们通常选择 invalid="NaN"。

数组表示多个元素，其中一些（或全部）可能需要标记为无效。以下符号用于指定指示数组元素无效的值：

invalid="[value]"：包含 value 的数组元素无效。
invalid="[value:]"：如果第一个数组元素设置为 value，则所有数组元素都无效。
invalid="[value1,,value3,]"：如果数组元素包含在逗号分隔列表的相应位置中指定的值，则数组元素无效。如果列表中的a位置为空，则无法指示对应的数组元素无效。上面的示例表明，如果元素 1 和 3 分别包含 value1 和 value3，则它们是无效的。对于元素 2 和任何 >4 的元素，不能设置该字段的无效属性。
invalid="[value1,]"：如果第一个数组元素包含 value1，则它是无效的。不能为所有其他元素设置无效属性。

1.3.2. 约束

从dialect文件生成 MAVLink 库时，将为dialect中的所有消息和任何包含的文件 (例如 common.xml) 创建代码，并合并特定枚举的条目。 如果导入的消息或枚举项之间存在名称或 id 冲突, 生成器将报告错误。

定义元素的位置取决于它是公共元素还是特殊的, 以及项目是公共的还是私有的。

消息(message)的主要规则是：

• 消息 必须 包括强制性的 id 和name;
• 消息 应该(非常高度推荐) 包含 description;
• Point to point messages必须包含字段（filed）target_system;
• 与组件相关的Point to point messages必须包含 target_component 字段;
• 总有效载荷大小(对于所有字段) 不得超过255字节;
• 所有其他字段都是可选的;
• 至少一个field字段，至多64个field字段;
• <wip/> 标签可以添加到仍在测试的消息;
• Fields：
  • 消息中必须具有唯一的 name;
  • 应该 有一个描述;
  • 应该 使用 units 属性, 而不是在描述中说明。 每个字段只能有 一个 或没有单位;
  • 当结果预期较为明确下，应该 使用enum 属性;

不能依赖生成器来完全测试是否符合上述规则。
代码生成器仅检测：

• 是否有重复的message id；
• 是否有重复的filed name；
• message是否没带field字段或超过64个field；

它不会检查其他问题 (例如重复的名称或过大的有效负载)。

更改消息的name或 id 将使其与生成的库的旧版本不兼容。

添加或删除字段filed, 或更改字段的名称或类型, 将使消息与生成的库的旧版本不兼容 (生成的消息解码方法在生成时使用字段编号、order、类型和位置进行硬编码，如果这些变化, 解码将失败)。

Message Extensions允许向 MAVLink 2 消息添加新字段，而不会破坏尚未更新的接收器的兼容性。请注意，只能使用此机制(扩展字段)添加消息，而不能修改或删除它们。

如果需要通过这些方式（添加或删除字段, 或更改字段的名称或类型）更改消息，则有几个选项：

• 可以创建具有所需行为的新消息。同时，标记旧消息为已弃用；
• 可以更新消息, 并迭代语支版本号；

无论哪种情况，消息的所有用户都需要使用新的客户端库进行更新。

1.3.3. 消息ID的范围

特定生成的库中的所有消息都必须具有唯一的 id这一点很重要, 因为 id 用于确定消息有效负载的格式 。

对于 MAVLink 2, 每个语支都被分配到一个特定的范围, 从中可以选择 id。 这可确保任何语支都可以包含任何其他语支 (或common.xml), 而不会发生冲突。 这也意味着消息可以从语支移动到common.xml, 而无需更改任何代码。

创建新消息时, 应为您的语支选择下一个未使用的 id (在目标语支文件中定义的最后一个 id 之后)。
分配范围如下：

不应创建在id在 "MAVLink v1" 范围内的消息 (MAVLink v1 只有8位消息 id, 因此只能支持具有 id 0-255 的消息)。

1.4. 命令定义

1.4.1. 语法

MAVLink 命令被定义为 MAV_CMD 枚举中的条目（entry）。它们用于定义自主任务中使用的操作（ Mission Protocol）或以任何模式发送命令（ Command Protocol）。

每个命令都有 value(其命令编号)，并指定最多 7 参数。
这些参数主要用于 MISTION_ITEM 或 MISCION_ITEM_INT 消息(Mission Protocol)，或 COMMAND_INT 或 COMMAND_LONG 消息的编码。

例如，见MAV_CMD_NAV_PAYLOAD_PLACE:

枚举类型MAV_CMD 的entry标签内 可能会额外定义这些标签字段：

• param(可选)：最多为7个参数标签，使用index 属性编号。
• 以下二选一：
  • hasLocation(可选)：一个bool值(默认true)，向 GCS 提供提示，表明条目应显示为“独立”位置，而不是飞行路径上的目的地。这适用于在其参数 5、6 和 7 值中代表 经度、纬度、高度 位置信息而不是飞行器路径的entry（例如：MAV_CMD_DO_SET_ROI_LOCATION）。
  • isDestination (可选)：一个bool值(默认true)，它向 GCS 提供一个提示，表明该条目是一个飞行路径上的位置。这适用于在其参数 5、6 和 7 值代表经度、纬度、高度 位置信息并且位于飞行器路径上的entry（例如：MAV_CMD_NAV_WAYPOINT 和 MAV_CMD_NAV_LAND）。

param标签用于MAV_CMD枚举类型，包含在entry标签内，最多可以定义7个param，索引值从1~7。可包含以下字段：

• index ：索引值，范围1-7；
• description：描述，即注释；
• label ： 在 GCS 或其他 UI 中表示参数的显示名称。标签中的所有单词都应大写；
• units：值的单位；
• enum：包含参数的可能值的枚举 (如果适用)；
• decimalPlaces ：如果显示参数值，则提示 UI 使用多少小数位；
• increment ：参数值的允许增量；
• minValue ： 参数的最低值；
• maxValue：参数的最大值；
• reserved ：bool值 - 表示是否保留用于未来使用的参数。 如果未定义属性，则隐含 reserved="False"；
• default ： param的默认值 (主要用于 reserved 参数, 值 0 或NaN)；

1.4.2. 约束

命令(command)的主要规则是：

• param 必须具有1~7的索引值；
• 索引1~4、7的数据类型为float，索引 5、6 类型可以为 int32（依赖于具体的消息用途），也可以为float；
• 某些命令可能并不需要7个或任何的参数，这些参数可以作为保留字段留待以后使用；
• 保留的参数字段必须设为默认值0或NaN，接收方会视为“无操作”或“不受支持”；
• 参数5、6的默认值不能设为NaN，当某些命令需要参数5，6，为整型会有问题，NaN则无法表示整型；

若要将 param 声明为具有 NaN default 值的 reserved, 应使用以下语法：

<param index="3" reserved="true" default="NaN" />

要将参数声明为默认值为 0 的reserved，只需从定义中省略参数即可。相当于：

<param index="3" reserved="true" default="0" />

1.4.3. 命令value的范围

所有任务命令条目都必须有一个值（这不是由工具链强制执行的，但对于其他枚举，它减少了值无意更改和破坏其他系统的机会）。

对于 Mavlink 每个语支都被分配到一个特定的范围, 从中可以选择 id。 这可确保任何语支都可以包含任何其他语支 (或 common. xml), 而不会发生冲突。 它还意味着，消息可以从语支到 common.xml 而不需要修改的任何代码。

语支可以为任何消息选择其范围内的任何值。 然而，我们建议，所有相关命令都保留在同一块ID中，如果今后可能有更类似的命令，则可能会为新命令留出空间。

分配范围如下：

1.5. 扩展字段

扩展字段仅用于MAVLink v2。MAVLink v2 定义 extension fields，可以添加到一个现有消息，同时不打破原接收方的二进制兼容性。
在消息中的 标记之后定义的任何字段都是扩展字段。 例如, OPTICAL_FLOW 具有 flow_rate_x 和 flow_rate_y 字段, 这些字段将仅在 MAVLink 2 中发送:

扩展字段的规则是：

• 扩展字段可以添加任何 id 的信息，包括 MAVLink v1 消息id 范围内的信息。
• 当消息使用 MAVLink v1协议编码时不会发送扩展字段;
• 如果接收方没有定义这些扩展字段，则这些字段被忽略;
• 如果发送方没有定义这些扩展字段, 则接收方将扩展字段视为零值;
• 序列化消息时，扩展字段不被重排序或包含在 CRC_EXTRA 中;
• 必须将新的扩展字段添加到消息定义的末尾 (对于扩展字段, 序列化顺序由 XML 定义顺序定义);

添加后，不能修改或删除字段。 但是, 只要不超过最大字段数或有效负载大小限制, 就可以继续向消息末尾添加新字段;

2. 常用消息

每个消息对应的消息ID可以在xml中查看，也可以在库文件中查看。

2.1. HEARTBEAT MESSAGE

心跳包对应的msgid为0。心跳消息主要用来通告 MAVLink 网络上系统的存在，以及它的系统和组件 ID、组件类型和操作模式等。

消息体结构如下：

typedef struct __mavlink_heartbeat_t {
    uint32_t custom_mode; /*<  A bitfield for use for autopilot-specific flags*/
    uint8_t type; /*<  Type of the system (quadrotor, helicopter, etc.). Components use the same type as their associated system.*/
    uint8_t autopilot; /*<  Autopilot type / class.*/
    uint8_t base_mode; /*<  System mode bitmap.*/
    uint8_t system_status; /*<  System status flag.*/
    uint8_t mavlink_version; /*<  MAVLink version, not writable by user, gets added by protocol because of magic data type: uint8_t_mavlink_version*/
} mavlink_heartbeat_t;

各字段含义如下：

base_mode：指示不同的操作模式。它以8位编码。 共有8个预定义的标记。

• FLAG= 1：保留供将来使用;
• FLAG=2：表示已启用测试模式。 此模式用于临时测试，而不用于常规工具；
• FLAG=4：表示启用了自主模式（AUTO）。 这意味着无人系统通过导航到从地面站发送给它的目标航路点来自主运行。 在自动模式下，任务会加载到自动驾驶仪上。 任务由系统必须导航的一组多个航点组成;
• FLAG=8：表示启用了GUIDED模式。 在GUIDED模式下，任务由发送到系统的单个航路点组成。 然后，系统自动导航到指定位置;
• FLAG=16：表示系统可以通过自动控制来稳定其姿态（方向和高度）以及可能的位置。 这就需要外部传感器（例如室内环境中的GPS），高度传感器（气压计，LIDAR）或用于室内定位的运动捕捉才能在稳定状态下悬停。 系统需要外部控制输入才能使其移动;
• FLAG=32：表示回路仿真器中的硬件已激活，即当内部自动驾驶仪完全运行时，所有电机和电机执行器均被锁定；
• FLAG=64：表示已启用手动模式，这要求飞行员使用远程控制输入手动控制系统。 在手动控制中，自动驾驶仪不会进行自动控制；
• FLAG=128：系统处于待命状态，这意味着电动机已启用/正在运行，并且可以启动飞行;

system_status：一个系统状态的标志。 根据最新规范，已定义：

• system_status = 0：指未初始化系统或未知状态的系统；
• system_status = 1：表示系统正在引导；
• system_status = 2：表示系统正在执行校准。 实际上，传感器校准是一个非常重要的阶段，以确保诸如惯性测量单元（IMU）和通行证这样的飞行传感器保持一致并按预期运行;
• system_status = 3：这意味着系统处于待机模式，可以随时启动；
• system_status = 4：表示电动机已接合并且系统处于活动状态并且可能在空中；
• system_status = 5：表示潜在的错误，并且系统处于严重状态，尽管它仍然可以导航。 例如，在临时干扰或电池电量不足时，可能会发生这种情况；
• system_status = 6 ：这意味着紧急情况，其中无人驾驶系统失去了对某些零件的控制权，并处于困境中。 系统可能已经崩溃；
• system_status = 7：表示系统已开始关闭电源过程，现在正在关闭；
• system_status = 8：表示系统正在终止并结束其飞行;

2.2. GLOBAL POSITION MESSAGE

全球定位信息，消息ID为33

消息结构如下：

typedef struct __mavlink_global_position_int_t {
    uint32_t time_boot_ms; /*< [ms] Timestamp (time since system boot).*/
    int32_t lat; /*< [degE7] Latitude, expressed*/
    int32_t lon; /*< [degE7] Longitude, expressed*/
    int32_t alt; /*< [mm] Altitude (MSL). Note that virtually all GPS modules provide both WGS84 and MSL.*/
    int32_t relative_alt; /*< [mm] Altitude above ground*/
    int16_t vx; /*< [cm/s] Ground X Speed (Latitude, positive north)*/
    int16_t vy; /*< [cm/s] Ground Y Speed (Longitude, positive east)*/
    int16_t vz; /*< [cm/s] Ground Z Speed (Altitude, positive down)*/
    uint16_t hdg; /*< [cdeg] Vehicle heading (yaw angle), 0.0..359.99 degrees. If unknown, set to: UINT16_MAX*/
} mavlink_global_position_int_t;

各字段含义如下：

2.3. COMMAND_LONG

COMMAND_LONG是一个多功能命令，允许根据消息的命令类型及其参数发送不同类型的命令。其消息ID为76。

消息结构如下：

typedef struct __mavlink_command_long_t {
    float param1; /*<  Parameter 1 (for the specific command).*/
    float param2; /*<  Parameter 2 (for the specific command).*/
    float param3; /*<  Parameter 3 (for the specific command).*/
    float param4; /*<  Parameter 4 (for the specific command).*/
    float param5; /*<  Parameter 5 (for the specific command).*/
    float param6; /*<  Parameter 6 (for the specific command).*/
    float param7; /*<  Parameter 7 (for the specific command).*/
    uint16_t command; /*<  Command ID (of command to send).*/
    uint8_t target_system; /*<  System which should execute the command*/
    uint8_t target_component; /*<  Component which should execute the command, 0 for all components*/
    uint8_t confirmation; /*<  0: First transmission of this command. 1-255: Confirmation transmissions (e.g. for kill command)*/
} mavlink_command_long_t;

各字段含义如下：

2.4. MISSION 系列消息

mission系列的消息主要就是航线任务相关的消息。例如

• mission_count：总的任务点（航点）数量
• mission_item：具体每个航点的信息
• mission_request：请求获取目标的任务信息
• mission_ack：任务状态，如任务成功接收，任务接收失败，失败原因：缺少参数。
• mission_current：当前目标航点
• mission_item_reached：上一个到达的航点
• mission_change，mission_clear_all：任务改变，清空任务。

2.4.1. MISSION ITEM

MISSION ITEM消息的消息ID是39，用于将航点信息发送到无人系统上，以便它在GUIDED模式下自动导航到该特定路点。
消息结构如下：

typedef struct __mavlink_mission_item_t {
    float param1; /*<  PARAM1, see MAV_CMD enum*/
    float param2; /*<  PARAM2, see MAV_CMD enum*/
    float param3; /*<  PARAM3, see MAV_CMD enum*/
    float param4; /*<  PARAM4, see MAV_CMD enum*/
    float x; /*<  PARAM5 / local: X coordinate, global: latitude*/
    float y; /*<  PARAM6 / local: Y coordinate, global: longitude*/
    float z; /*<  PARAM7 / local: Z coordinate, global: altitude (relative or absolute, depending on frame).*/
    uint16_t seq; /*<  Sequence*/
    uint16_t command; /*<  The scheduled action for the waypoint.*/
    uint8_t target_system; /*<  System ID*/
    uint8_t target_component; /*<  Component ID*/
    uint8_t frame; /*<  The coordinate system of the waypoint.*/
    uint8_t current; /*<  false:0, true:1*/
    uint8_t autocontinue; /*<  Autocontinue to next waypoint*/
    uint8_t mission_type; /*<  Mission type.*/
} mavlink_mission_item_t;

各字段含义如下：

3. 参考链接

mavlink官方文档

本栏目推荐文章
• C++实现文件内查找字符串
• IDEA项目名称后面出现中括号，模块Modules的名子和文件夹名称不同，可以右键修改名称也可以在File->Project Structure 修改Modules的Name(快捷键ctrl+Shift+Alt+s)
• 和利时MACS6通过dat文件实现任意时间范围与测点的历史数据提取与科研分析
• 类模板分文件编写
• Linux文件IO之二 [补档-2023-07-21]
• Linux文件IO之一 [补偿-2023-07-21]
• 写代码时如何合理的画图表达逻辑结构
• 十行python代码实现文件去重，去除重复文件的脚本
• vim编辑器实现左边目录右边是文件内容
• MakeFile文件的使用 [补档-2023-07-13]

mavlink 结构 文件 xmlmavlink结构 文件xml mavlink logback文件xml 文件xml springmvc文件xml xmldocument文件xml mybatis文件xml 内容xml文件xsl setting文件xml 接口mavlink