Skip to main content

API Server-Drone v2.1

API интеграции MQTT-топиков между сервером и дроном проекта Wheelies.

Протокол: MQTT
Формат данных: JSON
Дата: 12.02.2025
Формат топика: {DRONE_ID}_{topic_name}

Типы данных

Point

latfloatrequired
Широта
longfloatrequired
Долгота
heightfloat
Высота полёта (м)

Position

pointPointrequired
Координаты
latfloatrequired
Широта
longfloatrequired
Долгота
heightfloat
Высота (м)
directionintrequired
Направление движения (0–360°)
speedfloat
Скорость (м/с)

Сервер → Дрон

1. mission

  • MQTT Topic: {DRONE_ID}_mission

Отправка миссии на дрон. Топик get_mission переименован в mission начиная с v2.0.

mission_iduuidrequired
ID миссии
paramsArray[Param]required
Массив параметров
param_iduuidrequired
ID параметра
namestr
Имя параметра
typestrrequired
Тип данных параметра
pointТочка
floatЧисло
booleanЛогическое значение
valueMixed
Значение параметра
commandsArray[Command]required
Массив команд
command_iduuidrequired
ID команды
command_typestrrequired
Тип команды
move_toПерелёт к точке
coverageПокрытие области
landПосадка
takeoffВзлёт
scan_areaСканирование области
by_pathДвижение по маршруту
pointsArray[Point]required
Точки маршрута
latfloatrequired
Широта
longfloatrequired
Долгота
heightfloat
Высота полёта (м)
paramsArray[Object]required
Параметры команды
triggersArray[Trigger]
Массив триггеров
conditionstrrequired
Условие переключения
command_idstrrequired
ID целевой команды
priorityintrequired
Приоритет триггера
{
"topic": "10001_mission",
"message": {
"mission_id": "abc-123",
"params": [],
"commands": [
{
"command_id": "cmd-456",
"command_type": "move_to",
"points": [
{
"lat": 55.751244,
"long": 37.618423,
"height": 50.0
}
],
"params": []
}
],
"triggers": []
}
}

2. pause_mission

  • MQTT Topic: {DRONE_ID}_pause_mission

Пауза или возобновление выполнения миссии.

messagestrrequired
Команда управления паузой
onПоставить на паузу
offВозобновить выполнение
{
"topic": "10001_pause_mission",
"message": "on"
}

3. cancel_mission

  • MQTT Topic: {DRONE_ID}_cancel_mission

Отмена текущей миссии.

messagestrrequired
Способ завершения миссии
BACK_TO_STARTВозврат на точку старта
ON_CURRENT_PLACEПосадка на текущем месте
{
"topic": "10001_cancel_mission",
"message": "BACK_TO_START"
}

4. use_hand_mode

  • MQTT Topic: {DRONE_ID}_use_hand_mode

Переключение между ручным и автоматическим режимом управления дроном.

messagestrrequired
Режим управления
trueРучной режим
falseАвтоматический режим
{
"topic": "10001_use_hand_mode",
"message": "true"
}

5. use_ai_video

  • MQTT Topic: {DRONE_ID}_use_ai_video

Включение или выключение AI-детекции объектов на видеопотоке.

messagestrrequired
Режим AI-детекции
trueВключить AI-детекцию
falseВыключить AI-детекцию
{
"topic": "10001_use_ai_video",
"message": "true"
}

6. gimbal_control

  • MQTT Topic: {DRONE_ID}_gimbal_control

Управление подвесом камеры. Формат сообщения — JSON-объект {camera_id: {roll, pitch, yaw, zoom}}. Значения roll, pitch, yaw в диапазоне 1100–1900, zoom — "0" или "1".

messageobjectrequired
Объект, где ключ — ID камеры, значение — параметры подвеса
{camera_id}objectrequired
Параметры подвеса для камеры
rollintrequired
Крен (1100–1900, центр 1500)
pitchintrequired
Тангаж (1100–1900, центр 1500)
yawintrequired
Рыскание (1100–1900, центр 1500)
zoomstrrequired
Зум
0Без зума
1Увеличение
{
"topic": "10001_gimbal_control",
"message": {
"camera_0": {
"roll": 1500,
"pitch": 1100,
"yaw": 1500,
"zoom": "0"
}
}
}

7. get_current_data

  • MQTT Topic: {DRONE_ID}_get_current_data

Запрос текущего состояния всех модулей дрона. Дрон ответит актуальными данными телеметрии.

messagestrrequired
Команда запроса
trueЗапросить текущие данные
{
"topic": "10001_get_current_data",
"message": "true"
}

8. joy_control

  • MQTT Topic: {DRONE_ID}_joy_control

Ручное управление дроном. Формат сообщения: "{direction}_{speed}".

messagestrrequired
Команда в формате direction_speed
directionstrrequired
Направление движения
forwardВперёд
backНазад
leftВлево
rightВправо
forward_leftВперёд-влево
forward_rightВперёд-вправо
back_leftНазад-влево
back_rightНазад-вправо
upВверх
downВниз
centerОстановка (зависание)
speedintrequired
Скорость движения
{
"topic": "10001_joy_control",
"message": "forward_2"
}

9. critical_disarm

  • MQTT Topic: {DRONE_ID}_critical_disarm

Экстренное отключение моторов дрона. Используется только в аварийных ситуациях.

messagestrrequired
Команда аварийного отключения
trueНемедленно отключить моторы
{
"topic": "10001_critical_disarm",
"message": "true"
}

10. obstacle_avoidance

  • MQTT Topic: {DRONE_ID}_obstacle_avoidance

Глобальное включение или выключение системы обхода препятствий.

messagestrrequired
Режим обхода препятствий
trueВключить обход препятствий
falseВыключить обход препятствий
{
"topic": "10001_obstacle_avoidance",
"message": "true"
}

11. camera_tracking

  • MQTT Topic: {DRONE_ID}_camera_tracking

Выбор камеры, используемой для AI-трекинга объектов.

messagestrrequired
Имя камеры для трекинга (например, camera_front, camera_0)
{
"topic": "10001_camera_tracking",
"message": "camera_front"
}

12. stream_url

  • MQTT Topic: {DRONE_ID}_stream_url

Передача URL видеопотока на дрон для конкретной камеры.

camera_idstrrequired
Идентификатор камеры
provider_urlstrrequired
URL видеопотока (RTSP/RTMP)
expire_timestr
Время истечения доступа к потоку
{
"topic": "10001_stream_url",
"message": {
"camera_id": "camera_0",
"provider_url": "rtsp://192.168.1.100:8554/stream",
"expire_time": "2025-02-12T18:00:00"
}
}

13. get_calibration_data

  • MQTT Topic: {DRONE_ID}_get_calibration_data

Запрос текущих данных калибровки сенсоров дрона.

messagestrrequired
Команда запроса
trueЗапросить данные калибровки
{
"topic": "10001_get_calibration_data",
"message": "true"
}

14. set_calibration

  • MQTT Topic: {DRONE_ID}_set_calibration

Установка параметров калибровки сенсоров.

stepintrequired
Этап калибровки (0–3)
paramstrrequired
Параметр калибровки (например, accel, gyro, compass)
{
"topic": "10001_set_calibration",
"message": {
"step": 1,
"param": "accel"
}
}

15. get_check_motors

  • MQTT Topic: {DRONE_ID}_get_check_motors

Запрос текущих данных проверки моторов.

messagestrrequired
Команда запроса
trueЗапросить данные моторов
{
"topic": "10001_get_check_motors",
"message": "true"
}

16. set_check_motors

  • MQTT Topic: {DRONE_ID}_set_check_motors

Запуск проверки моторов с указанным PWM-значением.

idintrequired
ID мотора (0 — все моторы, 1–4 — конкретный мотор)
valueintrequired
PWM-значение для проверки
{
"topic": "10001_set_check_motors",
"message": {
"id": 0,
"value": 1200
}
}

17. get_drone_params

  • MQTT Topic: {DRONE_ID}_get_drone_params

Запрос значений параметров MAVROS (ArduPilot) дрона.

messageArray[str]required
Список имён запрашиваемых параметров
{
"topic": "10001_get_drone_params",
"message": [
"WPNAV_SPEED",
"WPNAV_SPEED_DN"
]
}

18. set_drone_params

  • MQTT Topic: {DRONE_ID}_set_drone_params

Установка значений параметров MAVROS (ArduPilot) дрона.

messageobjectrequired
Объект с параметрами: ключ — имя параметра, значение — новое значение
{
"topic": "10001_set_drone_params",
"message": {
"WPNAV_SPEED": 500,
"WPNAV_SPEED_DN": 150
}
}

19. drone_request_approve

  • MQTT Topic: {DRONE_ID}_drone_request_approve

Подтверждение запроса регистрации дрона. Передаёт ключи шифрования для установки защищённого соединения.

public_keystrrequired
Публичный ключ для шифрования
aes_keystrrequired
AES-ключ для симметричного шифрования
{
"topic": "10001_drone_request_approve",
"message": {
"public_key": "MIIBIjANBgkqhki...",
"aes_key": "aGVsbG8gd29ybGQ="
}
}

  • MQTT Topic: {DRONE_ID}_send_file_link

Отправка ссылки для загрузки ML-модели на дрон.

file_namestrrequired
Имя файла модели
file_linkstrrequired
URL для скачивания файла
tokenstrrequired
Токен авторизации для доступа к файлу
{
"topic": "10001_send_file_link",
"message": {
"file_name": "yolov8n.pt",
"file_link": "https://storage.example.com/models/yolov8n.pt",
"token": "Bearer eyJhbGciOi..."
}
}

21. set_model_name

  • MQTT Topic: {DRONE_ID}_set_model_name

Установка активной ML-модели для детекции объектов. Сообщение — имя файла модели.

messagestrrequired
Имя файла модели (например, yolov8n.pt)
{
"topic": "10001_set_model_name",
"message": "yolov8n.pt"
}

22. delete_model

  • MQTT Topic: {DRONE_ID}_delete_model

Удаление ML-моделей с дрона. Сообщение — массив имён файлов для удаления.

messageArray[str]required
Список имён файлов моделей для удаления
{
"topic": "10001_delete_model",
"message": [
"model_v1.pt",
"model_v2.pt"
]
}

23. gimbal_auto_control

  • MQTT Topic: {DRONE_ID}_gimbal_auto_control

Управление автоматическим сканированием подвеса камеры.

statusstrrequired
Действие
startЗапустить автосканирование
stopОстановить автосканирование
currentЗапросить текущий статус
typestrrequired
Тип сканирования
sinСинусоидальное движение
dynamicДинамическое движение
noneБез типа (для current/stop)
{
"topic": "10001_gimbal_auto_control",
"message": {
"status": "start",
"type": "sin"
}
}

24. follow_track_object

  • MQTT Topic: {DRONE_ID}_follow_track_object

Управление слежением камеры за объектом (трекинг).

statusstrrequired
Действие
startНачать слежение
stopПрекратить слежение
track_idstrrequired
ID отслеживаемого объекта
class_namestrrequired
Класс объекта (например, car, person)
zoom_statusstr
Режим автозума
enableАвтозум включён
disenableАвтозум выключен
zoom_meanfloat
Целевое среднее значение зума (1.0–15.0)
{
"topic": "10001_follow_track_object",
"message": {
"status": "start",
"track_id": "42",
"class_name": "car",
"zoom_status": "enable",
"zoom_mean": 5.0
}
}

25. drone_follow_object

  • MQTT Topic: {DRONE_ID}_drone_follow_object

Управление следованием дрона за объектом (дрон физически перемещается за целью).

statusstrrequired
Действие
startНачать следование
stopПрекратить следование
track_idstrrequired
ID объекта
class_namestrrequired
Класс объекта
{
"topic": "10001_drone_follow_object",
"message": {
"status": "start",
"track_id": "42",
"class_name": "person"
}
}

26. drone_strike_object

  • MQTT Topic: {DRONE_ID}_drone_strike_object

Управление тараном объекта дроном.

statusstrrequired
Действие
startНачать таран
stopПрекратить таран
track_idstrrequired
ID объекта для тарана
class_namestrrequired
Класс объекта
{
"topic": "10001_drone_strike_object",
"message": {
"status": "start",
"track_id": "42",
"class_name": "car"
}
}

Дрон → Сервер

1. data (телеметрия)

  • MQTT Topic: {DRONE_ID}_data

Периодическая отправка телеметрии дрона — позиция, батарея, статус, активные режимы. В v2.1 добавлены поля: pause, obstacle_avoidance, camera_tracking. Новые статусы: online, offline, emergency landing, on mission, returning, taking off, landing, paused.

positionPositionrequired
Позиция дрона
pointPointrequired
Координаты
latfloatrequired
Широта
longfloatrequired
Долгота
heightfloat
Высота (м)
directionintrequired
Направление движения (0–360°)
speedfloat
Скорость (м/с)
battery_levelintrequired
Заряд батареи (0–100%)
headingintrequired
Направление камеры (0–360°)
statusstrrequired
Текущий статус дрона
onlineВ сети, готов к работе
offlineНе в сети
emergency landingАварийная посадка
on missionВыполняет миссию
returningВозвращается на точку старта
taking offВзлетает
landingСовершает посадку
pausedМиссия на паузе
mission_iduuidrequired
ID текущей миссии
command_iduuidrequired
ID выполняемой команды
use_ai_videobooleanrequired
AI-детекция активна
use_hand_modebooleanrequired
Ручной режим управления активен
pausebooleanrequired
Миссия на паузе
obstacle_avoidancebooleanrequired
Обход препятствий активен
camera_trackingstr
Идентификатор активной камеры трекинга
{
"topic": "10001_data",
"message": {
"position": {
"point": {
"lat": 59.939,
"long": 149.182,
"height": 200
},
"direction": 90,
"speed": 15.5
},
"battery_level": 87,
"heading": 318,
"status": "on mission",
"mission_id": "01939ba1-fd8a-7ed4-acb1-35791c03c70d",
"command_id": "0193909e-e71c-7b38-8ed7-ab4d7aed7e1c",
"use_ai_video": false,
"use_hand_mode": false,
"pause": false,
"obstacle_avoidance": true,
"camera_tracking": "camera_0"
}
}

2. mission_received

  • MQTT Topic: {DRONE_ID}_mission_received

Подтверждение получения миссии дроном.

messageuuidrequired
ID полученной миссии
{
"topic": "10001_mission_received",
"message": "01939ba1-fd8a-7ed4-acb1-35791c03c70d"
}

3. mission_completed

  • MQTT Topic: {DRONE_ID}_mission_completed

Уведомление о завершении миссии.

messageuuidrequired
ID завершённой миссии
{
"topic": "10001_mission_completed",
"message": "01939ba1-fd8a-7ed4-acb1-35791c03c70d"
}

4. mission_cancelled

  • MQTT Topic: {DRONE_ID}_mission_cancelled

Уведомление об отмене миссии.

messageuuidrequired
ID отменённой миссии
{
"topic": "10001_mission_cancelled",
"message": "01939ba1-fd8a-7ed4-acb1-35791c03c70d"
}

5. objects_data

  • MQTT Topic: {DRONE_ID}_objects_data

Метаданные детектируемого объекта без изображения. Передаётся при каждом обнаружении.

namestrrequired
Класс объекта (например, car, person)
idint
ID объекта в рамках текущей сессии
timedatetimerequired
Время детекции в формате YYYY-MM-DDThh:mm:ss
positionPositionrequired
Позиция обнаруженного объекта
pointPointrequired
Координаты объекта
latfloatrequired
Широта
longfloatrequired
Долгота
heightfloat
Высота (м)
directionintrequired
Направление движения объекта (0–360°)
speedfloat
Скорость объекта (м/с)
drone_pointPointrequired
Координаты дрона в момент детекции
latfloatrequired
Широта дрона
longfloatrequired
Долгота дрона
{
"topic": "10001_objects_data",
"message": {
"name": "car",
"id": 1,
"time": "2025-08-09T18:31:42",
"position": {
"point": {
"lat": 59.9397889,
"long": 149.18209,
"height": 200
},
"direction": 90,
"speed": 60
},
"drone_point": {
"lat": -35.364,
"long": 149.165
}
}
}

6. photo

  • MQTT Topic: {DRONE_ID}_photo

Данные фото с детектируемым объектом. Включает изображение в Base64.

namestrrequired
Класс детектируемого объекта (например, car, person)
idint
ID детектируемого объекта
timedatetimerequired
Время детекции в формате YYYY-MM-DDThh:mm:ss
photoBase64required
Изображение объекта в формате Base64
latfloatrequired
Широта координаты дрона в момент съёмки
longfloatrequired
Долгота координаты дрона в момент съёмки
{
"topic": "10001_photo",
"message": {
"name": "car",
"id": 1,
"time": "2025-08-09T18:31:42",
"photo": "/9j/4AAQSkZJRgABAD...",
"lat": 59.942,
"long": 30.3202
}
}

7. gimbal_data

  • MQTT Topic: {DRONE_ID}_gimbal_data

Текущие данные подвеса камеры для каждой подключённой камеры. Формат: {camera_id: {roll, pitch, yaw, zoom}}.

{camera_id}objectrequired
Параметры подвеса камеры
rollintrequired
Крен
pitchintrequired
Тангаж
yawintrequired
Рыскание
zoomintrequired
Текущее значение зума
{
"topic": "10001_gimbal_data",
"message": {
"camera_0": {
"roll": 0,
"pitch": -45,
"yaw": 180,
"zoom": 1
}
}
}

8. gimbal_auto_status

  • MQTT Topic: {DRONE_ID}_gimbal_auto_status

Статус автоматического сканирования подвеса.

statusstrrequired
Текущий статус автосканирования
startАвтосканирование запущено
stopАвтосканирование остановлено
typestrrequired
Тип сканирования
sinСинусоидальное движение
dynamicДинамическое движение
noneНе задан
{
"topic": "10001_gimbal_auto_status",
"message": {
"status": "start",
"type": "sin"
}
}

9. drone_params_data

  • MQTT Topic: {DRONE_ID}_drone_params_data

Ответ с запрошенными параметрами MAVROS. Ключ — имя параметра, значение — текущее значение.

messageobjectrequired
Объект параметров: ключ — имя, значение — текущее значение
{
"topic": "10001_drone_params_data",
"message": {
"WPNAV_SPEED": 500,
"WPNAV_SPEED_DN": 150
}
}

10. calibration_data

  • MQTT Topic: {DRONE_ID}_calibration_data

Данные о текущем состоянии калибровки сенсоров.

stepintrequired
Текущий этап калибровки (0–3)
paramstrrequired
Калибруемый параметр (accel, gyro, compass)
statusstrrequired
Статус этапа калибровки
in_progressКалибровка выполняется
completedЭтап завершён
errorОшибка калибровки
{
"topic": "10001_calibration_data",
"message": {
"step": 1,
"param": "accel",
"status": "completed"
}
}

11. check_motors_data

  • MQTT Topic: {DRONE_ID}_check_motors_data

Данные проверки моторов — массив PWM-значений для каждого мотора.

messageArray[int]required
PWM-значения моторов (индекс = номер мотора)
{
"topic": "10001_check_motors_data",
"message": [1200, 1200, 1200, 1200]
}

12. stream_lost

  • MQTT Topic: {DRONE_ID}_stream_lost

Уведомление о потере URL видеопотока. Сервер должен отправить актуальный URL через stream_url.

messagestrrequired
Уведомление о потере потока
trueURL видеопотока потерян, требуется повторная отправка
{
"topic": "10001_stream_lost",
"message": "true"
}

13. payload

  • MQTT Topic: {DRONE_ID}_payload

Полный статус оборудования дрона: камеры, SD-карта, прошивка, контроллер, состояние связи.

camerasArray[object]
Список подключённых камер и их статусов
sd_cardobject
Информация об SD-карте (наличие, свободное место)
firmwarestr
Версия прошивки дрона
controllerstr
Тип полётного контроллера
connectionobject
Информация о качестве связи
{
"topic": "10001_payload",
"message": {
"cameras": [
{
"id": "camera_0",
"status": "connected",
"resolution": "1920x1080"
}
],
"sd_card": {
"present": true,
"free_mb": 15360
},
"firmware": "4.5.1",
"controller": "Pixhawk6C",
"connection": {
"rssi": -45,
"quality": "good"
}
}
}

14. mag_fitness

  • MQTT Topic: {DRONE_ID}_mag_fitness

Данные калибровки магнитометра (компаса).

compass_idintrequired
ID компаса (0, 1, 2)
fitnessfloatrequired
Качество калибровки (0.0 — плохо, 1.0 — отлично)
{
"topic": "10001_mag_fitness",
"message": {
"compass_id": 0,
"fitness": 0.95
}
}

15. drone_request_init

  • MQTT Topic: drone_request_init (без DRONE_ID)

Инициация процесса регистрации нового дрона в системе.

organization_idstrrequired
ID организации-владельца
drone_idstrrequired
ID дрона
public_keystrrequired
Публичный ключ дрона
mac_addressstrrequired
MAC-адрес дрона
{
"topic": "drone_request_init",
"message": {
"organization_id": "org-001",
"drone_id": "10001",
"public_key": "MIIBIjANBgkqhki...",
"mac_address": "AA:BB:CC:DD:EE:FF"
}
}

16. drone_request_complete

  • MQTT Topic: drone_request_complete (без DRONE_ID)

Завершение процесса регистрации дрона. Подтверждает успешное сопряжение.

drone_idstrrequired
ID зарегистрированного дрона
statusstrrequired
Результат регистрации
successРегистрация успешна
errorОшибка регистрации
{
"topic": "drone_request_complete",
"message": {
"drone_id": "10001",
"status": "success"
}
}

17. follow_info_publisher

  • MQTT Topic: {DRONE_ID}_follow_info_publisher

Информация о текущем состоянии трекинга объекта камерой.

track_idstrrequired
ID отслеживаемого объекта или none при отсутствии цели
class_namestrrequired
Класс объекта или none при отсутствии цели
statusstrrequired
Статус трекинга
trackingОбъект отслеживается
lostОбъект потерян
errorОшибка трекинга
noneТрекинг не активен
zoom_statusstrrequired
Состояние автозума
enableАвтозум активен
disenableАвтозум выключен
zoom_meanfloatrequired
Текущее среднее значение зума (1.0–15.0)
{
"topic": "10001_follow_info_publisher",
"message": {
"track_id": "42",
"class_name": "car",
"status": "tracking",
"zoom_status": "enable",
"zoom_mean": 5.0
}
}

18. drone_follow_status

  • MQTT Topic: {DRONE_ID}_drone_follow_status

Текущий статус следования дрона за объектом.

statusstrrequired
Статус следования
noneСледование не активно
trackingДрон следует за объектом
lostОбъект потерян, следование прервано
{
"topic": "10001_drone_follow_status",
"message": {
"status": "tracking"
}
}

19. drone_strike_status

  • MQTT Topic: {DRONE_ID}_drone_strike_status

Текущий статус тарана объекта дроном.

statusstrrequired
Статус тарана
noneТаран не активен
strikeТаран выполняется
lostОбъект потерян, таран прерван
{
"topic": "10001_drone_strike_status",
"message": {
"status": "strike"
}
}

20. download_info

  • MQTT Topic: {DRONE_ID}_download_info

Прогресс загрузки файла ML-модели на дрон.

statusstrrequired
Статус загрузки
progressЗагрузка в процессе
completeЗагрузка завершена
errorОшибка загрузки
model_namestrrequired
Имя файла загружаемой модели
progress_percentint
Процент загрузки (0–100, только при status=progress)
messagestr
Текст ошибки (только при status=error)
{
"topic": "10001_download_info",
"message": {
"status": "progress",
"model_name": "yolov8n.pt",
"progress_percent": 45
}
}

21. current_model_tracking

  • MQTT Topic: {DRONE_ID}_current_model_tracking

Информация о текущей активной и всех доступных ML-моделях на дроне.

current_modelstrrequired
Имя файла текущей активной модели
available_modelsArray[str]required
Список всех доступных моделей на дроне
{
"topic": "10001_current_model_tracking",
"message": {
"current_model": "yolov8n.pt",
"available_models": [
"yolov8n.pt",
"yolov8s.pt",
"custom_model.pt"
]
}
}

22. result_delete

  • MQTT Topic: {DRONE_ID}_result_delete

Результат удаления ML-моделей. Массив объектов с результатом для каждого файла.

messageArray[object]required
Результаты удаления
file_namestrrequired
Имя файла модели
successbooleanrequired
Успешно ли удалён файл
{
"topic": "10001_result_delete",
"message": [
{
"file_name": "model_v1.pt",
"success": true
},
{
"file_name": "model_v2.pt",
"success": false
}
]
}