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
Уведомление о потере потока
true— URL видеопотока потерян, требуется повторная отправка
{
"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
}
]
}