clever-show/docs/ru/positioning.md

# Настройка систем позиционирования

ПО `clover` официально поддерживает работу со следующими [системами позиционирования](https://clover.coex.tech/ru/programming.html#positioning):

* [optical flow](https://clover.coex.tech/ru/optical_flow.html)
* [aruco](https://clover.coex.tech/ru/aruco.html)
* [gps](https://clover.coex.tech/ru/gps.html)

`clever-show` поддерживает все системы позиционирования, что и `clover`.

**Приведённые ниже примеры настроек предназначены для коптера Клевер 4, собранного и настроенного согласно [документации](https://clover.coex.tech)**.

## Организация процесса настройки

Перед групповым запуском коптеров рекомендуется настроить и проверить один коптер из группы и размножить его настройки на остальные коптеры.

Настройте один коптер на работу с любой системой позиционирования из перечисленных. Настройка может включать в себя следующие этапы:

* Редактирование `.launch` файлов ROS пакета `clover`. Данные файлы находятся в директории `/home/pi/catkin_ws/src/clover/clover/launch` на коптере.
* Настройка параметров полётного контроллера.
* Редактирование файла конфигурации [клиента](client.md) `clever-show`.
* Редактирование файла конфигурации [сервера](server.md) `clever-show`.
* [Калибровка камеры](https://clover.coex.tech/ru/camera_calibration.html).

Проверьте автономный взлёт коптера: для этого выделите в таблице только один коптер, полёт которого вы ходите проверить, и нажмите кнопку `Takeoff` в правой панели приложения [сервера](server.md#тестовые-команды). Коптер должен взлететь на высоту, указанную в параметре `takeoff_height` раздела FLIGHT в конфигурации коптера (1 метр по умолчанию), и удерживать свою позицию.

Если взлёт прошёл успешно, размножьте конфигурацию клиента, настройки позиционирования и параметры полётного контроллера на остальные коптеры. Выделите в таблице успешно настроенный коптер и загрузите необходимые файлы настроек с выделенного коптера к себе на компьютер:

* `.launch` файлы для настройки ПО `clover` можно сохранить с помощью команды `Selected drones -> Retrieve file` в приложении сервера. В открывшемся диалоговом окне введите путь к файлу на коптере: `launch` файлы `clover` находятся в `/home/pi/catkin_ws/src/clover/clover/launch/`, к этому пути нужно дописать нужное имя `.launch` файла, например `/home/pi/catkin_ws/src/clover/clover/launch/clover.launch`. После нажатия кнопки `OK` в диалоговом окне откроется новое диалоговое окно с выбором пути сохранения указанного файла.
* Файл конфигурации коптера (`.ini`) можно сохранить, кликнув правой кнопкой мыши на строку с настроенным коптером, выбрав из выпадающего меню `Edit config`, затем нажав на кнопку `Save as`. Также можно перетянуть ячейку из столбца `configuration` в файловый менеджер вашей системы - сервер автоматически скопирует файл настройки в открытую директорию файлового менеджера.
* Файл конфигурации сервера (`.ini`) можно сохранить, выбрав пункт `Server -> Edit server config` из верхнего меню, затем нажав на кнопку `Save as`.
* Файл настройки полётного контроллера можно сохранить, подключившись к полётному контроллеру через приложение [QGroundControl](http://qgroundcontrol.com). Можно подключиться напрямую к полётному контроллеру [через USB порт](https://clover.coex.tech/ru/connection.html), либо через [TCP или UDP мост](https://clover.coex.tech/ru/gcs_bridge.html) (по умолчанию в образе `clever-show` настроен TCP мост, в графе `Host Address` вместо ip адреса можно ввести имя коптера с добавлением .local в конце, например clover-1.local). После подключения нужно перейти в [раздел](https://docs.px4.io/master/en/advanced_config/parameters.html#tools) `Parameters -> Tools -> Save to file...` и выбрать путь для сохранения файла параметров.
* Файл калибровки камеры полезен для уточнения визуального позиционирования. Название файла калибровки должно состоять из id коптера, для которого была сделана калибровка, с добавлением расширения `.yaml`, например `clover-1.yaml`. Для получения файла калибровки возпользуйтесь [инструкцией](https://clover.coex.tech/ru/camera_calibration.html).

После загрузки необходимых файлов с настроенного коптера, скопируйте эти файлы на остальные коптеры: выделите нужные коптеры в таблице и воспользуйтесь командами `Send -> Configuration`, `Send -> Launch files folder`, `Send -> FCU parameters file`, `Send -> Camera calibrations` из раздела `Selected drones` приложения [сервера](server.md#раздел-selected-drones).

## Настройки сервера и клиента clever-show

Набор ПО `clever-show` включает в себя множество проверок состояния коптеров, чтобы свести к минимуму количество неудачных запусков, а также набор параметров для настройки систем позиционирования. Все параметры хранятся в файлах конфигурации приложений клиента и сервера. Каждая система позиционирования обладает своими особенностями, которые необходимо учесть при настройке взаимодействия сервера и клиента. Ниже перечислены настройки, на которые необходимо обратить внимание при настройке клиента и сервера:

* Сервер:
  * раздел [CHECKS](server.md#раздел-checks) - проверки телеметрии коптеров на стороне сервера

* Клиент:
  * раздел [FLIGHT](client.md#раздел-flight) - имя опорной системы координат frame_id, параметры полёта
  * раздел [FLOOR FRAME](client.md#раздел-floor-frame) - позволяет создать новую систему координат с названием `floor` относительно любой существующей системы координат:
    * `map` - совпадает с начальным положением коптера при использовании optical flow или gps
    * `aruco_map` - совпадает с началом координат карты ArUco маркеров
    * `gps` - начало координат находится в заданной GPS координате с поворотом на заданный угол относительно начального положения коптера, настраивается в разделе [GPS FRAME](client.md#раздел-gps-frame) и позволяет задать систему координат с общим началом для всех коптеров
  * раздел [FAILSAFE](client.mf#раздел-failsafe) - отключен по умолчанию, но позволяет настроить условия экстренной посадки коптера:
    * при потере визуальной позиции - полезно при использовании системы позиционирования по ArUco маркерам
    * при большой разнице между текущей позицией и точкой, где должен находиться коптер - с помощью данной проверки можно избежать непредвиденного поведения коптеров при столкновениях или любых физических неполадках
  * раздел [EMERGENCY LAND](client.md#раздел-emergency-land) - задаёт настройку экстренной посадки коптера: параметр `thrust` задаёт уровень газа моторов для начала посадки, через время `decrease_thrust_after` коптер начинает в постепенно снижать уровень газа до 0. **Внимание!** Уровень газа экстренной посадки по умолчанию равен 45% - эта настройка работает для коптера Клевер 4 с 3S аккумулятором. Если ваша конфигурация отличается, нужно предварительно определить газ висения, а затем установить параметр `thrust` в значение на 5% меньше, чем газ висения. В случае, если газ экстренной посадки превышает газ висения коптера, коптер при экстренной посадке первые 3 секунды (значение `decrease_thrust_after` по умолчанию) будет лететь вверх и только после этого начнет плавно снижать мощность моторов до 0.

## Optical flow

Optical flow - способ позиционирования с помощью расчёта скоростей движения камеры по вычислению сдвига пикселей между соседними кадрами.

`Optical flow` подходит для демонстрации полёта одного коптера или же для синхронного полёта нескольких коптеров по одной и той же траектории внутри помещения. Однако следует учитывать, что данная система координат не задаёт общее начало координат для всех коптеров - началом координат является стартовое положение каждого конкретного коптера. Также стоит принять во внимание тот факт, что данный способ рассчитывает позицию коптера по скорости перемещения его камеры - а значит в позиции коптера постоянно накапливается ошибка и позиция становится менее точной со временем. Поэтому не рекомендуется использовать эту систему координат для сложных и продолжительных групповых полётов.

Образ `clever-show` для коптера настроен по умолчанию на полёт по данной системе позиционирования (как и образ `clover`) - на коптере должен быть установлер лазерный дальномер, а камера должна быть наклонена вниз шлейфом назад.

ROS пакет clover, настроенный по умолчанию предполагает автономный полёт с использованием `optical flow`. Параметры, загружаемые по умолчанию при загрузке прошивки, адаптированной для Клевер 4, предполагают позиционирование по `optical flow`. Файлы конфигураций клиента и сервера, настроенные по умолчанию, также не требуют измений для полёта по данной системе позиционирования.

Однако, если вам требуется перейти на систему позиционирования `optical flow` с другой предварительно настроенной системы или же изменить настройки данной системы, вам поможет информация, расположенная ниже.

Все файлы настроек для конфигурации `optical flow` находятся в папке [examples/positioning/optical flow](../../examples/positioning/optical%20flow/).

### Настройка ROS пакета clover

Настройка позиционирования по `optical flow` описана в [документации](https://clover.coex.tech/ru/optical_flow.html) `clover`.

Пример `.launch` файла для настройки: [clover.launch](../../examples/positioning/optical%20flow/launch/clover.launch).

### Настройка полётного контроллера

Параметры, настраивающие полётный контроллер на возможность полёта по `optical flow`: [optical_flow.params](../../examples/positioning/optical%20flow/optical_flow.params).

Для загрузки параметров на выделенные в таблице коптеры воспользуйтесь командой `Selected drones -> Send -> FCU parameters file` из верхнего меню и укажите путь к файлу с параметрами полётного контроллера.

### Настройка клиента

#### Вариант 1. Загрузка значимых параметров из примера конфигурации

Конфигурация клиента со значениями, применимыми для работы с `optical flow`: [client.ini](../../examples/positioning/optical%20flow/client.ini).

Для загрузки воспользуйтесь командой `Selected drones -> Send -> Configuration` из верхнего меню сервера. В открывшемся диалоговом окне выберите вариант `Modify` и укажите путь к файлу `client.ini`.

#### Вариант 2. Сброс всех настроек клиента

Для того, чтобы настроить конфигурацию клиента для позиционирования по optical flow, можно сбросить данные конфигурации в значения по умолчанию. Для этого нужно удалить сгенерированные файлы конфигураций на клиентах:

* Выделите в таблице коптер или коптеры, конфигурацию которых хотите сбросить.
* Выполните команду удаления конфигурации на выделенных коптерах, выбрав пункт `Selected drones -> Send -> Command`. В открывшемся диалоговом окне введите команду `rm config/client.ini` и нажмите `OK`.

### Настройка сервера

#### Вариант 1. Загрузка значимых параметров из примера конфигурации

Конфигурация сервера со значениями, применимыми для работы с `optical flow`: [server.ini](../../examples/positioning/optical%20flow/server.ini).

Для установки параметров вручную воспользуйтесь командой `Server -> Edit config` из верхнего меню сервера.

#### Вариант 2. Сброс всех настроек сервера

Для того, чтобы настроить конфигурацию сервера для позиционирования по optical flow, можно сбросить данные конфигурации в значения по умолчанию. Для этого нужно удалить сгенерированный файл конфигурации на сервере:

* Выполните команду `rm config/server.ini` из директории с расположением приложения `server.py`.
* Перезагрузите сервер, выбрав команду `Server -> Restart server` из верхнего пункта меню.

## Aruco

ArUco-маркеры — это популярная технология для позиционирования робототехнических систем с использованием компьютерного зрения. Позиционирование происходит с помощью получения информации о расположении специальных визуальных маркеров.

Данная система позиционирования вариативна: маркеры могут располагаться на полу, на потолке или на стенах. Главное условие для позиционирования - правильно внести координаты в специальную карту маркеров и обозначить её наклон относительно пола.

Если карта маркеров расположена на полу, появляются нюансы: сразу после включения коптер не знает своего положения до тех пор, пока камера не увидит карту меток. Соответственно некоторые проверки по позиции коптера и безопасности полёта становятся не применимы:

* Не имеет смысла проверка текущего положения коптера, т.к. сразу после загрузки оно не определено, но коптер при этом всё равно имеет механизм взлёта
* Не имеет смысла проверять максимальное расстояние стартовой точки анимации от текущей позиции коптера, т.к. она никогда не будет совпадать при старте
* Стартовое действие анимации `fly` в системе координат `aruco_map` будет иметь непредсказуемые последствия, т.к. на старте реальная позиция коптера будет сильно отличаться от позиции, рассчитанной полётным контроллером. Соответственно единственный вариант параметра `start_action` в разделе [ANIMATION] - это `takeoff`: подъём на высоту, определённую параметром `takeoff_height` из раздела [FLIGHT], относительно текущей позиции коптера.

### Настройка ROS пакета clover

Настройка системы позиционирования по ArUco маркерам описана в [документации](https://clover.coex.tech/ru/aruco_map.html) `clover`.

Пример `.launch` файлов для настройки карты меток на полу:

* [clover.launch](../../examples/positioning/aruco%20floor/launch/clover.launch)
* [aruco.launch](../../examples/positioning/aruco%20floor/launch/aruco.launch)

### Настройка полётного контроллера

Параметры, настраивающие полётный контроллер на возможность полёта по `ArUco`: [aruco.params](../../examples/positioning/aruco%20floor/aruco.params).

Для загрузки параметров на выделенные в таблице коптеры воспользуйтесь командой `Selected drones -> Send -> FCU parameters file` из верхнего меню и укажите путь к файлу с параметрами полётного контроллера.

### Настройка клиента

Конфигурация клиента со значениями, применимыми для работы с `Aruco`: [client.ini](../../examples/positioning/aruco%20floor/client.ini).

Для загрузки воспользуйтесь командой `Selected drones -> Send -> Configuration` из верхнего меню сервера. В открывшемся диалоговом окне выберите вариант `Modify` и укажите путь к файлу `client.ini`.

### Настройка сервера

Конфигурация сервера со значениями, применимыми для работы с `ArUco`: [server.ini](../../examples/positioning/aruco%20floor/server.ini).

Для установки параметров вручную воспользуйтесь командой `Server -> Edit config` из верхнего меню сервера.

## GPS

Позиционирование по спутниковым координатам - предпочтительный способ позиционирования для уличных полётов. Для позиционирования по GPS необходим [один из официально поддерживаемых модулей для PX4](https://docs.px4.io/v1.9.0/en/gps_compass/). Точность позиционирования по GPS составляет порядка одного метра. Использование наземной станции поправок [GPS RTK](https://docs.px4.io/v1.9.0/en/gps_compass/rtk_gps.html) и специальных GPS RTK модулей позволяет добиться дециметровой точности позиционирования.

### Настройка ROS пакета clover

Настройка позиционирования по `GPS` описана в [документации](https://clover.coex.tech/ru/gps.html) `clover`.

Пример `.launch` файла для настройки: [clover.launch](../../examples/positioning/gps/launch/clover.launch).

### Настройка полётного контроллера

Параметры, настраивающие полётный контроллер на возможность полёта по `gps`: [gps.params](../../examples/positioning/gps/gps.params).

Для загрузки параметров на выделенные в таблице коптеры воспользуйтесь командой `Selected drones -> Send -> FCU parameters file` из верхнего меню и укажите путь к файлу с параметрами полётного контроллера.

### Настройка клиента

Внимание! Начальная точка позиционирования фрейма `gps` должна быть изменена перед загрузкой. Для примера выбрана точка тестовой полётной зоны на территории Технополиса Москва.

Конфигурация клиента со значениями, применимыми для работы с `GPS`: [client.ini](../../examples/positioning/gps/client.ini).

Для загрузки воспользуйтесь командой `Selected drones -> Send -> Configuration` из верхнего меню сервера. В открывшемся диалоговом окне выберите вариант `Modify` и укажите путь к файлу `client.ini`.

### Настройка сервера

Конфигурация сервера со значениями, применимыми для работы с `GPS`: [server.ini](../../examples/positioning/gps/server.ini).

Для установки параметров вручную воспользуйтесь командой `Server -> Edit config` из верхнего меню сервера.