CopterExpress/clover
1
0
Fork 0
mirror of https://github.com/CopterExpress/clover.git synced 2026-05-27 05:29:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into ros-book

Browse Source
This commit is contained in:
Oleg Kalachev
2020-08-05 13:48:06 +03:00
parent 156527641a 8b690900b9
commit a89bc82f2b
93 changed files with 4223 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/ru/SUMMARY.md
View File

@@ -47,11 +47,18 @@
* [Автозапуск ПО](autolaunch.md)
* [Использование JavaScript](javascript.md)
* [`mavros`](mavros.md)
* Симулятор
* [Общая информация](simulation.md)
* [Сборка на собственной машине](simulation_native.md)
* [Установка виртуальной машины](simulation_vm.md)
* [Использование симулятора](simulation_usage.md)
* ROS: учебник
* [Общая информация](ros.md)
* [Графические инструменты](ros_gui.md)
* [Соглашения ROS](ros_conventions.md)
* [Продвинутое использование](ros_advanced.md)
* [ROS](ros.md)
* [MAVROS](mavros.md)
* Дополнительные материалы
* [COEX Pix](coex_pix.md)
* [Гид по автономному полету](auto_setup.md)

23
docs/ru/assemble_4_2.md
View File

@@ -160,7 +160,7 @@
<img src="../assets/assembling_clever4_2/fc_connection_6.png" width=300 class="zoom border">
</div>
2. На монтажную деку установите стойки 6мм и стойки 30мм, закрепите их с помощью винт М3х8 и М3х12 соответственно.
2. На монтажную деку установите стойки 6мм и стойки 30мм, закрепите их с помощью винт М3х5 и М3х12 соответственно.
<img src="../assets/assembling_clever4_2/raspberry_1.png" width=300 class="zoom border center">
@@ -204,6 +204,10 @@
<img src="../assets/assembling_clever4_2/raspberry_11.png" width=300 class="zoom border center">
13. Подключите полетный контроллер к *Raspberry Pi* с помощью USB кабеля.
<img src="../assets/assembling_clever4_2/final_2.png" width=300 class="zoom border">
## Установка LED ленты
1. Соберите обруч для светодиодной ленты, объединив замок на концах.
@@ -252,21 +256,4 @@
<img src="../assets/assembling_clever4_2/guard_4.png" width=300 class="zoom border center">
## Подготовка к полету
1. Установите ремешок для аккумулятора и подключите полетный контроллер к *Raspberry Pi* с помощью USB кабеля.
<div class="image-group">
<img src="../assets/assembling_clever4_2/final_1.png" width=300 class="zoom border">
<img src="../assets/assembling_clever4_2/final_2.png" width=300 class="zoom border">
</div>
2. Установите пропеллеры в соответствии со [схемой направления движения моторов](#prop_rotation).
<img src="../assets/assembling_clever4_2/final_3.png" width=300 class="zoom border center">
3. Установите аккумулятор.
<img src="../assets/assembling_clever4_2/final_4.png" width=300 class="zoom border center">
> **Success** Дрон собран, далее произведите ["настройку"](setup.md).

34
docs/ru/simulation.md Normal file
View File

@@ -0,0 +1,34 @@
# Общая информация
Среда симуляции Клевера позволяет пользователям запускать и отлаживать свой код в симуляторе, используя большинство функций, доступных на реальном дроне. Симулятор использует [режим PX4 SITL](sitl.md) и тот же код, использующий ROS, что и настоящий дрон. Большинство железа также симулируется.
## Особенности
Устанавливаемая пользователем среда включает в себя:
* высококачественную модель Клевера 4;
* плагины Gazebo для железа Клевера (например, для светодиодной ленты);
* легко изменяемые файлы описания дрона в формате [`xacro`](https://wiki.ros.org/xacro);
* примеры моделей и миров;
* [`roslaunch`](https://wiki.ros.org/roslaunch) файлы для быстрого запуска и настройки.
Кроме того, предоставляется [образ виртуальной машины](simulation_vm.md), который максимально точно имитирует реальный дрон.
Особенности:
* легкий доступ к симулятору;
* установлен и настроен для работы с ROS Visual Studio Code;
* веб-сервер (Monkey) для плагинов Клевера, работающих в браузере;
* постоянно работающий сервис `roscore`;
* средства визуализации (`rviz`, `rqt`).
## Состав симулятора
Симулятор основан на следующих элементах:
* [Gazebo](http://gazebosim.org/), универсальная среда симуляции для любых типов роботов;
* [PX4](https://px4.io/), в частности, его компонент SITL (software-in-the-loop);
* [`sitl_gazebo`](https://github.com/PX4/sitl_gazebo) пакет, содержащий плагины Gazebo для PX4;
* пакеты ROS и плагины Gazebo;
<!-- TODO: Write more, add a diagram, etc -->

96
docs/ru/simulation_native.md Normal file
View File

@@ -0,0 +1,96 @@
# Сборка на собственной машине
Настройка среды для симуляции с нуля требует некоторых усилий, однако это приведет к улучшению производительности и к уменьшению вероятности появления проблем с драйверами.
Требования для сборки: установлены Ubuntu 18.04 и [ROS](ros-install.md).
## Создание рабочего пространства для симулятора
В этой статье мы будем использовать `catkin_ws` как имя рабочего пространства (вы можете поменять её). Мы создадим её в домашнем каталоге текущего пользователя (`~`).
Создайте рабочее пространство и загрузите исходный код Клевера:
```bash
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
git clone https://github.com/CopterExpress/clover
git clone https://github.com/CopterExpress/ros_led
```
Установите все зависимости, используя `rosdep`:
```bash
cd ~/catkin_ws
rosdep update
rosdep install --from-paths src --ignore-src -y
```
## Загрузка исходного кода PX4
Сборка PX4 будет осуществлена вместе с другими пакетами в нашем рабочем пространстве. Вы можете загрузить его прямо в рабочее пространство или поместить куда-нибудь и создать симлинк к `~/catkin_ws/src`. Нам также нужно будет поместить его подмодуль `sitl_gazebo` в `~/catkin_ws/src`. Для упрощения мы загрузим прошивку прямо в рабочее пространство:
```bash
cd ~/catkin_ws/src
git clone --recursive https://github.com/CopterExpress/Firmware -b v1.10.1-clever
ln -s Firmware/Tools/sitl_gazebo ./sitl_gazebo
```
## Установка зависимостей PX4
PX4 имеет свой собственный скрипт для установки зависимостей. Воспользуемся им:
```bash
cd ~/catkin_ws/src/Firmware/Tools/setup
sudo ./ubuntu.sh
```
Он установит все, что нужно для сборки PX4 и SITL.
Также вы можете пропустить установку ARM тулчейна, если вы не планируете компилировать PX4 для вашего полетного контроллера. Для этого воспользуйтесь флагом `--no-nuttx`:
```
sudo ./ubuntu.sh --no-nuttx
```
## Патчинг плагинов Gazebo
Пакет `sitl_gazebo`, содержащий плагины нужно пропатчить, из-за недавних изменений в MAVLink. Эти патчи уже применены в [образе виртуальной машины](simulation_vm.md) и хранятся в репозитории CopterExpress/VM. Запустите следующие команды для загрузки и применения патчей:
```bash
cd ~/catkin_ws/src/Firmware/Tools/sitl_gazebo
wget https://raw.githubusercontent.com/CopterExpress/clover_vm/master/assets/patches/sitl_gazebo.patch
patch -p1 < sitl_gazebo.patch
rm sitl_gazebo.patch
```
## Установка датасетов geographiclib
Для `mavros` нужны датасеты geographiclib:
```bash
cd ~
wget https://raw.githubusercontent.com/mavlink/mavros/6f5bd5a1a67c19c2e605f33de296b1b1be9d02fc/mavros/scripts/install_geographiclib_datasets.sh
chmod +x ./install_geographiclib_datasets.sh
sudo ./install_geographiclib_datasets.sh
rm ./install_geographiclib_datasets.sh
```
## Сборка симулятора
После установки всех зависимостей можно начинать сборку рабочего пространства:
```bash
cd ~/catkin_ws
catkin_make
```
> **Note** Некоторые файлы, особенно плагины Gazebo, требуют большого объема оперативной памяти для сборки. Вы можете уменьшить количество параллельных процессов; количество параллельных процессов должно быть равно объёму RAM в гигабайтах, поделенному на 2. Например, для машины с 16Гб следует указывать не более 8 процессов. Вы можете указать количество процессов, используя флаг `-j` : ```catkin_make -j8```
## Запуск симулятора
Чтобы удостовериться в том, что все было собрано корректно, попробуйте запустить симулятор:
```bash
source ~/catkin_ws/devel/setup.bash
roslaunch clover_simulation simulator.launch
```

89
docs/ru/simulation_usage.md Normal file
View File

@@ -0,0 +1,89 @@
# Использование симулятора
Среда симуляции Клевера позволяет пользователям тестировать свой код без какого-либо риска повреждения оборудования. Кроме того, в [виртуальной машине](simulation_vm.md) по умолчанию запущены дополнительные (не относящиеся к ROS) сервисы, которые присутствуют на реальном дроне, например, веб-сервер Monkey.
## Запуск симулятора
После [сборки симулятора с нуля](simulation_native.md) или [запуска виртуальной машины](simulation_vm.md), вы можете использовать `roslaunch` для запуска симулятора Gazebo:
```bash
# Не забудьте сначала активировать ваше рабочее пространство
source ~/catkin_ws/devel/setup.bash
roslaunch clover_simulation simulator.launch
```
> **Note** Кроме того, если вы используете виртуальную машину, просто дважды щелкните `Gazebo PX4` на рабочем столе.
Это запустит Gazebo сервер и клиент, бинарные файлы PX4 и ноды Клевера. Терминал, в котором была запущена команда, будет отображать отладочные сообщения от нод и PX4, а также принимать входные данные для интерпретатора команд PX4:
![Скриншот симулятора Gazebo](../assets/simulation_usage/01_running_gazebo.jpg)
Вы также можете использовать QGroundControl для настройки параметров дрона в симуляторе, планирование миссий полета (если GPS также симулируется) и управление дроном с пульта:
![Gazebo и QGC](../assets/simulation_usage/02_gazebo_qgc.jpg)
Также вы можете использовать [simplified OFFBOARD](simple_offboard.md) для управления дроном, и средства визуализации ROS, например, [rviz and rqt](rviz.md) для анализа состояния дрона:
![Gazebo и RQT](../assets/simulation_usage/03_gazebo_rqt.jpg)
## Настройка симулятора
Симулятор можно настроить, передав дополнительные аргументы команде `roslaunch` или изменив файл `~/catkin_ws/src/clover/clover_simulation/launch/simulator.launch`. Ноды, обеспечивающие [распознавание ArUco](aruco.md), [расчет optical flow](optical_flow.md) и другие сервисы могут быть настроены изменением соответствующих `.launch` файлов, как на реальном дроне.
### Изменение параметров дрона
![Открытый в VSCode simulator.launch](../assets/simulation_usage/04_vscode_config.jpg)
Вы можете включить или отключить некоторые датчики дрона, изменив параметры в файле `simulator.launch`. Например, чтобы включить GPS, установите аргумент `gps` в значение `true`:
```xml
<arg name="gps" value="true"/>
```
Обратите внимание, что это просто включит датчик, вам придется также изменить параметры PX4.
Если вы хотите добавить датчики или изменить их расположение, вам придется изменить файл описания дрона. Этот файл находится в `~/catkin_ws/src/clover/clover_description/urdf/clover/clover4.xacro`, и использует формат [xacro](http://wiki.ros.org/xacro) для сборки описания URDF.
### Изменение мира по умолчанию
Плагины Gazebo для дрона на данный момент требуют, чтобы значение параметра мира `real_time_update_rate` было равно 250, а значение `max_step_size` было равно 0.004. С другими параметрами симулятор не заработает. Используйте файл `~/catkin_ws/src/clover/clover_simulation/resources/worlds/clover.world` как шаблон.
## Повышение производительности
Симуляция с использованием Gazebo требовательна к ресурсам, и для нормальной скорости работы требуются мощный процессор и видеокарта. При этом симуляции можно запускать и на менее мощном оборудовании, жертвуя при этом скоростью работы. Ниже приведены рекомендации для компьютеров, на которых симуляция не может работать в реальном времени.
### Использование плагина `throttling_camera`
По умолчанию Gazebo не замедляет симуляцию для достижения требуемой частоты работы визуальных сенсоров. Это можно исправить с помощью плагина `throttling_camera` из пакета `clover_simulation`.
Включение этого плагина происходит путём выставления параметра `maintain_camera_rate` в значение `true` в файле `clover_description/launch/spawn_drone.launch`:
```xml
<!-- Slow simulation down to maintain camera rate -->
<arg name="maintain_camera_rate" default="true"/>
```
Этот плагин будет собирать статистику по частоте публикации изображений, и будет замедлять симуляцию до тех пор, пока частота публикации не станет соответствовать или превышать требуемую. При этом значительные замедления симуляции могут негативно сказаться на программном обеспечении, которое подключается к PX4 (например, QGroundControl). Если скорость симуляции опускается ниже, чем 0.5 от реального времени, следует воспользоваться следующей рекомендацией.
### Выставление скорости симуляции
PX4, начиная с версии 1.9, поддерживает [принудительную установку скорости симуляции](https://dev.px4.io/v1.9.0/en/simulation/#simulation_speed) с помощью переменной окружения `PX4_SIM_SPEED_FACTOR`. Выставление этой переменной подготавливает все компоненты симулятора к соответствующему ускорению/замедлению.
Значение этой переменной должно соответствовать величине Real Time Factor (скорости симуляции по отношению к реальному времени), получаемой при использовании `throttling_camera`. Величина Real Time Factor отображается в окне Gazebo на нижней панели:
![Real Time Factor](../assets/simulation_usage/05_real_time_factor.png)
В данном случае `PX4_SIM_SPEED_FACTOR` следует выставить в значение `0.42` перед запуском симулятора:
```bash
PX4_SIM_SPEED_FACTOR=0.42 roslaunch clover_simulation simulator.launch
```
> **Note** При использовании виртуальной машины удобнее добавить эту переменную в ярлык запуска Gazebo на рабочем столе. Нажмите правой кнопкой на значок Gazebo, выберите "Properties..." и добавьте `PX4_SIM_SPEED_FACTOR=0.42` в поле Command, как показано на иллюстрации:
![Gazebo PX4 launcher command](../assets/simulation_usage/06_gazebo_px4_launcher.png)
### Выделение ресурсов для виртуальной машины
Выделение нескольких процессорных ядер для виртуальной машины может значительно повысить производительность симуляции. В наших испытаниях виртуальная машина, для которой было выделено одно ядро, не позволяла работать в симуляторе: окно Gazebo не реагировало на пользовательский ввод, сообщения ROS терялись. После выделения четырёх ядер для этой же виртуальной машины симуляция стала работать со скоростью 0.25 от реального времени.
При этом не следует пытаться выделить для виртуальной машины больше ресурсов, чем доступно на основной системе.

66
docs/ru/simulation_vm.md Normal file
View File

@@ -0,0 +1,66 @@
# Установка виртуальной машины
Для работы с платформой Клевер рекомендуется иметь [установленное окружение ROS](ros.md) на своём компьютере. К сожалению, [установка ROS](ros-install.md) сопряжена с рядом трудностей: требуется использовать операционную систему Ubuntu 18.04, процесс установки длительный и требует выполнения большого количества команд в терминале.
Для облегчения процесса настройки окружения мы предлагаем использовать виртуальную машину со всем необходимым для работы с платформой Клевер. В состав виртуальной машины входят:
* операционная система Ubuntu 18.04 с легковесной графической оболочкой XFCE;
* предустановленные пакеты ROS для работы с Клевером;
* QGroundControl;
* предварительно настроенный симулятор Gazebo;
* среда разработки Visual Studio Code с плагинами для разработки на Python и C++.
Виртуальная машина может использоваться как для запуска симуляторов, так и для работы с настоящим дроном.
Скачать текущую версию виртуальной машины можно [в релизах репозитория виртуальной машины](https://github.com/CopterExpress/clover_vm/releases)
> **Warning** Виртуальную машину следует использовать только в тех случаях, когда по каким-то причинам использование Ubuntu 18.04 напрямую невозможно. Производительность всех программ, особенно тех, которые используют 3D-графику - jMAVSim, Gazebo, rviz - будет существенно ниже; кроме того, в ряде случаев будут возникать графические ошибки, приводящие к частичной или полной неработоспособности указанных программ.
## Установка виртуальной машины
Для запуска виртуальной машины разработчика требуется использовать одну из совместимых сред виртуализации: [VirtualBox](https://www.virtualbox.org/wiki/Downloads), [VMware Player](https://www.vmware.com/products/workstation-player.html), [VMware Workstation](https://www.vmware.com/products/workstation-pro.html).
> **Note** На момент написания данной статьи VirtualBox не обеспечивал достаточный уровень совместимости с виртуальной машиной. Рекомендуется по возможности использовать VMware Player или VMware Workstation; дальнейшая инструкция будет преимущественно написана для VMware Player.
Убедитесь, что поддержка аппаратной виртуализации включена в настройках BIOS/UEFI вашего компьютера. Шаги для включения аппаратной виртуализации, как правило, описаны в руководстве пользователя компьютера. Проконсультируйтесь с производителем компьютера, если включить виртуализацию не получается.
1. Импортируйте архив виртуальной машины в среду виртуализации. Для VMware Player используйте опцию **Open a Virtual Machine**:
![Open dialog with clever-devel.ova selected](../assets/simulation_setup_vm/01_import_vm.png)
> **Note** При импорте архива, скорее всего, появится окно с предупреждением о формате виртуальной машины:
![Import failure dialog](../assets/simulation_setup_vm/02_import_failure.png)
Это предупреждение можно игнорировать и нажать кнопку **Retry**.
2. Откройте окно настроек виртуальной машины и измените параметры для наилучшего соответствия основной системе:
* увеличьте объём оперативной памяти, отводимый для виртуальной машины:
![Increasing avaliable memory](../assets/simulation_setup_vm/03_max_memory.png)
* увеличьте количество доступных процессорных ядер:
![Increasing cpu cores](../assets/simulation_setup_vm/04_core_count.png)
* включите 3D-ускорение:
![Enabling 3D acceleration](../assets/simulation_setup_vm/05_3d_acceleration.png)
* включите использование USB 2.0/3.0:
![USB 3.0 controller](../assets/simulation_setup_vm/06_usb_3_0.png)
* опционально включите режим "мост" для виртуального сетевого адаптера:
![Enabling bridge networking](../assets/simulation_setup_vm/07_bridge_networking.png)
> **Note** Режим "мост" может некорректно работать с некоторыми сетевыми адаптерами. Если в режиме "мост" вы не можете подключиться к дрону, используйте USB Wi-Fi-адаптеры, "проброшенные" в виртуальную машину.
3. Запустите виртуальную машину. Возможно, при первом запуске справа появятся сообщения об отсутствии поддержки 3D-ускорения со стороны основной системы:
![No 3D support from host](../assets/simulation_setup_vm/08_no_3d_acceleration.png)
В этом случае убедитесь, что у вас установлены самые последние драйверы для видеокарты в основной системе. Если сообщения появляются при повторных запусках виртуальной машины, добавьте строку
```
mks.gl.allowBlacklistedDrivers = "TRUE"
```
в файл `clever-devel.vmx`, находящийся в папке, в которую был импортирован архив в п. 1.
4. Настройте режим моста через настройки виртуальной машины (если используется VMware Player для Windows) или с помощью утилиты `vmware-netcfg` (если используется версия для Linux-дистрибутивов):
![vmware-netcfg interface](../assets/simulation_setup_vm/09_netcfg.png)
В списке сетей выберите `vmnet0`, ниже - режим *Bridged*, в выпадающем списке *Bridged to* - название беспроводного адаптера, с помощью которого будет производиться подключение к дрону.

2
docs/ru/sitl.md
View File

@@ -1,6 +1,6 @@
# Симуляция PX4
> **Hint** Мы также предоставляем [предварительно настроенный](sitl_docker.md) симулятор, поставляемый в виде Docker-контейнера!
> **Hint** Мы также предоставляем [конфигурации для Gazebo](simulation.md) и [образ виртуальной машины](simulation_vm.md) со всем необходимым для запуска симуляции Клевера.
Основная статья: https://dev.px4.io/en/simulation/

2
docs/ru/sitl_docker.md
View File

@@ -1,5 +1,7 @@
# Docker-контейнер с преднастроенным SITL
> **Warning** Рекомендуется использовать [образ виртуальной машины](simulation_vm.md) или [нативную установку](simulation_native.md) для работы в симуляторе.
![SITL demo](../assets/sitl_docker_demo.png)
Для упрощения запуска симулятора предлагается использовать предварительно настроенный [Docker-контейнер](https://hub.docker.com/r/sfalexrog/clever-sitl) с симулятором [Gazebo](http://gazebosim.org/), автопилотом [PX4](https://px4.io/) и предустановленными пакетами Клевера.