diff --git a/docs/assets/sitl_debug_pane.png b/docs/assets/sitl_debug_pane.png new file mode 100644 index 00000000..2c9c4a2d Binary files /dev/null and b/docs/assets/sitl_debug_pane.png differ diff --git a/docs/assets/sitl_docker_demo.png b/docs/assets/sitl_docker_demo.png new file mode 100644 index 00000000..fbcdd596 Binary files /dev/null and b/docs/assets/sitl_docker_demo.png differ diff --git a/docs/ru/SUMMARY.md b/docs/ru/SUMMARY.md index 865e2a84..5f85f158 100644 --- a/docs/ru/SUMMARY.md +++ b/docs/ru/SUMMARY.md @@ -47,6 +47,7 @@ * [Ультразвуковой дальномер](sonar.md) * [Лазерный дальномер](laser.md) * [Работа с SITL](sitl.md) + * [SITL в Docker-контейнере](sitl_docker.md) * [Автозапуск ПО](autolaunch.md) * [Взаимодействие с Arduino](arduino.md) * [3G-модем](3g.md) diff --git a/docs/ru/sitl_docker.md b/docs/ru/sitl_docker.md new file mode 100644 index 00000000..ff73b9b8 --- /dev/null +++ b/docs/ru/sitl_docker.md @@ -0,0 +1,104 @@ +# Docker-контейнер с преднастроенным SITL + +![SITL demo](../assets/sitl_docker_demo.png) + +Для упрощения запуска симулятора предлагается использовать предварительно настроенный [Docker-контейнер](https://hub.docker.com/r/sfalexrog/clever-sitl) с симулятором [Gazebo](http://gazebosim.org/), автопилотом [PX4](https://px4.io/) и предустановленными пакетами Клевера. + +## Состав контейнера + +В Docker-контейнере с симулятором установлены и настроены: + +* Симулятор Gazebo с плагинами для симуляции камеры, дальномера и связью с ROS +* Пакеты [ROS](http://www.ros.org/), требуемые для запуска нод Клевера +* Собранный для симулятора PX4 +* Легковесный web-интерфейс для Gazebo [Gzweb](http://gazebosim.org/gzweb.html) +* Web-терминал Butterfly + +## Предварительная настройка + +Запуск контейнера рекомендуется производить на ОС Ubuntu версии не ниже 16.04 с использованием Docker версии не ниже 18.09. Для комфортной работы с симулятором следует использовать компьютер с не менее чем 4 ядрами CPU (Intel Core i5/i7, не ниже Haswell) и не менее чем 8 ГБ ОЗУ. На компьютере может быть установлена графическая среда и браузер, но это не является обязательным требованием: работа с симулятором может происходить на другом компьютере в той же локальной сети. + +## Запуск симулятора + +Для запуска симулятора можно воспользоваться [вспомогательным скриптом](https://github.com/sfalexrog/clever-sitl/blob/master/run_web_server.sh), либо использовать следующую команду: + +```bash +docker run \ + -it \ + --rm \ + -p 14556:14556 \ + -p 14557:14557 \ + -p 8080:8080 \ + -p 8081:8081 \ + -p 8082:8082 \ + -p 9090:9090 \ + -p 35602:35602 \ + -p 2222:22 \ + sfalexrog/clever-sitl:latest +``` + +Данная команда запускает контейнер ```sfalexrog/clever-sitl:latest```, содержащий последнюю версию контейнера с симулятором. Ключ ```-p``` позволяет задать соответствие между портом компьютера, на котором запущен контейнер, и портом "внутри" контейнера. Порты 14556 и 14557 нужны для подключения к симулятору с помощью [QGroundControl](http://qgroundcontrol.com/), порт 8080 - для просмотра топиков ROS с изображениями и видеопотоками, порт 8081 - для подключения к визуализации симуляции Gazebo, порт 8082 - для доступа к web-терминалу Butterfly. + +После запуска контейнера можно перейти по следующим ссылкам в браузере для доступа к сервисам симулятора: + +* [http://localhost:8080](http://localhost:8080) - просмотр топиков с камеры (аналогично тому, как это сделано в Клевере) +* [http://localhost:8081](http://localhost:8081) - визуализация текущего состояния симулятора через Gzweb +* [http://localhost:8082](http://localhost:8082) - Web-терминал Butterfly с запущенным сеансом [tmux](https://github.com/tmux/tmux/wiki) + +Доступ к этим сервисам также есть с других компьютеров, расположенных в той же локальной сети; для этого в ссылках, указанных выше, следует ```localhost``` поменять на IP-адрес компьютера с запущеным контейнером. + +## Работа с симулятором + +Основное взаимодействие с симулятором происходит через Web-терминал Butterfly. По умолчанию в нём открывается сессия tmux, так что происходящее в терминале можно демонстрировать сразу на нескольких компьютерах. + +В web-терминале работают команды ROS, доступны редакторы [vim](https://www.vim.org/) и [nano](https://www.nano-editor.org/), поддерживается работа с интерпретатором [Python](https://www.python.org/). В симуляторе можно запускать программы, написанные для Клевера и не использующие специфический функционал бортового компьютера или периферии (например, LED-ленты). + +Визуализация текущего состояния симулированного мира доступна в Gzweb. Камеру можно перемещать, передвигая мышь с зажатой левой кнопкой. Поворот камеры производится при зажатой средней кнопке мыши, приближение/удаление камеры - при повороте колёсика. При выполнении этих манипуляций появляется небольшая жёлтая сфера, означающая центр поворота/приближения. + +В web-терминале также можно просмотреть текущее состояние PX4, отладочный вывод нод Клевера, лог Gazebo и Gzweb. Для этого надо переключиться на нулевой экран tmux; это делается комбинацией клавиш ```ctrl+B``` и последующим нажатием клавиши ```0```. Появится примерно следующее: + +![SITL debug pane](../assets/sitl_debug_pane.png) + +Верхняя панель - отладочная консоль PX4; на нижней панели: слева находится отладочный вывод симулятора Gazebo, справа сверху - лог нод Клевера, справа снизу - лог Gzweb. + +Для переключения между панелями следует использовать комбинацию клавиш ```ctrl+B``` и последующее нажатие кнопки ```Q``` и номера панели. Номера панелей будут кратковременно выведены поверх самих панелей при нажатии ```ctrl+B``` и ```Q```. + +## Завершение работы с симулятором + +Для завершения работы с симулятором достаточно завершить работу соответствующего контейнера. Это можно сделать с помощью инструментов управления Docker-контейнерами или нажатием комбинации клавиш ```ctrl+C``` в терминале, в котором был запущен контейнер. + +## Увеличение скорости работы симулятора + +(Данная секция нуждается в доработке) + +По умолчанию симулятор будет создавать изображения в симулируемых камерах, используя программную растеризацию. Это создаёт повышенную нагрузку на CPU компьютера с запущенным симулятором, а также не позволяет получить приемлемую частоту кадров для большинства задач компьютерного зрения. Как правило, Docker не используют для графически интенсивных задач, поэтому возможности по увеличению производительности ограничены. + +При использовании достаточно современного графического оборудования с открытыми драйверами (например, Intel HD Graphics 520+ и mesa на Linux) можно попробовать "пробросить" сеанс X Server и видеокарту в контейнер; в этом случае будет использована гораздо более быстрая аппаратная растеризация. + +Для проброса видеокарты в контейнер следует выполнить следующие команды на компьютере, на котором будет запущен контейнер: + +``` +touch /tmp/.docker.xauth + +xauth nlist $DISPLAY | sed -e 's/^..../ffff/' | xauth -f /tmp/.docker/xauth nmerge - + +docker run \ + -it \ + --rm \ + -v /tmp/.X11-unix:/tmp/.X11-unix:rw \ + -v /tmp/.docker.xauth:/tmp/.docker.xauth:rw \ + -e DISPLAY=$DISPLAY \ + -e XAUTHORITY=/tmp/.docker.xauth \ + --device /dev/dri/card0:/dev/dri/card0 \ + -p 14556:14556 \ + -p 14557:14557 \ + -p 8080:8080 \ + -p 8081:8081 \ + -p 8082:8082 \ + -p 9090:9090 \ + -p 35602:35602 \ + -p 2222:22 \ + sfalexrog/clever-sitl:latest +``` + +При этом на компьютере с контейнером должна быть запущена графическая среда, использующая X Server.