Следующие XML-файлы определений представляют собой стандартный набор свойств, управляемых проектом mavlink.io. Они содержат сообщения, команды и перечисления, которые ожидаются в использовании для многих стеках дистанционно управляемых устройств (multiple flight stacks, MFS, так называемые полетные стеки) и наземных станциях управления (ground control stations, GCS):

common.xml - набор элементов, которые были реализованы как минимум в одном основном полетном стеке (включая объекты в standard.xml и common.xml).

standard.xml - стандартный набор элементов, совместимым образом реализованных как минимум двумя полетными стеками.

minimal.xml - минимальный набор элементов (сообщения, перечисления, MAV_CMD), необходимый для установки сети MAVLink.

Примечание: расшифровку незнакомых терминов и сокращений см. в Словарике MAVLink статьи [2].

[Диалекты MAVLink]

Далектами называют XML-файлы, которые определяют протокол - как стандартные его элементы, так и специфичные для вендора сообщения, перечисления и команды.

См. врезку "Диалекты и тестовые определения" для примеров XML-определений некоторых полетных стеков.

[MAVLink XML File Schema / Format]

Формат и структура файлов диалекта формально определена в документе XML Schema: mavschema.xsd. Хотя это каноническая ссылка, легче понять XML-файл на примере (как показано в следующих разделах).

Структура файла. Общая структура XML-файлов MAVLink приведена ниже. Если вы создаете пользовательский файл диалекта, структура вашего файла должна быть аналогична приведенной ниже (но может пропустить любые/все разделы).

< ?xml version="1.0"?>
< mavlink>

    < include>common.xml< /include>
    < include>other_dialect.xml< /include>

    < !-- ЗАМЕЧАНИЕ: если подключенный файл уже содержит тег version,
         то здесь этот тег удалите, иначе раскоментируйте
         следующую строку. -->
    < !-- < version>6< /version> -->

    < dialect>8< /dialect>

    < enums>
        < !-- Здесь определены перечисления (опционально) -->
    < /enums>

    < messages>
        < !-- Здесь определены сообщения (опционально) -->
    < /messages>
< /mavlink>

Ниже перечислены основные теги (все они опциональны):

• include: этот тег используется для указания других XML-файлов, подключенных в ваш диалект.

- Обычно файлы диалекта будут подключать common.xml, как показано выше.
- Вы можете подключить несколько файлов, используя отдельные теги include.
- Путь подключаемых файлов относителен к вашему файлы диалекта. Однако обратите внимание, что тесты проекта охватывают только случай, когда диалекты находятся в одной папке.
- Вложенные include не поддерживаются (импортируются только файлы, указанные в теге include верхнего уровня).
- При сборке утилиты генератора будут сливать вместе (присоединять) перечисления во всех файлах, и сообщать о дубликатах элементов перечислений и сообщений.

• version: minor-номер версии для релиза, как подключено в поле mavlink_version [HEARTBEAT](../messages/common.md#HEARTBEAT message).

- Для диалектов, которые подключают common.xml, тег version должен быть удален, чтобы использовался version из common.xml (если тег version указан, то он будет использоваться из файла верхнего уровня).
- Для частных диалектов вы можете использовать любую версию, какую захотите.

• dialect: число, уникальное для вашего диалекта.

• enums: в этом блоке могут быть определены перечисления, специфические для диалекта (если они не определены в файле, то этот блок опционален или может быть удален).

• messages: в этом блоке могут быть определены сообщения, специфические для диалекта (если они не определены в файле, то этот блок опционален или может быть удален).

Определения enum. Перечисления применяются для определения именованных значений, которые могут использоваться как опции в сообщениях - например для определения ошибок, состояний или режимов. Существует также специальное перечисление MAV_CMD, которое используется для определения команд MAVLink.

Перечисления определяются внутри блоков < enums> ... < /enums> (как обсуждалось в предыдущей секции) с помощью тегов < enum> ... < /enum> tags. Значения перечисления определены внутри enum с помощью тегов < entry> ... < /entry>.

Например, может быть определено вот такое перечисление LANDING_TARGET_TYPE:

< enum name="LANDING_TARGET_TYPE">
    < description>Тип цели приземления< /description>
    < entry value="0" name="LANDING_TARGET_TYPE_LIGHT_BEACON">
        < description>Цель приземления сигнализирует световым маячком (например:\
          IR-LOCK)< /description>
    < /entry>
    < entry value="1" name="LANDING_TARGET_TYPE_RADIO_BEACON">
        < description>Цель приземления сигнализирует радио маячком (например: \
          ILS, NDB)< /description>
    < /entry>
    < entry value="2" name="LANDING_TARGET_TYPE_VISION_FIDUCIAL">
        < description>Цель приземления представлена реперным маркером (например: \
          ARTag)< /description>
    < /entry>
    < entry value="3" name="LANDING_TARGET_TYPE_VISION_OTHER">
        < description>Цель приземления представлена визуальной формой/фигурой \
          (например: X-маркер, H-маркер, квадрат)< /description>
    < /entry>
< /enum>

У перечисления существуют следующие основные атрибуты:

• name: имя перечисления (обязательное). Это строка из заглавных букв, где слова отделены друг от друга символом нижнего подчеркивания.

• bitmask: установите в true для перечислений, которые определяют увеличивающиеся значения степени двойки, такие как флаги.

У перечисления существуют следующие вложенные теги (все они опциональные):

• description: строка, описывающая предназначение этого перечисления.

• entry: элемент перечисления (для каждого перечисления можно указать 0 или большее количество элементов).

• deprecated: этот тег показывает, что перечисление устарело.

entry. Элемент перечисления определяет одно из возможных значений этого перечисления. Атрибуты "нормального" элемента перечисления:

• name: имя значения перечисления (обязательное). Это строка из заглавных букв, где слова отделены друг от друга символом нижнего подчеркивания.

• value (опционально): значение элемента (число).

Вложенные поля "нормального" элемента (все они опциональные):

• description: описание элемента.

• deprecated: показывает, что элемент устарел.

• wip: показывает, что элемент разрабатывается (work in progress).

Замечание: entry может также определять опциональные элементы: param, hasLocation, isDestination, missionOnly. На практике они должны использоваться только в перечислении MAV_CMD (описано далее).

[Команды MAVLink (enum MAV_CMD)]

Отдельные значения элементов в перечислении MAV_CMD используются для определения команд MAVLink. У каждой команды есть значение (её "номер команды"), и команда указывает до 7 параметров.

Замечание: эти параметры закодированы в сообщениях MISSION_ITEM или MISSION_ITEM_INT (Mission Protocol, протокол миссии), либо сообщениях COMMAND_INT или COMMAND_LONG messages (Command Protocol).

Для примера рассмотрим MAV_CMD_NAV_PAYLOAD_PLACE:

< enum name="MAV_CMD">
...
    < entry value="94" name="MAV_CMD_NAV_PAYLOAD_PLACE">
        < description>Спуск и размещение полезной нагрузки. Квадрик снижается, \
         пока не обнаружит, что висящая нагрузка достигла земли, после чего \
         раскрывает захват и освобождает полезную нагрузку< /description>
        < param index="1">Максимальная дистанция для снижения (метров)< /param>
        < param index="2">Пусто< /param>
        < param index="3">Пусто< /param>
        < param index="4">Пусто< /param>
        < param index="5">Latitude (широта, deg * 1E7)< /param>
        < param index="6">Longitude (долгота, deg * 1E7)< /param>
        < param index="7">Altitude (высота, метров)< /param>
< /entry>
...
< /enum>

Поле value элементов MAV_CMD может дополнительно определять следующие теги/поля:

• param (опционально): до 7 тегов параметров, пронумерованных атрибутом index.

• Одно из следующего (но не одновременно):

hasLocation (опционально): двоичное значение (по умолчанию true), которое предоставляется подсказку для GCS, что элемент должен отображаться как "автономное" месторасположения (standalone location), а не как место назначение на маршруте полета. Применяется для команд MAV_CMD, которые содержат широту/долготу/высоту (lat/lon/alt) информации места размещения в param-значениях 5, 6 и 7, но которые не находятся на маршруте полета (например: MAV_CMD_DO_SET_ROI_LOCATION).

isDestination (опционально): двоичное значение (по умолчанию true), которое предоставляется подсказку для GCS, что элемент должен отображаться как точка на маршруте полета. Применяется для команд MAV_CMD, которые содержат широту/долготу/высоту (lat/lon/alt) информации места размещения в param-значениях 5, 6 и 7, и которые устанавливают путь/место назначения (например: MAV_CMD_NAV_WAYPOINT и MAV_CMD_NAV_LAND).

missionOnly (опционально): применяется со значением true, если MAV_COMMAND имеет смысл только в миссии. Например, команды задания ограждения не могут быть полезны в команде.

param. Тег < param> используется в перечислении MAV_CMD как часть определения команд миссии. Каждое значение entry может иметь до 7 декларированных с помощью param параметров, с индексами от 1 до 7 (индекс параметра указывается атрибутом index, и он является обязательным для param).

У param может присутствовать описание:

• description - описание параметра (находится в теле тега).

Параметр также может включать следующие опциональные атрибуты (которые могут использоваться графическим интерфейсом пользователя для отображения и редактирования параметров):

• label - видимое имя, представляющее параметр на GCS или другом UI. Все слова label должны быть в верхнем регистре.

• units - единицы СИ (SI) для значения.

• enum - перечисление, содержащее возможные значения для параметра (если это имеет место).

• decimalPlaces - подсказка для UI, сколько десятичных позиций использовать в отображаемом параметре.

• increment - разрешенные инкременты для значения параметра.

• minValue - минимальное значение для параметра.

• maxValue - максимальное значение для параметра.

• multiplier - умножается на это значение для получения не масштабированного оригинального значения. Это предназначено главным образом для масштабирования, применяемого для значений без единиц, когда масштабирование не закодировано единицами units.

• reserved - двоичное значение, которое показывает, что параметр зарезервирован для использования в будущем. Если атрибуты не декларированы, то неявно reserved="False".

Совет: для дополнительной информации см. Defining XML Enums/Messages > Reserved/Undefined Parameters.

• default - значение по умолчанию для param (используется главным образом для зарезервирвоанных параметров, где значение 0 или NaN).

[Определение сообщения (messages)]

Сообщения определены в блоке < messages> ... < /messages> с использованием тегов < message>...< /message> Отдельные поля кодируются в полезной нагрузке сообщения с использованием определений тегов < field> ... < /field>. Каждое сообщение должно иметь как минимум одно поле.

Для примера ниже приведено определение сообщения BATTERY_STATUS (оно было выбрано потому, что содержит многие основные поля и атрибуты).

< message id="147" name="BATTERY_STATUS">
   < description>Информация о батарее. Обновляет GCS статусом батареи полетного контроллера. \
     Умные батареи также используют это сообщение, но могут дополнительно посылать \
     SMART_BATTERY_INFO.< /description>
   < field type="uint8_t" name="id" instance="true">Идентификатор батареи (Battery ID)< /field>
   < field type="uint8_t" name="battery_function" enum="MAV_BATTERY_FUNCTION">Функция батареи< /field>
   < field type="uint8_t" name="type" enum="MAV_BATTERY_TYPE">Тип (химия) батареи< /field>
   < field type="int16_t" name="temperature" units="cdegC" invalid="INT16_MAX">Температура \
    батареи. INT16_MAX для неизвестной температуры.< /field>
   < field type="uint16_t[10]" name="voltages" units="mV" invalid="[UINT16_MAX]">Напряжение \
     ячеек 1 .. 10 батареи (см. voltages_ext для ячеек 11 .. 14). Ячейки в этом поле сверх \
     допустимого количества ячеек для этой батареи должны иметь значение UINT16_MAX. \
     Если напряжения отдельных ячеек неизвестны или не измерены, то общее напряжение \
     батареи должно быть заполнено в ячейке 0, а у всех других установлено значение UINT16_MAX. \
     Если напряжение батареи больше чем (UINT16_MAX - 1), то ячейка 0 должна быть установлена \
     в (UINT16_MAX - 1), а ячейка 1 в оставшееся напряжение. Это может быть расширено на несколько \
     ячеек, если общее напряжение больше, чем 2 * (UINT16_MAX - 1).< /field>
   < field type="int16_t" name="current_battery" units="cA" invalid="-1">Ток батареи, \
     -1: автопилот не измеряет ток< /field>
   < field type="int32_t" name="current_consumed" units="mAh" invalid="-1">Потребленный заряд, \
     -1: автопилот не предоставляет оценку потребления заряда< /field>
   < field type="int32_t" name="energy_consumed" units="hJ" invalid="-1">Потребленная энергия, \
     -1: автопилот не предоставляет оценку потребления энергии< /field>
   < field type="int8_t" name="battery_remaining" units="%" invalid="-1">Оставшаяся энергия батареи. \
     Значения: [0-100], -1: автопилот не предоставляет оценку разряжености батареи.< /field>
   < extensions/>
   < field type="int32_t" name="time_remaining" units="s" invalid="0">Оставшееся время работы от \
     батареи, 0: автопилот не предоставляет оценку оставшегося времени батареи< /field>
   < field type="uint8_t" name="charge_state" enum="MAV_BATTERY_CHARGE_STATE">Состояние степени \
     разряда, предоставленное автопилотом для предупреждения или внешних реакций< /field>
   < field type="uint16_t[4]" name="voltages_ext" units="mV" invalid="[0]">Напряжения батареи для \
     ячеек 11 .. 14. Ячейки с номерами выше допустимого количества для этой батареи должны иметь \
     значение 0, где 0 показывает, что ячейка не поддерживается (обратите внимание, что это отличается \
     от поля напряжений и позволяет усечение пустого байта). Если измеренное значение 0, то вместо \
     него должно быть отправлено 1.< /field>
   < field type="uint8_t" name="mode" enum="MAV_BATTERY_MODE">Режим батареи. Умолчание (0) означает, \
     что сообщение о режиме батареи не поддерживается, или батарея находится в режиме нормального \
     использования.< /field>
   < field type="uint32_t" name="fault_bitmask" enum="MAV_BATTERY_FAULT">Индикации отказа/здоровья \
     (fault/health). Это должно быть установлено, когда charge_state MAV_BATTERY_CHARGE_STATE_FAILED \
     или MAV_BATTERY_CHARGE_STATE_UNHEALTHY (если нет, то fault reporting не поддерживается).< /field>
< /message>

Каждое сообщение инкапсулируется тегами message со следующими атрибутами:

• id: атрибут идентификатора, уникальный номер индекса для этого сообщения (в показанном выше примере 147). 

Для протокола MAVLink 1: допустимы номера id в диапазоне 0 .. 255. Идентификаторы 0-149 и 230-255 зарезервированы для common.xml. Диалекты могут использовать 180-229 для своих сообщений (при условии, что они не используются другими подключенными диалектами).

Для MAVLink 2: допустимы номера id в диапазоне 0 .. 16777215. Все номера ниже 255 должны считаться зарезервированными, за исключением сообщений, которые также предназначены для MAVLink 1.

Замечание: значения идентификаторов являются дорогим ресурсом в MAVLink 1.

• name: атрибут имени предоставляет удобную для чтения человеком форму для сообщения (например "BATTERY_STATUS"). Это используется для именования в helper-функциях генерируемых библиотек, но не посылается по каналу связи.

Внутренние теги message:

• description: удобочитаемое описание сообщения, которое показывается в интерфейсах пользователя и комментариях кода. Здесь должна содержаться вся информация (и гиперссылки) для полного понимания сообщения.

• field: кодирует поле сообщения. Значение field это строка имени/текста, используемая в документации GUI (но она не посылается по каналу связи). Каждое message должно иметь как минимум одно field.

Атрибуты для field следующие:

type: подобно полю в структуре C - размер данных, необходимый для сохранения/представления типа данных. Поля могут быть целыми числами signed/unsigned размером 8, 16, 23, 64 бита ({u)int8_t, (u)int16_t, (u)int32_t, (u)int64_t), одиночной/двойной точности IEEE754 float. Они также могут быть массивами других типов - например uint16_t[10].

name: имя поля (используется в коде).

enum (опционально): имя перечисления, определяющего возможные значения поля (например MAV_BATTERY_CHARGE_STATE).

units (опционально): единицы для полей сообщения, которые принимают числовые значения (не перечисления). Они определены в schema (см. name="SI_Unit").

multiplier (опционально): множитель на это значение, чтобы получить не масштабированное оригинальное значение. Допустимые значения определены в schema (см. name="factor"). Например, GPS_STATUS это значение в градусах (0-360), посылаемое в поле байта (0-255). Чтобы получить оригинальное значение, байт умножается на значение multiplier (360/256). Это в настоящее время используется только для значений, масштабирование которых не закодировано в units.

print_format (опционально): TBD (пока не реализовано).

default (опционально): TBD (пока не реализовано).

increment: разрешенные инкременты для изменения значения.

minValue: минимальное значение поля.

maxValue: максимальное значение поля.

instance: если true, то это показывает, что сообщение содержит информацию определенного сенсора или батареи (например Battery 1, Battery 2, и т. д.), и что это поле показывает, какой сенсор. По умолчанию false. Это поле позволяет получателю автоматически связать сообщения с определенным сенсором и нарисовать их в одной последовательности.

invalid: указывает значение, которое можно установить на поле, чтобы показать недопустимость данных. В этом случае получатель должен игнорировать поле, если в нем оказалось такое значение. Например, BATTERY_STATUS.current_battery указывает invalid="-1", таким образом для батареи, у которой не измеряется ток, должно быть установлено BATTERY_STATUS.current_battery = -1.

Там, где это возможно, значение invalid должно быть выбрано вне ожидаемого/допустимого значения поля (предпочтителен 0, если это не относится к допустимому значению поля). Для целых чисел обычно выбирается самое большое возможное значение (например UINT16_MAX, INT16_MAX, UINT8_MAX, UINT8_MAX). Для чисел float мы обычно используем invalid="NaN".

Массивы представляют несколько элементов, где некоторые (или все) могут нуждаться в пометке как недопустимые. Используется следующая нотация, чтобы пометить недопустимые элементы массива:

invalid="[value]": элементы массива, содержащие значение value, являются недопустимыми.

invalid="[value:]": все элементы массива недопустимы, если первый элемент массива установлен в значение value.

invalid="[value1,,value3,]": элементы массива недопустимы, если они содержат значение, присутствующее в этом списке. Если позиция списка пустая, то невозможно указать, что соответствующий элемент массива недействителен. В этом примере показано, что элементы 1 и 3 недопустимы, если они содержат значения value1 и value3 соответственно. Для элемента 2 и любых элементов >4 недопустимое свойство поля не может быть установлено.

invalid="[value1,]": первый элемент массива недопустим, если содержит value1: недопустимое свойство поля не может быть установлено для всех других элементов.

• deprecated (опционально): помечает сообщение как устаревшее.

• wip (опционально): помечает, что сообщение в разработке (work in progress).

• extensions (опционально): это самозакрывающийся тег, используемый для отображения последующих полей, применимых только к MAVLink 2. Тег должен использоваться только для сообщений MAVLink 1 (id < 256), которые были расширены в MAVLink 2.

[Общие теги]

Здесь перечислены теги, которые могут использоваться в нескольких других типах - например в message и enum.

deprecated. Тег < deprecated> может использоваться в перечислении (enum), элементе перечисления (value) или сообщении, чтобы показать, что элемент был заменен. Атрибуты тега показывают время устаревания и замещающий его элемент, в то время как элемент может (опционально) содержать строку с дополнительной информацией, описывающей устаревание.

Утилита генерации библиотеки (MAVlink generator toolchain) может быть сконфигурирована для условной сборки сообщений, когда устаревшие элементы опускаются.

Совет: сущность должна быть помечена как deprecated только когда основные пользователи выбрали вариант обновления на новый метод.

В качестве конкретного примера рассмотрим SET_MODE, что устарело и было заменено на MAV_CMD_DO_SET_MODE в декабре 2015 года (2015-12).

< message id="11" name="SET_MODE">
   < deprecated since="2015-12" replaced_by="MAV_CMD_DO_SET_MODE">Вместо этого используйте \
      COMMAND_LONG вместе с MAV_CMD_DO_SET_MODE < /deprecated>

Атрибуты deprecated:

• since: год/месяц, когда началось устаревание. Формат: YYYY-MM.

• replaced_by: строка сущности, которая заменила устаревший элемент.

wip. Тег < wip> может использоваться в элементе перечисления (value) или сообщения, чтобы показать, что это находится в процессе разработки (work in progress). Элемент может (опционально) содержать строку с дополнительной информацией о новом элементе.

Утилита генерации библиотеки может быть сконфигурирована для условной сборки сообщений, когда wip-элементы опускаются.

Чаще всего этот тег используется следующим образом:

< wip />

[Ссылки]

1. MAVLink-Standard Definitions site:mavlink.io.
2. MAVLink: руководство разработчика.