diff --git a/docs/ru/client.md b/docs/ru/client.md index 2e166f9..aa74cf7 100644 --- a/docs/ru/client.md +++ b/docs/ru/client.md @@ -5,101 +5,40 @@ * [Установка и запуск](start-tutorial.md#установка-и-запуск-клиента) * [Настройка клиента](#настройка-клиента) +## Схема работы клиента + +Клиент является сервисом `clever-show` в операционной системе коптера. Сервис запускает скрипт [copter_client.py](../../Drone/copter_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`, к которому может обратиться клиент по команде с сервера для экстренной посадки. + +Логи обоих сервисов записываются в файл `/var/log/syslog` операционной системы бортового компьютера Raspberry Pi на дроне. Логи текущего сеанса доступны для просмотра при выполнении команд `journalctl -u clever-show` для клиента и `journalctl -u visual_pose_watchdog` для сервиса экстренной защиты дрона в терминале, подключенном к Raspberry Pi. Логи могут быть полезны при анализе возникших нештатных или аварийных ситуаций при полёте коптера под управлением приложения клиента. + ## Настройка клиента ### Файл конфигурации -Конфигурация клиента задаётся в файле [client_config.ini](../../Drone/client_config.ini), имеющем следующий вид по умолчанию: - -```ini -[SERVER] -port = 25000 -broadcast_port = 8181 -host = 192.168.1.101 -buffer_size = 10000 - -[VISUAL_POSE_WATCHDOG] -timeout = 1.0 -pos_delta_max = 3.0 -action = emergency_land -emergency_land_thrust = 0.45 -emergency_land_decrease_thrust_after = 5.0 -timeout_to_disarm = 10.0 - -[TELEMETRY] -transmit = True -frequency = 1 -log_cpu_and_memory = True - -[COPTERS] -frame_id = map -takeoff_height = 1.0 -takeoff_time = 5.0 -safe_takeoff = False -reach_first_point_time = 5.0 -land_time = 1.0 -x0_common = 0 -y0_common = 0 -z0_common = 0 -yaw = 180 -land_timeout = 10.0 - -[FLOOR FRAME] -parent = aruco_map -x = 2.4 -y = 12.4 -z = 6.4 -roll = 180 -pitch = 0 -yaw = -90 - -[ANIMATION] -takeoff_animation_check = True -land_animation_check = True -frame_delay = 0.1 -x_ratio = 1.0 -y_ratio = 1.0 -z_ratio = 1.0 - -[PRIVATE] -id = /hostname -restart_after_rename = True -use_leds = True -led_pin = 21 -x0 = 0 -y0 = 0 -z0 = 0 - -[NTP] -use_ntp = False -host = ntp1.stratum2.ru -port = 123 - -``` +Конфигурация клиента создаётся согласно [спецификации](../../Drone/config/spec/configspec_client.ini), в ней можно посмотреть значения по умолчанию для любого параметра после ключевого слова `default`. Все изменения сохраняются в файл конфигурации `client.ini` в папке `clever-show/Drone/config`. Доступно редактирование конфигурации клиента через GUI модуль `Config editor` в приложении сервера. Для редактирования конфигурации с сервера нужно выбрать строку с клиентом, для которого требуется изменение конфигурации, кликнуть левой кнопкой мыши по любой ячейке из строки и выбрать `Edit config` из контекстного меню. Конфигурация по умолчанию является полностью работоспособной и не требует изменений для быстрого старта клиента. -Для централизованной загрузки конфигурации на все коптеры нужно использовать пункт меню `Send configurations` на [сервере](server.md#раздел-server). Допускается загрузка неполного файла параметров конфигурации, с отсутствующими разделами или параметрами относительно конфигурации по умолчанию. +Для централизованной загрузки конфигурации на все коптеры нужно использовать пункт меню `Send configurations` на [сервере](server.md#раздел-server). Допускается загрузка неполного файла параметров конфигурации, с отсутствующими разделами или параметрами относительно конфигурации по умолчанию. Также доступна опция загрузки конфигурации конкретного клиента на выделенные коптеры: для этого нужно с сервера выбрать строку с клиентом, с которого требуется скопировать конфигурацию на выделенные клиенты, кликнуть левой кнопкой мыши по любой ячейке из строки и выбрать `Copy config to selected` из контекстного меню. + +### Описание параметров #### Раздел SERVER В этом разделе задаются параметры сетевого взаимодействия клиента с сервером. Доступны следующие параметры: * `port` - TCP порт, на который будут приниматься входящие соединения от сервера. При использовании настройки [use_broadcast](server.md#раздел-broadcast) на сервере, данный порт будет сконфигурирован у клиента автоматически. *Рекомендуется изменить значение по умолчанию в целях безопасности* (любое пятизначное и более число, если другое ПО не использует выбранный порт). -* `broadcast_port` - UDP порт, на который по широковещательному каналу сервер передаёт свои настройки. С помощью данного механизма возможно автоматическое подключение клиента к серверу. * `host` - IP адрес сервера. * `buffer_size` - размер буфера при приёме и передаче данных. *Не рекомендуется изменять. Рекомендуется использовать единое значение у сервера и клиентов.* -#### Раздел VISUAL_POSE_WATCHDOG +#### Раздел BROADCAST -В данном разделе настраивается программа экстренной защиты коптера от потери позиции или столкновения с объектом. +В этом разделе включается/выключается механизм получения broadcast пакетов по UDP с сервера. -* `timeout` - время срабатывания экстренной защиты после потери визуальной позиции, в секундах. -* `pos_delta_max` - максимальная разница между текущим положением и точкой, в которой сейчас должен находиться коптер, в метрах. Требуется для проверки на столкновение коптера с объектом. Если расстояние между текущим положением коптера и положением, в котором он должен сейчас находиться, больше этого числа (в метрах), срабатывает экстренная защита. -* `action` - действие при срабатывании экстренной защиты. Доступные варианты: `land` - посадка коптера в режиме полётного контроллера AUTO.LAND, `emergency_land` - посадка коптера с постепенным уменьшением мощности моторов, `disarm`- выключение моторов. **Внимание!** Не рекомендуется использовать режим AUTO.LAND с выключенным барометром - при потере источника высоты в полёте, например показаний лазера или визуальной позиции, режим AUTO.LAND не гарантирует посадку коптера, так как ориентируется на показания высоты. Для посадки коптера при его позиционировании с использованием визуальной позиции или лазера и возможности потери данных с этих систем рекомендуется использовать режим `emergency_land`. -* `emergency_land_thrust` - начальная мощность, подаваемая на моторы в случае выбора действия `emergency_land` при срабатывании экстренной защиты. Безразмерная величина, от 0 (отсутствие мошности) до 1 (полная мощность). Для гарантированной посадки рекомендуется устанавливать в значение, меньшее по величине на 5-10 процентов, чем газ висения (параметр `MPC_THR_HOVER` в px4). -* `emergency_land_decrease_thrust_after` - время, через которое мощность на моторах плавно начинает уменьшаться в случае выбора действия `emergency_land` при срабатывании экстренной защиты, в секундах. -* `timeout_to_disarm` - время, через которое коптер безусловно выключает моторы после срабатывания экстренной защиты, в секундах. +* `use` - логическое значение, определяет, использовать или не использовать механизм получения broadcast пакетов по UDP с сервера. +* `port` - порт UDP для приёма broadcast сообщений. #### Раздел TELEMETRY @@ -107,9 +46,28 @@ port = 123 * `transmit` - логическое значение, определяет, нужно ли передавать данные на сервер. * `frequency` - частота передачи данных на сервер, целочисленное значение, количество раз в секунду. -* `log_cpu_and_memory` - логическое значение, определяет, будет ли записываться в лог сервиса клиента clever-show состояние процессора и памяти. +* `log_resources` - логическое значение, определяет, будет ли записываться в лог сервиса клиента clever-show состояние бортового компьютера Raspberry Pi: загрузка процессора и оперативной памяти, температура процессора, состояние температуры, состояние системы питания. -#### Раздел COPTERS +#### Раздел POSITION WATCHDOG + +В данном разделе настраивается программа экстренной защиты коптера от потери позиции или столкновения с объектом. + +* `enabled` - логическое значение, определяет, использовать или нет экстренную защиту при потере визуальной позиции или столкновении с объектом. +* `log_state` - логическое значение, определяет, будет ли записываться в лог сервиса состояние коптера: `armed: {} | mode: {} | vis_dt: {:.2f} | pos_delta: {:.2f} | pos_dt: {:.2f} | range: {:.2f} | watchdog_action: {}`. +* `action` - действие при срабатывании экстренной защиты. Доступные варианты: `land` - посадка коптера в режиме полётного контроллера AUTO.LAND, `emergency_land` - посадка коптера с постепенным уменьшением мощности моторов, `disarm`- выключение моторов. **Внимание!** Не рекомендуется использовать режим AUTO.LAND с выключенным барометром - при потере источника высоты в полёте, например показаний лазера или визуальной позиции, режим AUTO.LAND не гарантирует посадку коптера, так как ориентируется на показания высоты. Для посадки коптера при его позиционировании с использованием визуальной позиции или лазера и возможности потери данных с этих систем рекомендуется использовать режим `emergency_land`. +* `vision_pose_delay_after_arm` - время после взлёта коптера в секундах, которое требуется для получения визуальной позиции. В течение этого времени после взлёта защита по потере визуальной позиции не будет срабатывать. Этот параметр полезен при использовании модуля экстренной защиты совместно с системой позиционирования по aruco маркерам, расположенным на полу: при взлёте коптер какое-то время не имеет визуальной позиции. +* `vision_pose_timeout` - время в секундах после потери визуальной позиции, через которое срабатывает экстренная защита. +* `position_delta_max` - максимальная разница между текущим положением и точкой, в которой сейчас должен находиться коптер, в метрах. Требуется для проверки на столкновение коптера с объектом. Если расстояние между текущим положением коптера и положением, в котором он должен сейчас находиться, больше этого числа (в метрах), срабатывает экстренная защита. +* `disarm_timeout` - время, через которое коптер безусловно выключает моторы после срабатывания экстренной защиты, в секундах. + +#### Раздел EMERGENCY LAND + +Настройки параметров экстренной посадки при действии `emergency_land` экстренной защиты или при вызове ROS сервиса `/emergency_land`. + +* `thrust` - начальная мощность, подаваемая на моторы в случае выбора действия `emergency_land` при срабатывании экстренной защиты. Безразмерная величина, от 0 (отсутствие мошности) до 1 (полная мощность). Для гарантированной посадки рекомендуется устанавливать в значение, меньшее по величине на 5-10 процентов, чем газ висения (параметр `MPC_THR_HOVER` в px4). **Внимание!** Неправильная настройка этого параметра может привести к взлёту коптера вверх вместо посадки! +* `decrease_thrust_after` - время, через которое мощность на моторах плавно начинает уменьшаться в случае выбора действия `emergency_land` при срабатывании экстренной защиты, в секундах. + +#### Раздел COPTER В данном разделе находятся настройки, влияющие на процесс полёта коптера. @@ -119,23 +77,17 @@ port = 123 * `safe_takeoff` - логическое значение, определяет, нужно ли производить посадку в безопасном режиме. * `reach_first_point_time` - максимальное время полёта к первой точке анимации, в секундах. * `land_time` - время зависания в конечной точке анимации перед посадкой, в секундах. -* `x0_common` - смещение по оси x, общее для всех коптеров, в метрах. -* `y0_common` - смещение по оси y, общее для всех коптеров, в метрах. -* `z0_common` - смещение по оси z, общее для всех коптеров, в метрах. -* `yaw` - поворот коптера при полёте по точкам, в градусах. Если значение `nan` - коптер сохраняет изначальную ориентацию в полёте. * `land_timeout` - время таймаута посадки, после которого происходит выключение моторов коптера, в секундах. +* `common_offset` - смещение координат относительно текущей системы, общее для всех коптеров, в метрах. Список из 3 величин (x, y, z): каждая величина задаёт смещение по соответствующей оси. #### Раздел FLOOR_FRAME Данный раздел описывает смещение системы координат с названием `floor` и используется только при указании параметра `frame_id` как `floor` в разделе [COPTERS](#раздел-copters). +* `enabled` - логическое значение, определяет, нужно ли публиковать фрейм `floor` * `parent` - название опорной системы координат, относительно которой будет располагаться система координат `floor`. -* `x` - смещение системы координат `floor` по оси x относительно системы координат `parent`, в метрах. -* `y` - смещение системы координат `floor` по оси y относительно системы координат `parent`, в метрах. -* `z` - смещение системы координат `floor` по оси z относительно системы координат `parent`, в метрах. -* `roll` - поворот системы координат `floor` вокруг оси x относительно системы координат `parent`, в градусах. -* `pitch` - поворот системы координат `floor` вокруг оси y относительно системы координат `parent`, в градусах. -* `yaw` - поворот системы координат `floor` вокруг оси z относительно системы координат `parent`, в градусах. +* `translation` - смещение системы координат `floor` по осям (x, y, z) относительно системы координат `parent`, в метрах. +* `rotation` - поворот системы координат `floor` на углы (roll, pitch, yaw) вокруг осей (x, y, z) относительно системы координат `parent`, в градусах. **Внимание!** Повороты `roll`, `pitch`, `yaw` производятся последовательно в указанном порядке. @@ -143,24 +95,33 @@ port = 123 В данном разделе настраивается обработка анимации. -* `takeoff_animation_check` - логическое значение, определяет, будет ли производиться автоматическая обработка старта анимации. **Если значение True**, при загрузке анимации проверяется взлёт коптеров. Если в файле анимации коптер взлетает с земли, при старте анимации будет применена *логика немедленного воспроизведения*: коптер сразу начинает следовать точкам, указанным в анимации. Если в файле анимации коптер начинает полёт в воздухе, при старте анимации будет применена *логика полёта к первой точке*: коптер в начале взлетает на высоту `takeoff_height` за время `takeoff_time`, затем перемещается к первой точке за время `reach_first_point_time`, и затем начинает следовать точкам, указанным в анимации. **Если значение False**, при загрузке анимации не проверяется взлёт коптеров, а при старте анимации действует *логика полёта к первой точке*. -* `land_animation_check` - логическое значение, определяет, будет ли производиться автоматическая обработка завершения анимации. **Если значение True**, при загрузке анимации проверяется посадка коптеров. Если в файле анимации коптер садится на землю и стоит до завершения анимации, проверка удалит все точки в анимации после начала посадки коптера. Таким образом, коптер в конце анимации зависнет над точкой посадки на время `land_time`, сядет автоматически и выключит моторы. **Если значение False**, при загрузке анимации не проверяется посадка коптеров и точкой посадки считается последняя точка в анимации. Например, если анимация посадки нарисована полностью и коптер стоит после посадки на земле некоторое время, а значение данного параметра **False**, всё это время у коптера будут включены моторы и он будет пытаться удержать указанную позицию посадки вплоть до завершении файла анимации, затем через время `land_time` перейдёт в редим посадки. +* `takeoff_detection` - логическое значение, определяет, будет ли производиться автоматическая обработка старта анимации. **Если значение True**, при загрузке анимации проверяется взлёт коптеров. Если в файле анимации коптер взлетает с земли, при старте анимации будет применена *логика немедленного воспроизведения*: коптер сразу начинает следовать точкам, указанным в анимации. Если в файле анимации коптер начинает полёт в воздухе, при старте анимации будет применена *логика полёта к первой точке*: коптер в начале взлетает на высоту `takeoff_height` за время `takeoff_time`, затем перемещается к первой точке за время `reach_first_point_time`, и затем начинает следовать точкам, указанным в анимации. **Если значение False**, при загрузке анимации не проверяется взлёт коптеров, а при старте анимации действует *логика полёта к первой точке*. +* `land_detection` - логическое значение, определяет, будет ли производиться автоматическая обработка завершения анимации. **Если значение True**, при загрузке анимации проверяется посадка коптеров. Если в файле анимации коптер садится на землю и стоит до завершения анимации, проверка удалит все точки в анимации после начала посадки коптера. Таким образом, коптер в конце анимации зависнет над точкой посадки на время `land_time`, сядет автоматически и выключит моторы. **Если значение False**, при загрузке анимации не проверяется посадка коптеров и точкой посадки считается последняя точка в анимации. Например, если анимация посадки нарисована полностью и коптер стоит после посадки на земле некоторое время, а значение данного параметра **False**, всё это время у коптера будут включены моторы и он будет пытаться удержать указанную позицию посадки вплоть до завершении файла анимации, затем через время `land_time` перейдёт в редим посадки. * `frame_delay` - время воспроизведения одного кадра в секундах. -* `x_ratio` - масштаб анимации по оси x -* `y_ratio` - масштаб анимации по оси y -* `z_ratio` - масштаб анимации по оси z +* `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`. -* `restart_dhcpcd` - логический параметр, определяет, требуется ли перезагрузка коптера при переименовании его `id` удалённо с сервера. -* `use_leds` - логический параметр, определяет, использует ли коптер светодиодную ленту. -* `led_pin` - номер пина GPIO на Raspberry Pi, к которому подключена светодиодная лента. -* `x0` - смещение по оси x, только для данного коптера. -* `y0` - смещение по оси y, только для данного коптера. -* `z0` - смещение по оси z, только для данного коптера. +* `offset` - смещение в метрах по осям (x, y, z) относительно текущей системы координат, только для данного коптера. + +#### Раздел SYSTEM + +Системные настройки служебных команд клиента + +* `change_hostname` - логический параметр, определяет, требуется ли смена hostname при переименовании `id` коптера. +* `restart_after_rename` - логический параметр, определяет, требуется ли перезагрузка коптера при переименовании его `id` удалённо с сервера. #### Раздел NTP