docs: Add porting guide for Jetson Nano (#198)

* docs: Add porting guide for Jetson Nano (en)

* docs/jetson_nano: Add missing Jetson Nano image

* docs/jetson_nano: More explicit initial setup

* docs/jetson_nano: imx219 -> IMX219

* docs/jetson_nano: Make lack of LED strip support more clear

* docs: Add porting guide for Jetson Nano (ru)

.markdownlint.json

@@ -105,7 +105,8 @@
             "TCP",
             "UDP",
             "QR",
-            "Li-ion"
+            "Li-ion",
+            "Nvidia"
         ],
         "code_blocks": false
     },

docs/en/SUMMARY.md

@@ -51,6 +51,7 @@
   * [PID Setup](calibratePID.md)
   * [Model files for parts](models.md)
   * [ROS Melodic installation](ros-install.md)
+  * [Clever and Jetson Nano](jetson_nano.md)
   * [Remote control app](rc.md)
   * [Wi-Fi Configuration](network.md)
   * [UART settings](uart.md)

docs/en/jetson_nano.md

@@ -0,0 +1,146 @@
+# Clever and Jetson Nano
+
+## Jetson Nano overview
+
+[Jetson Nano](https://developer.nvidia.com/embedded/jetson-nano-developer-kit) is a system-on-a-module by Nvidia. It is built on a Tegra X1 platform. With four ARM Cortex-A57 cores clocked at 1.4 GHz, 4 GB of RAM and a relatively powerful GPU, it is more capable than a Raspberry Pi 3 series of single-board computers.
+
+<img src="../assets/jetson_nano/00-jetson-nano-board.jpg" class="zoom">
+
+Jetson Nano developer kits come with a carrier board that has USB 3.0, CSI and Ethernet ports, as well as a row of GPIO pins. The carrier board is only slightly larger than a Raspberry Pi computer, making it a viable option for an onboard computer.
+
+> **Note** The default carrier board does not have a Wi-Fi chip installed. You can use a USB Wi-Fi adapter or install a Wi-Fi card in the M.2 slot on the carrier board. Be sure to check your adapter for compatibility with the Jetson Nano!
+
+## Setting up
+
+Nvidia provides an SD card image with an operating system based on Ubuntu Linux 18.04 for Jetson Nano. This image is a good starting point for ROS and Clever installation.
+
+### Initial system setup
+
+> **Hint** Be sure to check the [official Getting Started instructions](https://developer.nvidia.com/embedded/learn/get-started-jetson-nano-devkit) for the Jetson Nano developer kit!
+
+For the initial setup you'll need an HDMI or DisplayPort monitor, a keyboard and a mouse. Download the [Jetson Nano developer kit image](https://developer.nvidia.com/jetson-nano-sd-card-image-r3231) and flash it on a microSD card (a 32+ GB card is strongly recommended). Plug the card into the Jetson Nano module, connect your monitor, keyboard, and mouse to the carrier board, and power up the Jetson Nano.
+
+> **Hint** Jetson Nano can be powered by a microUSB cable, but we strongly suggest using a good power supply and a barrel jack connector. You'll need to put a jumper on the J48 pins (they are right next to the CSI connector on the carrier board).
+
+Accept the Nvidia EULA and follow the installer prompts. The system will reboot after installation. Login with your username and password.
+
+> **Info** We strongly recommend to choose the English system language/locale for Jetson Nano to avoid ROS compatibility issues!
+
+If you've installed a Wi-Fi adapter, you may want to configure your Jetson Nano to connect to your Wi-Fi network automatically. Once the system is installed and booted up, click on the "wireless network" icon in the top bar, choose "Edit Connections..." in the drop-down menu, select your network name from the list and click on the gear icon at the bottom of the window.
+
+<img src="../assets/jetson_nano/01-network-config.png" class="zoom">
+
+Go to the "General" tab in the newly-opened window and check the "All users may connect to this network" checkbox. Press the "Save" button to close the window.
+
+> **Hint** You may want to make sure you're able to access your Jetson Nano over the network. The image already has SSH enabled, and it's more convenient to perform next steps using the remote shell.
+
+### Installing ROS
+
+> **Hint** Ubuntu 18.04 is officially supported as a base system for ROS Melodic. Be sure to [check the official installation instructions](http://wiki.ros.org/melodic/Installation/Ubuntu)!
+
+Add OSRF keys and repositories to your system:
+
+```bash
+sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654
+sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
+sudo apt update
+```
+
+Install base ROS packages:
+
+```bash
+sudo apt install ros-melodic-ros-base
+```
+
+Enable your ROS environment and update your `rosdep` cache:
+
+```bash
+source /opt/ros/melodic/setup.bash
+sudo rosdep init
+rosdep update
+```
+
+> **Hint** You may wish to put the `source /opt/ros/melodic/setup.bash` line at the end of your user's `.profile` file.
+
+Install pip for Python 2 (while this is not technically a part of ROS, some dependencies are only installable using pip):
+
+```bash
+sudo apt install curl
+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+sudo python ./get-pip.py
+```
+
+### Building Clever nodes
+
+Create a "workspace" directory in your home folder and populate it with Clever packages:
+
+```bash
+mkdir -p ~/catkin_ws/src
+cd ~/catkin_ws/src
+git clone https://github.com/CopterExpress/clever
+git clone https://github.com/CopterExpress/ros_led
+git clone https://github.com/okalachev/vl53l1x_ros
+```
+
+Install dependencies using `rosdep`:
+
+```bash
+cd ~/catkin_ws
+rosdep install --from-paths src --ignore-src -y
+```
+
+Install geographiclib datasets (they are required for mavros, but are not packaged with it):
+
+```bash
+curl https://raw.githubusercontent.com/mavlink/mavros/master/mavros/scripts/install_geographiclib_datasets.sh -o install_geographiclib_datasets.sh
+chmod a+x ./install_geographiclib_datasets.sh
+sudo ./install_geographiclib_datasets.sh
+```
+
+Install development libraries for OpenCV 3.2 (recent Jetson Nano images have OpenCV 4.1.1 preinstalled; using this version will result in build failures):
+
+```bash
+sudo apt install libopencv-dev=3.2.0+dfsg-4ubuntu0.1
+```
+
+Finally, build the Clever nodes:
+
+```bash
+cd ~/catkin_ws
+catkin_make
+```
+
+> **Hint** You may also want to add udev rules for PX4 flight controllers. Copy [the rules file](https://github.com/CopterExpress/clever/blob/master/clever/config/99-px4fmu.rules) to `/etc/udev/rules.d` and run `sudo udevadm control --reload-rules && sudo udevadm trigger`.
+
+### Running Clever nodes
+
+Set up the workspace environment:
+
+```bash
+cd ~/catkin_ws
+source devel/setup.bash
+```
+
+Configure the launch files to your taste and use `roslaunch` to launch the nodes:
+
+```bash
+roslaunch clever clever.launch
+```
+
+> **Hint** You may want to start the Clever nodes automatically. This can be done with `systemd`: look at service files for [`roscore`](https://github.com/CopterExpress/clever/blob/master/builder/assets/roscore.service) and [`clever`](https://github.com/CopterExpress/clever/blob/master/builder/assets/clever.service) that are used in our image and adjust them as necessary.
+
+## Caveats
+
+### CSI cameras
+
+Jetson Nano currently does not support older Raspberry Pi v1 cameras (that are based on the Omnivision OV5647 sensor). Raspberry Pi v2 cameras (the ones that use Sony IMX219) are supported, but are not available as Video4Linux devices.
+
+Fortunately, these cameras are available using GStreamer. You can try using the [`gscam`](http://wiki.ros.org/gscam) ROS package or our [`jetson_camera`](https://github.com/sfalexrog/jetson_camera) node. The latter requires you to build OpenCV 3.4 from source with GStreamer support.
+
+The GStreamer pipelines are available at [JetsonHacksNano CSI camera reposotory](https://github.com/JetsonHacksNano/CSI-Camera).
+
+You may also notice that the camera image has a red tint that is more pronounced near the edges. This can be fixed by image signal processor tuning. Generally this should be done by your camera manufacturer; [here is a sample ISP configuration](https://www.arducam.com/docs/camera-for-jetson-nano/fix-red-tint-with-isp-tuning/) from Adrucam
+
+### LED strip
+
+Jetson Nano currently does not support LED strips over GPIO.

docs/ru/SUMMARY.md

@@ -52,6 +52,7 @@
   * [CAD-модели Клевера](models.md)
   * [Docker-контейнер с симулятором](sitl_docker.md)
   * [Установка ROS Melodic](ros-install.md)
+  * [Пакеты Клевера на Jetson Nano](jetson_nano.md)
   * [Пилотирование со смартфона](rc.md)
   * [Настройка сети RPi](network.md)
   * [Интерфейс UART](uart.md)

docs/ru/jetson_nano.md

@@ -0,0 +1,146 @@
+# Пакеты Клевера на Jetson Nano
+
+## О Jetson Nano
+
+[Jetson Nano](https://developer.nvidia.com/embedded/jetson-nano-developer-kit) – система на модуле (SoM), выпускаемая компанией Nvidia. Система построена на базе платформы Tegra X1 и несёт на себе четырёхядерный процессор ARM Cortex-A57 частотой 1.4 ГГц, 4 ГБ оперативной памяти и видеоядро на базе Nvidia Maxwell.
+
+<img src="../assets/jetson_nano/00-jetson-nano-board.jpg" class="zoom">
+
+Набор для разработчиков Jetson Nano включает в себя как сам модуль, так и плату-носитель с портами USB 3.0, CSI, Ethernet и GPIO-пинами. Плата-носитель ненамного больше одноплатного компьютера Raspberry Pi и может быть использована в качестве бортового компьютера.
+
+> **Note** На плате-носителе изначально нет Wi-Fi-адаптера. Для организации беспроводного подключения к Jetson Nano следует использовать USB-адаптер или Wi-Fi карту стандарта M.2. Следует свериться со списком совместимого оборудования перед установкой адаптера.
+
+## Установка ПО
+
+Nvidia предоставляет образ системы для Jetson Nano на базе Ubuntu 18.04. Эта версия системы поддерживается как база для ROS Melodic.
+
+### Начальная установка
+
+> **Hint** Более подробные инструкции можно получить на [официальном сайте Nvidia](https://developer.nvidia.com/embedded/learn/get-started-jetson-nano-devkit) для Jetson Nano.
+
+Для начальной установки требуется использование клавиатуры, мыши и HDMI-монитора. Скачайте [образ системы Jetson Nano](https://developer.nvidia.com/jetson-nano-sd-card-image-r3231) и запишите его на карту microSD (размером не менее 16 ГБ; рекомендуется использовать карту объёмом не менее 32 ГБ). Вставьте записанную карту в модуль Jetson Nano, подключите клавиатуру, мышь и монитор к плате-носителю и подайте питание на модуль.
+
+> **Hint** Jetson Nano можно питать от кабеля microUSB, но для повышения надёжности рекомендуется использовать специальный разъём питания. При использовании этого разъёма следует поместить перемычку на пины J48 (расположены рядом с разъёмом CSI).
+
+Примите лицензионное соглашение на использование системы и следуйте дальнейшим указаниям установщика. После установки система автоматически перезагрузится и покажет экран входа в систему. Выберите созданного вами пользователя и введите пароль, указанный на этапе установки.
+
+> **Info** Настоятельно рекомендуется выбрать английский язык как системный, дабы избежать возможных проблем с ROS.
+
+Рекомендуется настроить автоматические подключение к Wi-Fi сети. Для этого после установки системы нажмите на значок Wi-Fi подключения в верхней части экрана, выберите опцию "Edit Connections..." в выпадающем меню, выделите текущую Wi-Fi сеть в открывшемся списке и нажмите на кнопку с иконкой шестерёнки.
+
+<img src="../assets/jetson_nano/01-network-config.png" class="zoom">
+
+Во вкладке "General" поставьте галочку возле пункта "All users may connect to this network". Нажмите на кнопку "Save" для применения параметров и закрытия окна.
+
+> **Hint** Убедитесь, что Jetson Nano доступен в сети. В образе по умолчанию установлен и включен SSH-сервер; для выполнения дальнейших операций рекомендуется подключиться к нему.
+
+### Установка ROS
+
+> **Hint** Ubuntu 18.04 официально поддерживается дистрибутивом ROS Melodic, и поэтому на официальном сайте [есть подробная инструкция по его установке](http://wiki.ros.org/melodic/Installation/Ubuntu).
+
+Добавьте ключи и репозитории OSRF в систему:
+
+```bash
+sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654
+sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
+sudo apt update
+```
+
+Установите базовые ROS-пакеты (стек `ros-base`):
+
+```bash
+sudo apt install ros-melodic-ros-base
+```
+
+Активируйте окружение ROS и обновите кэш утилиты `rosdep`:
+
+```bash
+source /opt/ros/melodic/setup.bash
+sudo rosdep init
+rosdep update
+```
+
+> **Hint** Добавьте строчку `source /opt/ros/melodic/setup.bash` в конец файла `.profile` в своей домашней директории, чтобы не производить активацию окружения ROS каждый раз заново.
+
+Установите пакетный менеджер pip для Python 2 (он требуется для установки некоторых зависимостей):
+
+```bash
+sudo apt install curl
+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+sudo python ./get-pip.py
+```
+
+### Сборка нод Клевера
+
+Создайте в своей домашней директории "рабочее пространство" (workspace) и добавьте туда необходимые для Клевера пакеты:
+
+```bash
+mkdir -p ~/catkin_ws/src
+cd ~/catkin_ws/src
+git clone https://github.com/CopterExpress/clever
+git clone https://github.com/CopterExpress/ros_led
+git clone https://github.com/okalachev/vl53l1x_ros
+```
+
+Установите зависимости этих пакетов с помощью утилиты `rosdep`:
+
+```bash
+cd ~/catkin_ws
+rosdep install --from-paths src --ignore-src -y
+```
+
+Для функционирования mavros потребуется также скачать географические данные. Это делается следующими командами:
+
+```bash
+curl https://raw.githubusercontent.com/mavlink/mavros/master/mavros/scripts/install_geographiclib_datasets.sh -o install_geographiclib_datasets.sh
+chmod a+x ./install_geographiclib_datasets.sh
+sudo ./install_geographiclib_datasets.sh
+```
+
+Для сборки пакетов также потребуется установить заголовочные файлы OpenCV 3.2 (по умолчанию в новых образах для Jetson Nano установлены заголовочные файлы для OpenCV 4.1.1; с ними компиляция пакетов провалится):
+
+```bash
+sudo apt install libopencv-dev=3.2.0+dfsg-4ubuntu0.1
+```
+
+Наконец, запустите сборку нод Клевера:
+
+```bash
+cd ~/catkin_ws
+catkin_make
+```
+
+> **Hint** При подключении полётных контроллеров на базе PX4 через USB следует также добавить правила udev в систему. Скопируйте [файл с правилами](https://github.com/CopterExpress/clever/blob/master/clever/config/99-px4fmu.rules) в `/etc/udev/rules.d` и выполните команду `sudo udevadm control --reload-rules && sudo udevadm trigger`.
+
+### Запуск Клеверных нод
+
+Активируйте окружение "рабочего пространства":
+
+```bash
+cd ~/catkin_ws
+source devel/setup.bash
+```
+
+Поменяйте launch-файлы так, чтобы это соответствовало вашей конфигурации, и запустите ноды с помощью `roslaunch`:
+
+```bash
+roslaunch clever clever.launch
+```
+
+> **Hint** Вы можете настроить `systemd` так, чтобы ноды Клевера запускались автоматически. Примером такой настройки может служить образ Клевера для Raspberry Pi: там созданы сервисы [`roscore`](https://github.com/CopterExpress/clever/blob/master/builder/assets/roscore.service) и [`clever`](https://github.com/CopterExpress/clever/blob/master/builder/assets/clever.service). Их можно подкорректировать и использовать в Jetson Nano.
+
+## Возможные проблемы
+
+### CSI-камеры
+
+Jetson Nano не поддерживает старые камеры для Raspberry Pi (v1, на базе сенсора Omnivision OV5647). Камеры Raspberry Pi v2 (на базе Sony IMX219) поддерживаются, но не показываются в виде Video4Linux-устройств.
+
+Изображения с этих камер можно захватывать с помощью GStreamer. Для последующей передачи этих изображений в ROS можно использовать ноды [`gscam`](http://wiki.ros.org/gscam) или [`jetson_camera`](https://github.com/sfalexrog/jetson_camera). Для запуска ноды `jetson_camera` потребуется собрать OpenCV из ветки 3.4 с поддержкой GStreamer.
+
+Примеры конвейеров GStreamer для захвата изображения доступны [в репозитории JetsonHacksNano](https://github.com/JetsonHacksNano/CSI-Camera).
+
+Изображение с камеры может становиться более красным по краям. Это можно исправить с помощью настройки процессора изображения. Эта процедура должна выполняться производителями камер; [вот пример файла настройки процессора изображения](https://www.arducam.com/docs/camera-for-jetson-nano/fix-red-tint-with-isp-tuning/) от компании Arducam.
+
+### LED-лента
+
+В данный момент Jetson Nano не поддерживает работу с LED-лентой через GPIO.