SITL: Docker-based SITL documentation

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)

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.