From b757b99f2ab941e5a1c5904a9dd0f1f42fc432c8 Mon Sep 17 00:00:00 2001 From: Arthur Golubtsov Date: Fri, 5 Jun 2020 16:46:25 +0300 Subject: [PATCH] docs: Update client article --- docs/ru/client.md | 162 +++++++++++++++++++++++++++++----------------- 1 file changed, 104 insertions(+), 58 deletions(-) diff --git a/docs/ru/client.md b/docs/ru/client.md index aa74cf7..c781136 100644 --- a/docs/ru/client.md +++ b/docs/ru/client.md @@ -2,29 +2,48 @@ Приложение для удаленного синхронизированного управления дронами в шоу и модуль экстренной защиты дронов. +* `client.py` - основной модуль связи и управления дроном +* `failsafe.py` - модуль защиты дронов, который создает сервис `/emergency_land` и контролирует состояние дрона в соответствии с логикой, указанной в пунктах `[FAILSAFE]` и `[EMERGENCY LAND]` файла настроек `client.ini` + +## Инструкции + * [Установка и запуск](start-tutorial.md#установка-и-запуск-клиента) * [Настройка клиента](#настройка-клиента) -## Схема работы клиента +## Схема работы клиента в образе для Raspberry Pi -Клиент является сервисом `clever-show` в операционной системе коптера. Сервис запускает скрипт [copter_client.py](../../Drone/copter_client.py) и автоматически запускается при загрузке операционной системы. В случае необходимости применения параметров обновлённой конфигурации клиента сервис может быть перезапущен. Сервис `clever-show` предназначен для управления и настройки коптера для группового полёта с помощью приложения сервера. +Клиент является сервисом `clever-show` в операционной системе коптера. Сервис запускает скрипт [client.py](../../drone/client.py) и автоматически запускается при загрузке операционной системы. В случае необходимости применения параметров обновлённой конфигурации клиента сервис может быть перезапущен. Сервис `clever-show` предназначен для управления и настройки коптера для группового полёта с помощью приложения сервера. -Вместе с клиентом в операционной системе зарегистрирован сервис экстренной защиты дрона `visual_pose_watchdog`. Данный сервис запускает скрипт [visual_pose_watchdog.py](../../Drone/visual_pose_watchdog.py) и автоматически запускается при загрузке операционной системы. В случае необходимости применения параметров обновлённой конфигурации клиента сервис может быть перезапущен. Сервис `visual_pose_watchdog` предназначен для автоматической посадки коптера в экстренных ситуациях: при отсутствии сообщений о позиции дрона из топика `/mavros/vision_pose/pose` и при столкновении с объектами в полёте, когда расстояние между текущей точкой, где находится коптер, и точкой, где ему следует находиться по полётному заданию, превышает пороговое значение. Также `visual_pose_watchdog` предоставляет ROS сервис `/emergency_land`, к которому может обратиться клиент по команде с сервера для экстренной посадки. +Вместе с клиентом в операционной системе зарегистрирован сервис экстренной защиты дрона `failsafe`. Данный сервис запускает скрипт [failsafe.py](../../drone/failsafe.py) и автоматически запускается при загрузке операционной системы. В случае необходимости применения параметров обновлённой конфигурации клиента сервис может быть перезапущен. -Логи обоих сервисов записываются в файл `/var/log/syslog` операционной системы бортового компьютера Raspberry Pi на дроне. Логи текущего сеанса доступны для просмотра при выполнении команд `journalctl -u clever-show` для клиента и `journalctl -u visual_pose_watchdog` для сервиса экстренной защиты дрона в терминале, подключенном к Raspberry Pi. Логи могут быть полезны при анализе возникших нештатных или аварийных ситуаций при полёте коптера под управлением приложения клиента. +Сервис `failsafe` предназначен для автоматической посадки коптера в экстренных ситуациях: + +* при отсутствии сообщений о позиции дрона из топика `/mavros/vision_pose/pose` +* при столкновении с объектами в полёте, когда расстояние между текущей точкой, где находится коптер, и точкой, где ему следует находиться по полётному заданию, превышает пороговое значение. + +Также `failsafe` предоставляет ROS сервис `/emergency_land`, к которому может обратиться клиент по команде с сервера для экстренной посадки дрона. + +Логи обоих сервисов записываются в файл `/var/log/syslog` операционной системы бортового компьютера Raspberry Pi на дроне. Логи текущего сеанса доступны для просмотра при выполнении команд `journalctl -u clever-show` для клиента и `journalctl -u failsafe` для сервиса экстренной защиты дрона в терминале, подключенном к Raspberry Pi. Логи могут быть полезны при анализе возникших нештатных или аварийных ситуаций при полёте коптера под управлением приложения клиента. ## Настройка клиента ### Файл конфигурации -Конфигурация клиента создаётся согласно [спецификации](../../Drone/config/spec/configspec_client.ini), в ней можно посмотреть значения по умолчанию для любого параметра после ключевого слова `default`. Все изменения сохраняются в файл конфигурации `client.ini` в папке `clever-show/Drone/config`. Доступно редактирование конфигурации клиента через GUI модуль `Config editor` в приложении сервера. Для редактирования конфигурации с сервера нужно выбрать строку с клиентом, для которого требуется изменение конфигурации, кликнуть левой кнопкой мыши по любой ячейке из строки и выбрать `Edit config` из контекстного меню. +Конфигурация клиента создаётся согласно [спецификации](../../drone/config/spec/configspec_client.ini), в ней можно посмотреть значения по умолчанию для любого параметра после ключевого слова `default`. Все изменения сохраняются в файл конфигурации `client.ini` в папке `clever-show/drone/config`. Доступно редактирование конфигурации клиента через GUI модуль `Config editor` в приложении сервера. Для редактирования конфигурации с сервера нужно выбрать строку с клиентом, для которого требуется изменение конфигурации, кликнуть левой кнопкой мыши по любой ячейке из строки и выбрать `Edit config` из контекстного меню. Конфигурация по умолчанию является полностью работоспособной и не требует изменений для быстрого старта клиента. -Для централизованной загрузки конфигурации на все коптеры нужно использовать пункт меню `Send configurations` на [сервере](server.md#раздел-server). Допускается загрузка неполного файла параметров конфигурации, с отсутствующими разделами или параметрами относительно конфигурации по умолчанию. Также доступна опция загрузки конфигурации конкретного клиента на выделенные коптеры: для этого нужно с сервера выбрать строку с клиентом, с которого требуется скопировать конфигурацию на выделенные клиенты, кликнуть левой кнопкой мыши по любой ячейке из строки и выбрать `Copy config to selected` из контекстного меню. +Для централизованной загрузки конфигурации на все коптеры нужно использовать пункт меню `Send configurations` на [сервере](server.md#раздел-server). Допускается загрузка неполного файла параметров конфигурации, с отсутствующими разделами или параметрами относительно конфигурации по умолчанию. Также доступна опция загрузки конфигурации конкретного клиента на выделенные коптеры: для этого нужно в приложении сервера выбрать строку с клиентом, с которого требуется скопировать конфигурацию на выделенные клиенты, кликнуть левой кнопкой мыши по любой ячейке из строки и выбрать `Copy config to selected` из контекстного меню. ### Описание параметров +#### Основной раздел + +* `config_name` - название конфигурации +* `config_version` - версия конфигурации +* `id` - имя коптера, отображаемое в таблице. Если значение `/hostname` - имя определяется из файла `/etc/hostname`. +* `clover_dir` - путь к директории с ROS пакетом [Clover](https://github.com/CopterExpress/clover). Необходим для загрузки файлов с картами aruco меток и launch файлов настройки запуска сервиса `clover`. Если значение `auto` - клиент пытается сам определить нужную директорию через `roscd clover` (или `roscd clever`) при первом запуске. Если директорию с пакетом не удаётся определить, значение устанавливается в `error`, а файлы, специфичные для настройки ROS пакета `Clover` не передаются с сервера на клиент. + #### Раздел SERVER В этом разделе задаются параметры сетевого взаимодействия клиента с сервером. Доступны следующие параметры: @@ -46,11 +65,87 @@ * `transmit` - логическое значение, определяет, нужно ли передавать данные на сервер. * `frequency` - частота передачи данных на сервер, целочисленное значение, количество раз в секунду. -* `log_resources` - логическое значение, определяет, будет ли записываться в лог сервиса клиента clever-show состояние бортового компьютера Raspberry Pi: загрузка процессора и оперативной памяти, температура процессора, состояние температуры, состояние системы питания. +* `log_resources` - логическое значение, определяет, будет ли записываться в лог сервиса клиента clever-show состояние бортового компьютера: загрузка процессора и оперативной памяти, температура процессора, состояние температуры, состояние системы питания (только для Raspberry Pi). -#### Раздел POSITION WATCHDOG +#### Раздел FLIGHT -В данном разделе настраивается программа экстренной защиты коптера от потери позиции или столкновения с объектом. +В данном разделе находятся настройки, влияющие на процесс полёта коптера. + +* `frame_id` - название системы координат, относительно которой будут публиковаться координаты точек для воспроизведения анимации. Если значение `floor` - клиент публикует статическую систему координат с названием `floor` и настройками из раздела [FLOOR_FRAME](#раздел-floor_frame). **Внимание!** Убедитесь, что коптер удерживает позицию в данной системе координат. Для этого вы можете воспользоваться командой [Takeoff](server.md#тестовые-команды) из серверного приложения. Коптер взлетит на высоту `takeoff_height` относительно текущей. +* `takeoff_height` - высота взлёта коптера, в метрах. Используется в начале воспроизведения анимации или при тестировании коптера с сервера. +* `takeoff_time` - максимальное время взлёта коптера, в секундах. +* `reach_first_point_time` - максимальное время полёта к первой точке анимации, в секундах. +* `land_time` - время зависания в конечной точке анимации перед посадкой, в секундах. +* `land_timeout` - время таймаута посадки, после которого происходит выключение моторов коптера, в секундах. + +#### Раздел FLOOR FRAME + +Данный раздел описывает смещение системы координат с названием `floor` и используется только при указании параметра `frame_id` как `floor` в разделе [COPTERS](#раздел-copters). + +* `enabled` - логическое значение, определяет, нужно ли публиковать фрейм `floor` +* `parent` - название опорной системы координат, относительно которой будет располагаться система координат `floor`. +* `translation` - смещение системы координат `floor` по осям (x, y, z) относительно системы координат `parent`, в метрах. +* `rotation` - поворот системы координат `floor` на углы (roll, pitch, yaw) вокруг осей (x, y, z) относительно системы координат `parent`, в градусах. + +**Внимание!** Повороты `roll`, `pitch`, `yaw` производятся последовательно в указанном порядке. + +#### Раздел GPS FRAME + +Данный раздел описывает создание системы координат с названием `gps`. Начальное положение этой системы координат лежит в точке с координатами `lat` (latitude, широта), `lon` (longitude, долгота). Угол поворота задаётся значением `yaw` (в градусах) поворотом оси z начального положения коптера в системе координат `map`. + +* `lat` - широта в градусах в системе WGS 84 +* `lon` - долгота в градусах в системе WGS 84 +* `yaw` - угол поворота системы координат в градусах + +#### Раздел ANIMATION + +В данном разделе настраивается обработка анимации. За обработку анимации отвечает отдельный модуль [animation](../../drone/modules/animation.py). При загрузке анимации на коптер модуль производит разделение последовательности кадров анимации на 5 ключевых этапов: + +1. Коптер неподвижен в начале анимации - `static_begin` +2. Коптер взлетает - `takeoff` +3. Коптер следует по маршруту анимации - `route` +4. Коптер выполняет посадку - `land` +5. Коптер неподвижен до завершения файла анимации - `static_end` + +Кадр анимации - это набор данных, необходимых для позиционирования коптера и определения цвета его подсветки. В текущей версии ПО кадр анимации представлен последовательностью чисел `x y z yaw r g b` в строке `.csv` файла с анимацией, где: + +* `x`, `y`, `z` - координаты коптера в текущем кадре в метрах +* `yaw` - рыскание коптера в радианах +* `r`, `g`, `b` - компоненты цвета подсветки коптера, целые числа от 0 до 255 + +После разделения анимации на ключевые этапы модуль формирует выходную последовательность кадров, определяющих положение коптера и цвет его подсветки, а также последовательность действий при полёте к первой точке анимации. Настройка модуля производится с помощью следующих параметров: + +* `start_action` - первое действие при запуске воспроизведения анимации. Доступные варианты: + * `auto` - автоматический выбор действия между `takeoff` (взлёт) или `fly` (мгновенный полёт по точкам) на основе текущего уровня высоты коптера. Если (`z` в начальной точке анимации) - (текущая высота коптера) > (уровень взлета `takeoff_level`), то значение устанавливается в `takeoff`, иначе значение устанавливается в `fly`. + * `takeoff` - выполнение *логики полёта к первой точке*. + * `fly` - выполнение *логики немедленного полёта* + + Если в файле анимации коптер взлетает с земли, при старте анимации будет применена *логика немедленного воспроизведения*: коптер включает двигатели через время, которое требуется для выполнения начальных кадров анимации, которые не включены в выходную последовательность, затем через время `arming_time` начинает следовать точкам, указанным в анимации. Если в файле анимации коптер начинает полёт в воздухе, при старте анимации будет применена *логика полёта к первой точке*: через время, которое требуется для выполнения начальных кадров анимации, которые не включены в выходную последовательность, коптер в начале взлетает на высоту `takeoff_height` за время `takeoff_time`, затем перемещается к первой точке за время `reach_first_point_time`, и затем начинает следовать точкам, указанным в анимации. + +* `takeoff_level` - уровень взлёта для автоматического определения первого действия коптера при старте анимации +* `ground_level` - уровень земли, используется для проверки, не попытается ли коптер улететь под землю при воспроизведении анимации. Доступные варианты настройки: + * `current` - за уровень земли принимается текущий уровень высоты коптера перед стартом. + * координата z в метрах +* `frame_delay` - время воспроизведения одного кадра в секундах. +* `yaw` - поворот коптера при полёте по точкам, в градусах. Если значение `nan` - коптер сохраняет изначальную ориентацию в полёте. Если значение `animation` - коптер берёт поворот по yaw из файла с анимацией. +* `ratio` - масштаб анимации (ratio_x, ratio_y, ratio_z) по осям (x, y, z) +* `common_offset` - смещение анимации относительно текущей системы, общее для всех коптеров, в метрах. Список из 3 величин (x, y, z): каждая величина задаёт смещение по соответствующей оси. +* `private_offset` - смещение анимации относительно текущей системы, только для данного коптера, в метрах. Список из 3 величин (x, y, z): каждая величина задаёт смещение по соответствующей оси. +* `[[OUTPUT]]` - флаги, определяющие, какие этапы будут включены в выходную последовательность кадров. + +#### Раздел LED + +Настройки адресуемой светодиодной ленты на коптере + +* `use` - логическое значение, определяет, используется или нет светодиодная лента. +* `pin` - номер пина GPIO на Raspberry, к которому подключается лента +* `count` - количество задействованных светодиодов в ленте +* `takeoff_indication` - логическое значение, определяет, использовать ли подсветку для обозначения взлёта +* `land_indication` - логическое значение, определяет, использовать ли подсветку для обозначения посадки + +#### Раздел FAILSAFE + +В данном разделе настраивается программа экстренной защиты коптера от потери позиции или столкновения с объектом. Модуль `failsafe` при запуске предоставляет сервис `/emergency_land`, его настройки находятся в следующем разделе [EMERGENCY LAND](#раздел-emergency-land). * `enabled` - логическое значение, определяет, использовать или нет экстренную защиту при потере визуальной позиции или столкновении с объектом. * `log_state` - логическое значение, определяет, будет ли записываться в лог сервиса состояние коптера: `armed: {} | mode: {} | vis_dt: {:.2f} | pos_delta: {:.2f} | pos_dt: {:.2f} | range: {:.2f} | watchdog_action: {}`. @@ -67,55 +162,6 @@ * `thrust` - начальная мощность, подаваемая на моторы в случае выбора действия `emergency_land` при срабатывании экстренной защиты. Безразмерная величина, от 0 (отсутствие мошности) до 1 (полная мощность). Для гарантированной посадки рекомендуется устанавливать в значение, меньшее по величине на 5-10 процентов, чем газ висения (параметр `MPC_THR_HOVER` в px4). **Внимание!** Неправильная настройка этого параметра может привести к взлёту коптера вверх вместо посадки! * `decrease_thrust_after` - время, через которое мощность на моторах плавно начинает уменьшаться в случае выбора действия `emergency_land` при срабатывании экстренной защиты, в секундах. -#### Раздел COPTER - -В данном разделе находятся настройки, влияющие на процесс полёта коптера. - -* `frame_id` - название системы координат, относительно которой будут публиковаться координаты точек для воспроизведения анимации. Если значение `floor` - клиент публикует статическую систему координат с названием `floor` и настройками из раздела [FLOOR_FRAME](#раздел-floor_frame). **Внимание!** Убедитесь, что коптер удерживает позицию в данной системе координат. Для этого вы можете воспользоваться командой [Takeoff](server.md#тестовые-команды) из серверного приложения. Коптер взлетит на высоту `takeoff_height` относительно текущей. -* `takeoff_height` - высота взлёта коптера, в метрах. Используется в начале воспроизведения анимации или при тестировании коптера с сервера. -* `takeoff_time` - максимальное время взлёта коптера, в секундах. -* `safe_takeoff` - логическое значение, определяет, нужно ли производить посадку в безопасном режиме. -* `reach_first_point_time` - максимальное время полёта к первой точке анимации, в секундах. -* `land_time` - время зависания в конечной точке анимации перед посадкой, в секундах. -* `land_timeout` - время таймаута посадки, после которого происходит выключение моторов коптера, в секундах. -* `common_offset` - смещение координат относительно текущей системы, общее для всех коптеров, в метрах. Список из 3 величин (x, y, z): каждая величина задаёт смещение по соответствующей оси. - -#### Раздел FLOOR_FRAME - -Данный раздел описывает смещение системы координат с названием `floor` и используется только при указании параметра `frame_id` как `floor` в разделе [COPTERS](#раздел-copters). - -* `enabled` - логическое значение, определяет, нужно ли публиковать фрейм `floor` -* `parent` - название опорной системы координат, относительно которой будет располагаться система координат `floor`. -* `translation` - смещение системы координат `floor` по осям (x, y, z) относительно системы координат `parent`, в метрах. -* `rotation` - поворот системы координат `floor` на углы (roll, pitch, yaw) вокруг осей (x, y, z) относительно системы координат `parent`, в градусах. - -**Внимание!** Повороты `roll`, `pitch`, `yaw` производятся последовательно в указанном порядке. - -#### Раздел ANIMATION - -В данном разделе настраивается обработка анимации. - -* `takeoff_detection` - логическое значение, определяет, будет ли производиться автоматическая обработка старта анимации. **Если значение True**, при загрузке анимации проверяется взлёт коптеров. Если в файле анимации коптер взлетает с земли, при старте анимации будет применена *логика немедленного воспроизведения*: коптер сразу начинает следовать точкам, указанным в анимации. Если в файле анимации коптер начинает полёт в воздухе, при старте анимации будет применена *логика полёта к первой точке*: коптер в начале взлетает на высоту `takeoff_height` за время `takeoff_time`, затем перемещается к первой точке за время `reach_first_point_time`, и затем начинает следовать точкам, указанным в анимации. **Если значение False**, при загрузке анимации не проверяется взлёт коптеров, а при старте анимации действует *логика полёта к первой точке*. -* `land_detection` - логическое значение, определяет, будет ли производиться автоматическая обработка завершения анимации. **Если значение True**, при загрузке анимации проверяется посадка коптеров. Если в файле анимации коптер садится на землю и стоит до завершения анимации, проверка удалит все точки в анимации после начала посадки коптера. Таким образом, коптер в конце анимации зависнет над точкой посадки на время `land_time`, сядет автоматически и выключит моторы. **Если значение False**, при загрузке анимации не проверяется посадка коптеров и точкой посадки считается последняя точка в анимации. Например, если анимация посадки нарисована полностью и коптер стоит после посадки на земле некоторое время, а значение данного параметра **False**, всё это время у коптера будут включены моторы и он будет пытаться удержать указанную позицию посадки вплоть до завершении файла анимации, затем через время `land_time` перейдёт в редим посадки. -* `frame_delay` - время воспроизведения одного кадра в секундах. -* `ratio` - масштаб анимации (ratio_x, ratio_y, ratio_z) по осям (x, y, z) -* `yaw` - поворот коптера при полёте по точкам, в градусах. Если значение `nan` - коптер сохраняет изначальную ориентацию в полёте. Если значение `animation` - коптер берёт поворот по yaw из файла с анимацией. - -#### Раздел LED - -Настройки адресуемой светодиодной ленты на коптере - -* `use` - логическое значение, определяет, используется или нет светодиодная лента. -* `pin` - номер пина GPIO на Raspberry, к которому подключается лента -* `count` - количество задействованных светодиодов в ленте - -#### Раздел PRIVATE - -В данном разделе находятся параметры, специфичные для конкретного коптера. - -* `id` - имя коптера, отображаемое в таблице. Если значение `/hostname` - имя определяется из файла `/etc/hostname`. -* `offset` - смещение в метрах по осям (x, y, z) относительно текущей системы координат, только для данного коптера. - #### Раздел SYSTEM Системные настройки служебных команд клиента