API Server-Drone v2.1
API интеграции MQTT-топиков между сервером и дроном проекта Wheelies.
Протокол: MQTT
Формат данных: JSON
Дата: 12.02.2025
Формат топика: {DRONE_ID}_{topic_name}
Типы данных
Point
latfloatrequiredlongfloatrequiredheightfloatPosition
pointPointrequiredlatfloatrequiredlongfloatrequiredheightfloatdirectionintrequiredspeedfloatСервер → Дрон
1. mission
- MQTT Topic:
{DRONE_ID}_mission
Отправка миссии на дрон. Топик get_mission переименован в mission начиная с v2.0.
mission_iduuidrequiredparamsArray[Param]requiredparam_iduuidrequirednamestrtypestrrequiredpoint— Точкаfloat— Числоboolean— Логическое значениеvalueMixedcommandsArray[Command]requiredcommand_iduuidrequiredcommand_typestrrequiredmove_to— Перелёт к точкеcoverage— Покрытие областиland— Посадкаtakeoff— Взлётscan_area— Сканирование областиby_path— Движение по маршрутуpointsArray[Point]requiredlatfloatrequiredlongfloatrequiredheightfloatparamsArray[Object]requiredtriggersArray[Trigger]conditionstrrequiredcommand_idstrrequiredpriorityintrequired{
"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
Пауза или возобновление выполнения миссии.
messagestrrequiredon— Поставить на паузуoff— Возобновить выполнение{
"topic": "10001_pause_mission",
"message": "on"
}
3. cancel_mission
- MQTT Topic:
{DRONE_ID}_cancel_mission
Отмена текущей миссии.
messagestrrequiredBACK_TO_START— Возврат на точку стартаON_CURRENT_PLACE— Посадка на текущем месте{
"topic": "10001_cancel_mission",
"message": "BACK_TO_START"
}
4. use_hand_mode
- MQTT Topic:
{DRONE_ID}_use_hand_mode
Переключение между ручным и автоматическим режимом управления дроном.
messagestrrequiredtrue— Ручной режимfalse— Автоматический режим{
"topic": "10001_use_hand_mode",
"message": "true"
}
5. use_ai_video
- MQTT Topic:
{DRONE_ID}_use_ai_video
Включение или выключение AI-детекции объектов на видеопотоке.
messagestrrequiredtrue— Включить 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{camera_id}objectrequiredrollintrequiredpitchintrequiredyawintrequiredzoomstrrequired0— Без зума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
Запрос текущего состояния всех модулей дрона. Дрон ответит актуальными данными телеметрии.
messagestrrequiredtrue— Запросить текущие данные{
"topic": "10001_get_current_data",
"message": "true"
}
8. joy_control
- MQTT Topic:
{DRONE_ID}_joy_control
Ручное управление дроном. Формат сообщения: "{direction}_{speed}".
messagestrrequireddirectionstrrequiredforward— Вперёд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
Экстренное отключение моторов дрона. Используется только в аварийных ситуациях.
messagestrrequiredtrue— Немедленно отключить моторы{
"topic": "10001_critical_disarm",
"message": "true"
}
10. obstacle_avoidance
- MQTT Topic:
{DRONE_ID}_obstacle_avoidance
Глобальное включение или выключение системы обхода препятствий.
messagestrrequiredtrue— Включить обход препятствийfalse— Выключить обход препятствий{
"topic": "10001_obstacle_avoidance",
"message": "true"
}
11. camera_tracking
- MQTT Topic:
{DRONE_ID}_camera_tracking
Выбор камеры, используемой для AI-трекинга объектов.
messagestrrequired{
"topic": "10001_camera_tracking",
"message": "camera_front"
}
12. stream_url
- MQTT Topic:
{DRONE_ID}_stream_url
Передача URL видеопотока на дрон для конкретной камеры.
camera_idstrrequiredprovider_urlstrrequiredexpire_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
Запрос текущих данных калибровки сенсоров дрона.
messagestrrequiredtrue— Запросить данные калибровки{
"topic": "10001_get_calibration_data",
"message": "true"
}
14. set_calibration
- MQTT Topic:
{DRONE_ID}_set_calibration
Установка параметров калибровки сенсоров.
stepintrequiredparamstrrequired{
"topic": "10001_set_calibration",
"message": {
"step": 1,
"param": "accel"
}
}
15. get_check_motors
- MQTT Topic:
{DRONE_ID}_get_check_motors
Запрос текущих данных проверки моторов.
messagestrrequiredtrue— Запросить данные моторов{
"topic": "10001_get_check_motors",
"message": "true"
}
16. set_check_motors
- MQTT Topic:
{DRONE_ID}_set_check_motors
Запуск проверки моторов с указанным PWM-значением.
idintrequiredvalueintrequired{
"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_keystrrequiredaes_keystrrequired{
"topic": "10001_drone_request_approve",
"message": {
"public_key": "MIIBIjANBgkqhki...",
"aes_key": "aGVsbG8gd29ybGQ="
}
}
20. send_file_link
- MQTT Topic:
{DRONE_ID}_send_file_link
Отправка ссылки для загрузки ML-модели на дрон.
file_namestrrequiredfile_linkstrrequiredtokenstrrequired{
"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{
"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
Управление автоматическим сканированием подвеса камеры.
statusstrrequiredstart— Запустить автосканированиеstop— Остановить автосканированиеcurrent— Запросить текущий статусtypestrrequiredsin— Синусоидальное движение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
Управление слежением камеры за объектом (трекинг).
statusstrrequiredstart— Начать слежениеstop— Прекратить слежениеtrack_idstrrequiredclass_namestrrequiredzoom_statusstrenable— Автозум включёнdisenable— Автозум выключенzoom_meanfloat{
"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
Управление следованием дрона за объектом (дрон физически перемещается за целью).
statusstrrequiredstart— Начать следованиеstop— Прекратить следованиеtrack_idstrrequiredclass_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
Управление тараном объекта дроном.
statusstrrequiredstart— Начать таранstop— Прекратить таранtrack_idstrrequiredclass_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.
positionPositionrequiredpointPointrequiredlatfloatrequiredlongfloatrequiredheightfloatdirectionintrequiredspeedfloatbattery_levelintrequiredheadingintrequiredstatusstrrequiredonline— В сети, готов к работеoffline— Не в сетиemergency landing— Аварийная посадкаon mission— Выполняет миссиюreturning— Возвращается на точку стартаtaking off— Взлетаетlanding— Совершает посадкуpaused— Миссия на паузеmission_iduuidrequiredcommand_iduuidrequireduse_ai_videobooleanrequireduse_hand_modebooleanrequiredpausebooleanrequiredobstacle_avoidancebooleanrequiredcamera_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{
"topic": "10001_mission_received",
"message": "01939ba1-fd8a-7ed4-acb1-35791c03c70d"
}
3. mission_completed
- MQTT Topic:
{DRONE_ID}_mission_completed
Уведомление о завершении миссии.
messageuuidrequired{
"topic": "10001_mission_completed",
"message": "01939ba1-fd8a-7ed4-acb1-35791c03c70d"
}
4. mission_cancelled
- MQTT Topic:
{DRONE_ID}_mission_cancelled
Уведомление об отмене миссии.
messageuuidrequired{
"topic": "10001_mission_cancelled",
"message": "01939ba1-fd8a-7ed4-acb1-35791c03c70d"
}
5. objects_data
- MQTT Topic:
{DRONE_ID}_objects_data
Метаданные детектируемого объекта без изображения. Передаётся при каждом обнаружении.
namestrrequiredidinttimedatetimerequiredpositionPositionrequiredpointPointrequiredlatfloatrequiredlongfloatrequiredheightfloatdirectionintrequiredspeedfloatdrone_pointPointrequiredlatfloatrequiredlongfloatrequired{
"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.
namestrrequiredidinttimedatetimerequiredphotoBase64requiredlatfloatrequiredlongfloatrequired{
"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}objectrequiredrollintrequiredpitchintrequiredyawintrequiredzoomintrequired{
"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
Статус автоматического сканирования подвеса.
statusstrrequiredstart— Автосканирование запущеноstop— Автосканирование остановленоtypestrrequiredsin— Синусоидальное движение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
Данные о текущем состоянии калибровки сенсоров.
stepintrequiredparamstrrequiredstatusstrrequiredin_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{
"topic": "10001_check_motors_data",
"message": [1200, 1200, 1200, 1200]
}
12. stream_lost
- MQTT Topic:
{DRONE_ID}_stream_lost
Уведомление о потере URL видеопотока. Сервер должен отправить актуальный URL через stream_url.
messagestrrequiredtrue— URL видеопотока потерян, требуется повторная отправка{
"topic": "10001_stream_lost",
"message": "true"
}
13. payload
- MQTT Topic:
{DRONE_ID}_payload
Полный статус оборудования дрона: камеры, SD-карта, прошивка, контроллер, состояние связи.
camerasArray[object]sd_cardobjectfirmwarestrcontrollerstrconnectionobject{
"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_idintrequiredfitnessfloatrequired{
"topic": "10001_mag_fitness",
"message": {
"compass_id": 0,
"fitness": 0.95
}
}
15. drone_request_init
- MQTT Topic:
drone_request_init(без DRONE_ID)
Инициация процесса регистрации нового дрона в системе.
organization_idstrrequireddrone_idstrrequiredpublic_keystrrequiredmac_addressstrrequired{
"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_idstrrequiredstatusstrrequiredsuccess— Регистрация успешнаerror— Ошибка регистрации{
"topic": "drone_request_complete",
"message": {
"drone_id": "10001",
"status": "success"
}
}
17. follow_info_publisher
- MQTT Topic:
{DRONE_ID}_follow_info_publisher
Информация о текущем состоянии трекинга объекта камерой.
track_idstrrequiredclass_namestrrequiredstatusstrrequiredtracking— Объект отслеживаетсяlost— Объект потерянerror— Ошибка трекингаnone— Трекинг не активенzoom_statusstrrequiredenable— Автозум активенdisenable— Автозум выключенzoom_meanfloatrequired{
"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
Текущий статус следования дрона за объектом.
statusstrrequirednone— Следование не активноtracking— Дрон следует за объектомlost— Объект потерян, следование прервано{
"topic": "10001_drone_follow_status",
"message": {
"status": "tracking"
}
}
19. drone_strike_status
- MQTT Topic:
{DRONE_ID}_drone_strike_status
Текущий статус тарана объекта дроном.
statusstrrequirednone— Таран не активенstrike— Таран выполняетсяlost— Объект потерян, таран прерван{
"topic": "10001_drone_strike_status",
"message": {
"status": "strike"
}
}
20. download_info
- MQTT Topic:
{DRONE_ID}_download_info
Прогресс загрузки файла ML-модели на дрон.
statusstrrequiredprogress— Загрузка в процессеcomplete— Загрузка завершенаerror— Ошибка загрузкиmodel_namestrrequiredprogress_percentintmessagestr{
"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_modelstrrequiredavailable_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]requiredfile_namestrrequiredsuccessbooleanrequired{
"topic": "10001_result_delete",
"message": [
{
"file_name": "model_v1.pt",
"success": true
},
{
"file_name": "model_v2.pt",
"success": false
}
]
}