image: don’t install espeak to reduce size

* docs: add COEX Duocam docs

* Orthography and punctuation

* docs: change gitup_seek image resolution and extension

* docs: add missing duocam-mavlink article

* docs: fix linter problems in duocam-mavlink article

* docs: add a link to doucam-mavlink in SUMMARY

* Decrease the size of gitup_seek image

* Make duocam_mavlink a subsection of duocam section

* Edit duocam articles

Co-authored-by: Oleg Kalachev <okalachev@gmail.com>

.travis.yml

@@ -10,7 +10,7 @@ env:
     - IMAGE_VERSION=${TRAVIS_TAG:-${TRAVIS_COMMIT:0:7}}
     - IMAGE_NAME="$(basename -s '.git' ${TARGET_REPO})_${IMAGE_VERSION}.img"
 git:
-  depth: 25
+  depth: 1
 jobs:
   fast_finish: true
   include:

builder/image-software.sh

@@ -110,7 +110,6 @@ libffi-dev \
 monkey \
 pigpio python-pigpio python3-pigpio \
 i2c-tools \
-espeak espeak-data python-espeak \
 ntpdate \
 python-dev \
 python3-dev \

builder/test/tests.py

@@ -25,7 +25,7 @@ import pymavlink
 from pymavlink import mavutil
 import rpi_ws281x
 import pigpio
-from espeak import espeak
+# from espeak import espeak
 from pyzbar import pyzbar
 
 print cv2.getBuildInformation()

builder/test/tests.sh

@@ -32,7 +32,7 @@ monkey --version
 pigpiod -v
 i2cdetect -V
 butterfly -h
-espeak --version
+# espeak --version
 mjpg_streamer --version
 
 # ros stuff

docs/en/calibration.md

@@ -2,7 +2,7 @@
 
 In order to perform the sensor calibration, select the *Vehicle Setup* tab and choose the *Sensors* menu.
 
-> **Caution** If you use the flight controller *COEX Pix*, all *Autopilot Orientation* columns must specify `ROTATION_ROLL_180_YAW_90`, otherwise the flight controller will not correctly perceive the tilt and rotation of the copter.
+> **Caution** If you use the flight controller [*COEX Pix*](coex_pix.md), all *Autopilot Orientation* columns must specify `ROTATION_ROLL_180_YAW_90`, otherwise the flight controller will not correctly perceive the tilt and rotation of the copter.
 
 ## Compass
 

docs/en/power.md

@@ -15,7 +15,7 @@ If there is no voltage indicator or manual calibration is not possible, set the
     * Put the battery voltage into the prompt and click *Calculate*.
     * Press *Close* to save the calculated value.
 
-<img src="../assets/qgc-battery.png" class="zoom">
+<img src="../assets/qgc-voltage-divider.png" class="zoom">
 
 Further reading: https://docs.qgroundcontrol.com/en/SetupView/Power.html.
 
@@ -28,7 +28,7 @@ Further reading: https://docs.qgroundcontrol.com/en/SetupView/Power.html.
 3. Connect the battery when prompted.
 4. Wait for the *Calibration complete*.
 
-<img src="../assets/qgc-esc.png" class="zoom">
+<img src="../assets/qgc-power.png" class="zoom">
 
 Further reading: https://docs.px4.io/v1.9.0/en/advanced_config/esc_calibration.html.
 

docs/en/setup.md

@@ -68,12 +68,12 @@ This is how the main QGroundControl settings window will look like:
 
 ### Selecting the airframe
 
-<img src="../assets/qgc-frame-apply.png" alt="QGroundControl frame selection" class="zoom">
+<img src="../assets/qgc-frame-apply-clover4.png" alt="QGroundControl frame selection" class="zoom">
 
 1. Open the *Vehicle Setup* tab.
 2. Select the *Airframe* menu.
 3. Select the *Quadrotor X* airframe type.
-4. Select the *Generic Quadrotor X* from the dropdown menu.
+4. For Clover 4 select *COEX Clover 4* from the dropdown menu. Otherwise select *Generic Quadrotor X*.
 5. Return to the top of the list and press *Apply and Restart* button, confirm by pressing *Apply*.
 6. Wait for the settings to be applied and for the flight controller to restart.
 
@@ -87,6 +87,8 @@ Press the *Save* button to save the changed value to the flight controller. Chan
 
 #### Configuring PID regulators
 
+> **Info** Selecting *COEX Clover 4* frame subtype doesn't require setting PID coefficients.
+
 ##### Averaged PID coefficients for the Clover 4 drone
 
 * `MC_PITCHRATE_P` = 0.087

docs/ru/SUMMARY.md

@@ -91,6 +91,8 @@
   * [Светодиодная лента (legacy)](leds_old.md)
   * [Вклад в Клевер](contributing.md)
   * [Переход на версию 0.20](migrate20.md)
+  * [COEX Duocam](duocam.md)
+    * [Виртуальная MAVLink-камера](duocam_mavlink.md)
 * [Мероприятия](events.md)
   * [CopterHack-2021](copterhack2021.md)
   * [CopterHack-2019](copterhack2019.md)

docs/ru/calibration.md

@@ -2,7 +2,7 @@
 
 Чтобы откалибровать датчики зайдите во вкладку *Vehicle Setup* и выберите меню *Sensors*.
 
-> **Caution** Если вы используете полетный контроллер *COEX Pix*, во всех графах *Autopilot Orientation* необходимо указать значение `ROTATION_ROLL_180_YAW_90`, иначе полетный контроллер будет не корректно воспринимать наклоны и повороты коптера.
+> **Caution** Если вы используете полетный контроллер [*COEX Pix*](coex_pix.md), во всех графах *Autopilot Orientation* необходимо указать значение `ROTATION_ROLL_180_YAW_90`, иначе полетный контроллер будет не корректно воспринимать наклоны и повороты коптера.
 
 ## Компас
 

docs/ru/duocam.md

@@ -0,0 +1,197 @@
+# COEX DuoCam
+
+"COEX DuoCam" – это программно-аппаратный комплекс, позволяющий получать комбинированное визуально-тепловизионное изображение.
+
+<img src="../assets/duocam/gitup_seek.jpg" width=400 class="center" alt="duocam">
+
+В качестве источника визуальной картинки теоретически можно использовать любую камеру, имеющую CSI или HDMI-выход.
+
+В качестве источника тепловизионной картинки можно использовать тепловизоры Seek Compact или Seek Compact Pro.
+
+В качестве платформы для запуска обрабатывающего софта рекомендуется использовать одноплатный компьютер Raspberry Pi 4B.
+
+## Подключение устройств
+
+Тепловизор подключается в один из портов USB 3.0 на RPi4. Во второй USB 3.0-порт подключается Wi-Fi адаптер для осуществления связи с наземной станцией.
+
+Визуальная камера подключается в CSI порт напрямую или через HDMI-CSI-конвертер.
+
+В порт USB 2.0 следует подключить USB-flash устройство, на которое будет производиться сохранение фото и видеофайлов.
+
+## Принцип работы
+
+Программная часть осуществляет наложение тепловизионной картинки на визуальную. С помощью конфигурационного файла или виджета управления свойствами камеры в QGroundControl можно изменять результирующее изображение.
+
+### Выбор модели тепловизора
+
+Первоначально надо определиться, какая у вас модель тепловизора (простая или Pro) и выставить соответствующую настройку в конфиг-файле (`enable: yes` у seek_thermal_pro или seek_thermal в разделе thermal_camera_models. Важно не забыть выставить `enable: no` у камеры, которую не предполагается использовать).
+
+### Управление наложением
+
+При включенном визуальном (`show_visual: yes`) и термическом (`show_thermal: yes`) изображениях, термическое будет налагаться на визуальное в регион, заданный в свойстве `overlay_thermal_on_visual` (начальная точка с координатами `(x_start, y_start)`, ширина региона - `thermal_region_width`, высота - `thermal_region_height`).
+
+Если отключить визуальное изображение (`show_visual: no`), то термическое развернется на весь экран.
+
+Если отключить термическое (`show_thermal: no`), то будет транслироваться только визуальное.
+
+Если отключить оба – изображение перестанет транслироваться.
+
+### Центровка
+
+Для центровки результирующего изображения (из-за физического сдвига объективов камер термическое будет сдвинутого относительно центра визуального) следует использовать свойства раздела `final_frame_cropping`. Принцип аналогичен предыдущему разделу.
+
+### Детекторы контуров (edge detectors)
+
+Для облегчения понимания термического изображения, есть возможность включения наложения на него соответствующих контуров визуального изображения. В программе реализована поддержка двух алгоритмов детектирования контуров: [Sobel](https://docs.opencv.org/3.4/d2/d2c/tutorial_sobel_derivatives.html) и [Canny](https://docs.opencv.org/3.4/da/d5c/tutorial_canny_detector.html). В соответствующих разделах конфига (`apply_sobel` и `apply_canny`) можно поэкспериментировать с некоторыми свойствами детекторов.
+
+### Колоризация
+
+Для большей наглядности, тепловизионное изображение можно колорифицировать. Для этого необходимо выставить свойство `apply_colormap: yes`.
+
+Конкретную схему колорификации можно выбрать из [списка](https://docs.opencv.org/2.4/modules/contrib/doc/facerec/colormaps.html), указав порядковый номер схемы в свойстве `colormap`.
+
+### Свойства транслируемого видео и сохраняемых файлов
+
+Свойства транслируемого видео можно изменять в разделе `output_video`. Делать это стоит с четким пониманием того, что делаешь - неправильные настройки могут сломать трансляцию. Например, разрешение видео должно совпадать с настройками gstreamer'а, который осуществляет последующее кодирование.
+
+Для настройки сохраняемого на флеш-накопитель видео следует пользоваться группой свойств `encode_video`.
+
+Каталоги для сохранения фото и видеофайлов можно указать в свойствах `path_to_save`.
+
+### Настройки дополнительной отображаемой информации
+
+Скрывать\показывать частоту кадров в секунду визуального и термического изображений можно при помощи свойства `show_fps`.
+
+Показывать\скрывать перекрестие с температурой центрального пикселя можно при помощи свойства `draw_temp`.
+
+### Подстройка температуры
+
+В зависимости от используемого тепловизора, может потребоваться корректировка температурного диапазона. В секции `temperature_calibration` Доступны две настройки:
+
+* Сдвиг (`offset`) - линейный сдвиг температурного диапазон на указанное число.
+* Масштаб (`scale`) - пропорциональное изменение шкалы.
+
+### Выравнивание градиента температуры от центра к краям
+
+Если на тепловизионном изображении наблюдается "рамка", вызванная увеличением определяемой температуры к краям, то следует применить выравнивающий фильтр (виньетирование). Настройки располагаются в секции `vignette`:
+
+* `enable` - включить-выключить наложение фильтра.
+* `show_center` - показать точку "центра" для отладки ее положения.
+* `center_x` - X-координата "центра".
+* `center_y` - Y-координата "центра".
+* `max_decrement_relative` - максимальное уменьшение температуры к краям.
+
+## Виджет управления камерой для QGroundControl
+
+![QGC_widget](../assets/duocam/qgc_duocam_widget.png)
+
+### Где взять
+
+QGC c необходимый функционалом для управления "COEX DuoCam" можно скачать в нашем [репозитории](https://github.com/CopterExpress/qgroundcontrol/releases). Скачивать следует тот релиз, в названии которого присутствует слово `duocam` с максимальным порядковым номером.
+
+### Как использовать
+
+При открытии виджета QGC пошлет MAVLink-сообщения с запросом текущих значений свойств. Необходимо дождаться, пока они все до конца загрузятся. Если загрузка не завершается в течение минуты, необходимо нажать кнопку "Refresh values".
+
+При изменении значений свойств QGC осуществляет коммуникацию с DuoCam посредством протокола MAVLink, поэтому нет смысла очень часто нажимать контролы - наоборот, после нажатия следует дождаться изменения картинки и только потом переходить к следующему свойству.
+
+[Подробнее об архитектуре DuoCam и программе `duocam-mavlink`](duocam_mavlink.md).
+
+## Конфигурационный файл
+
+Для более глубокой настройки DuoCam можно использовать конфигурационный файл.
+
+### Как добраться
+
+Для редактирования конфигурационного файла необходимо извлечь microSD-карту из RPi4, вставить в кард-ридер своего компьютера (от операционной системы требуется возможность читать файловую систему ext4), открыть файл по адресу `<microSD>/etc/duocam/camera.yaml`.
+
+Также можно зайти по SSH на работающую RPi4 и отредактировать конфигурационный файл внутри системы по тому же пути.
+
+### Образец конфигурационного файла
+
+```yaml
+show_visual: yes
+show_thermal: yes
+flip_thermal: no
+apply_sobel:
+  enable: yes
+  sobel_scale: 3
+  sobel_delta: 0
+apply_canny: no
+draw_temp: yes
+
+output_video:
+  device: /dev/video1
+  width: 1280
+  height: 720
+  bytes_per_pixel: 3
+  framerate: 20
+
+path_to_save_photos: /media/usb0/
+path_to_save_videos: /media/usb0/
+
+encode_video:
+  width: 720
+  height: 480
+  framerate: 10
+
+thermal_camera_models:
+  seek_thermal_pro:
+    enable: no
+    sensor_resolution:
+      width: 320
+      height: 240
+    overlay_thermal_on_visual:
+      # These values are for GitUp3
+      x_start: 282
+      y_start: 102
+      thermal_region_width: 600
+      thermal_region_height: 400
+      transparency: 0.3
+      # These values are for Raspicam
+      #  x_start: 425
+      #  y_start: 155
+      #  thermal_region_width: 900
+      #  thermal_region_height: 600
+    final_frame_cropping:
+      enable: yes
+      x_start: 0
+      y_start: 0
+      width: 1160
+      height: 610
+
+  seek_thermal:
+    enable: yes
+    sensor_resolution:
+      width: 206
+      height: 156
+    overlay_thermal_on_visual:
+      x_start: 282
+      y_start: 102
+      thermal_region_width: 600
+      thermal_region_height: 400
+      transparency: 0.3
+    final_frame_cropping:
+      enable: yes
+      x_start: 0
+      y_start: 0
+      width: 1160
+      height: 610
+
+# Colormaps are taken from: https://docs.opencv.org/2.4/modules/contrib/doc/facerec/colormaps.html
+# COLORMAP_AUTUMN = 0,
+# COLORMAP_BONE = 1,
+# COLORMAP_JET = 2,
+# COLORMAP_WINTER = 3,
+# COLORMAP_RAINBOW = 4,
+# COLORMAP_OCEAN = 5,
+# COLORMAP_SUMMER = 6,
+# COLORMAP_SPRING = 7,
+# COLORMAP_COOL = 8,
+# COLORMAP_HSV = 9,
+# COLORMAP_PINK = 10,
+# COLORMAP_HOT = 11
+apply_colormap:
+  enable: yes
+  colormap: 4
+```

docs/ru/duocam_mavlink.md

@@ -0,0 +1,104 @@
+# Виртуальная MAVLink-камера COEX DuoCam
+
+Полётные контроллеры поддерживают разные способы взаимодействия с внешними камерами, включая протокол MAVLink. Обычно коммуникация с помощью данного протокола требует использования UART-порта на полётном контроллере, но есть возможность работать с камерой в основном потоке MAVLink-телеметрии с БПЛА.
+
+Утилита `duocam-mavlink` отвечает за работу виртуальной MAVLink-камеры и встраивается в общую телеметрию между полётным контроллером и QGroundControl.
+
+![Блок-схема COEX DuoCam](../assets/duocam/duocam.png)
+
+На блок-схеме прямыми линиями обозначены взаимодействия между блоками, пунктирными линиями уточняется характер взаимодействия.
+
+> **Warning** Протокол взаимодействия находится в процессе модификации. В новых версиях планируется избавиться от прямой отправки значений параметров и их количества от `duocam-mavlink` к QGroundControl.
+
+`duocam-camera` и `duocam-mavlink` обмениваются данными с помощью очередей POSIX. Имена очередей и формат сообщений доступен в репозитории [duocam-common](https://github.com/CopterExpress/duocam-common).
+
+Для объединения блоков, взаимодействующих через MAVLink, можно использовать любой MAVLink-коммутатор/маршрутизатор, который либо позволяет отключить таблицу коммутации, либо заполняет её по схеме *MAVLink ID:Component ID* (например, `cmavnode`, `mavlink-fast-switch`, `mavlink-switch`).
+
+> **Warning** При использовании `mavlink-fast-switch` требуется использовать `mavlink-serial-bridge`, либо любой другой мост для передачи MAVLink из последовательного порта в UDP, так как `mavlink-fast-switch` работает только с UDP.
+
+## Конфигурационный файл
+
+Для редактирования конфигурационного файла необходимо извлечь microSD-карту из RPi4, вставить в кард-ридер своего компьютера (от операционной системы требуется возможность читать файловую систему ext4), открыть файл по адресу `<microSD>/etc/duocam/mavlink.yaml`.
+
+Также можно зайти по SSH на работающую RPi4 и отредактировать конфигурационный файл внутри системы по тому же пути.
+
+Для корректной работы `duocam-mavlink` требуется *MAVLink ID* полётного контроллера (параметр `vehicle_id`) и `MAVLink ID` QGroundControl (параметр `qgc_vehicle_id`). `duocam-mavlink` ожидает телеметрию на UDP (параметры `ip` и `port`) и отправляет сообщения HEARTBEAT с частотой, согласно параметру `heartbeat_frequency`, представляясь, как компонент полётного контроллера `MAV_COMP_ID_CAMERA`.
+
+Максимальная задержка от `duocam-camera` задаётся параметром `command_timeout`.
+
+Если система DuoCam используется для полётов внутри помещений, то должен быть включен параметр `no_gps`.
+
+## Пример конфигурационного файла
+
+```yaml
+# MAVLink vehicle ID that owns the camera
+vehicle_id: 1
+# Enable this flag for indoor use
+no_gps: False
+# QGC vehicle ID
+qgc_vehicle_id: 255
+mavlink:
+  # IP address of the interface to listen port on (0.0.0.0 for all interfaces)
+  ip: 127.0.0.1
+  # UDP port
+  port: 14540
+  # Heartbeat frequency (Hz)
+  heartbeat_frequency: 1.0
+# Camera driver command timeout (s)
+command_timeout: 3.0
+```
+
+## Пример конфигурационного файла для `mavlink-fast-switch`
+
+```yaml
+# MAVLink endpoints
+endpoints:
+  # UAV endpoint
+  - name: "uav"
+    local:
+      port: 14588
+  # DuoCam MAVLink endpoint
+  - name: "duocam-mavlink"
+    remote:
+      ip: "127.0.0.1"
+      port: 14540
+  # GCS endpoint
+  - name: "gcs"
+    remote:
+      ip: "127.0.0.1"
+      port: 14550
+# Enable MAVLink ID table
+# HINT: Can't use this feature with duocam
+id-table: False
+```
+
+## Пример конфигурационного файла для `mavlink-serial-bridge`
+
+```yaml
+# Serial device settings
+serial:
+  # Device file
+  device: "/dev/ttyS0"
+  # Baudrate
+  baudrate: 57600
+  # Flow control (hardware, none)
+  flow: none
+  # Software serial TX buffer (bytes) (2048 by default)
+  tx-buffer: 2048
+# UDP port settings
+udp:
+  # Remote host settings (optional, listening mode if not presented)
+  remote:
+    ip: 127.0.0.1
+    port: 14588
+    # Lock remote host on the initial value (optional, False by default)
+    lock: True
+    # Broadcast mode (optional, False by default)
+    broadcast: False
+  # Local settings (optional, all interfaces and a random port by default)
+  local:
+    # Local IP address (0.0.0.0 to listen on all interfaces) (optional, all interfaces by default)
+    ip: 127.0.0.1
+    # Local UDP port (0 to select a random free port) (optional, 0 by default)
+    port: 0
+```

docs/ru/power.md

@@ -15,7 +15,7 @@
    * Введите в открывшемся поле суммарное значение напряжения с индикатора напряжения.
    * Нажмите *Close*, чтобы сохранить рассчитанное значение.
 
-<img src="../assets/qgc-battery.png" class="zoom">
+<img src="../assets/qgc-voltage-divider.png" class="zoom">
 
 Дополнительная информация: https://docs.qgroundcontrol.com/en/SetupView/Power.html.
 
@@ -28,7 +28,7 @@
 3. После появлении надписи *Connect the battery now* подсоедините АКБ.
 4. Дождитесь появления надписи *Calibration complete*.
 
-<img src="../assets/qgc-esc.png" class="zoom">
+<img src="../assets/qgc-power.png" class="zoom">
 
 Дополнительная информация: https://docs.px4.io/v1.9.0/en/advanced_config/esc_calibration.html.
 

docs/ru/setup.md

@@ -68,12 +68,12 @@
 
 ### Выбор рамы
 
-<img src="../assets/qgc-frame-apply.png" alt="QGroundControl frame selection" class="zoom">
+<img src="../assets/qgc-frame-apply-clover4.png" alt="QGroundControl frame selection" class="zoom">
 
 1. Зайдите во вкладку *Vehicle Setup*.
 2. Выберите меню *Airframe*.
 3. Выберите тип рамы *Quadrotor X*.
-4. Выберите подтип рамы *Generic Quadrotor X*.
+4. Для Клевера 4 выберите подтипа рамы *COEX Clover 4*. В ином случае – *Generic Quadrotor X*.
 5. Переместитесь в начало списка и нажмите кнопку *Apply and Restart*, подтвердите нажатием *Apply*.
 6. Дождитесь применения настроек и перезагрузки полетного контроллера.
 
@@ -87,6 +87,8 @@
 
 #### Настройка PID-регуляторов
 
+> **Info** Использование типа рамы *COEX Clover 4* не требует ввода коэффициентов PID.
+
 ##### Усредненные коэффициенты PID для Клевера 4
 
 * `MC_PITCHRATE_P` = 0.087