docs: add programming intro and re-arrange articles in programming section

docs/ru/SUMMARY.md

@@ -24,17 +24,16 @@
   * [Автоматическая проверка](selfcheck.md)
   * [Просмотр видеострима с камер](web_video_server.md)
 * Программирование
-  * [ROS](ros.md)
-  * [MAVROS](mavros.md)
+  * [Общая информация](programming.md)
   * [Ориентация камеры](camera_frame.md)
-  * [Системы координат](frames.md)
-  * [Автономный полет в OFFBOARD](simple_offboard.md)
-  * [Примеры кода](snippets.md)
   * Визуальные маркеры (ArUco)
     * [Общая информация](aruco.md)
     * [Распознавание маркеров](aruco_marker.md)
     * [Навигация по карте маркеров](aruco_map.md)
   * [Навигация по Optical Flow](optical_flow.md)
+  * [Автономный полет в OFFBOARD](simple_offboard.md)
+  * [Системы координат](frames.md)
+  * [Примеры кода](snippets.md)
   * [Лазерный дальномер](laser.md)
   * [Светодиодная лента](leds.md)
   * [Работа с GPIO](gpio.md)
@@ -42,6 +41,8 @@
   * [Компьютерное зрение](camera.md)
   * [Визуализация с помощью rviz](rviz.md)
   * [Автозапуск ПО](autolaunch.md)
+  * [ROS](ros.md)
+  * [MAVROS](mavros.md)
 * Дополнительные материалы
   * [COEX Pix](coex_pix.md)
   * [Гид по автономному полету](auto_setup.md)

docs/ru/programming.md

@@ -0,0 +1,96 @@
+# Программирование
+
+<img src="../assets/programming.png" width=250 align=right>
+
+Платформа Клевера позволяет использовать [Raspberry Pi](raspberry.md) для того, чтобы запрограммировать автономный полет дрона. Чаще всего программа для автономного полета пишется на языке Python. Программа может [получать телеметрию](simple_offboard.md#get_telemetry) (заряд батареи, ориентацию, расположение и т. д.) и отправлять команды: [полететь в точку](simple_offboard.md#navigate), [установить ориентацию](simple_offboard.md#set_attitude), [угловую скорость](simple_offboard.md#set_rates) и т. д.
+
+Платформа основывается на [фреймворке ROS](ros.md), который обеспечивает связь между пользовательской программой и сервисами Клевера, которые запущены в фоне в виде systemd-демона `clever`. Для связи с полетным контроллером используется пакет [MAVROS](mavros.md).
+
+Для автономного полета в PX4 используется [режим OFFBOARD](modes.md#auto). API Клевера переводит дрон в этом режим автоматически. В случае необходимости прерывания автономного полета, необходимо перевести дрон в любой другой режим, используя стик переключения режимов на пульте.
+
+## Система позиционирования {#positioning}
+
+Для того, чтобы дрон мог зависать на месте или летать между точками, необходимо использование система позиционирования. Такая система должна вычислять и сообщать дрону, где он находится. Клевер предполагает использование нескольких систем позиционирования: [optical flow](optical_flow.md) (используется [камера](camera.md) и [лазерный дальномер](laser.md)), [визуальные маркеры](aruco.md) (используется камера и маркеры, наклеенные на пол или потолок), GPS и других.
+
+### Optical flow
+
+Принцип работы optical flow основан на вычислении сдвигов между соседними кадрами с камеры и передачи этой информации в полетный контроллер для дальнейшего расчета смещения дрона относительно изначальной точки.
+
+Для настройки этой системы позиционирования обращайтесь к [соответствующей статье](optical_flow.md).
+
+### ArUco-маркеры
+
+Технология визуальных маркеров позволяет рассчитать позицию дрона относительно распознанных маркеров и передать эту информацию в полетный контроллер.
+
+Читайте [цикл статей про ArUco-маркеры](aruco.md) для получения подробностей.
+
+### GPS (уличный полет)
+
+Использование GPS позволяет также использовать для навигации глобальные координаты – широту и долготу (функция [`navigate_global`](simple_offboard.md#navigate_global)).
+
+Основная статья: [подключение GPS](gps.md).
+
+## Автономный полет {#flight}
+
+После настройки системы позиционирования становится возможным написание скриптов для автономных полетов. Для выполнения скриптов [подключитесь в Raspberry Pi по SSH](ssh.md). Для того, чтобы запустить Python-скрипт, используйте команду `python`:
+
+```bash
+python flight.py
+```
+
+Пример программы для полета (взлет, пролет вперед, посадка):
+
+```python
+# coding: utf8
+
+import rospy
+from clever import srv
+from std_srvs.srv import Trigger
+
+rospy.init_node('flight')
+
+get_telemetry = rospy.ServiceProxy('get_telemetry', srv.GetTelemetry)
+navigate = rospy.ServiceProxy('navigate', srv.Navigate)
+land = rospy.ServiceProxy('land', Trigger)
+
+# Взлет на высоту 1 м
+navigate(x=0, y=0, z=1, frame_id='body', auto_arm=True)
+
+# Ожидание 3 секунды
+rospy.sleep(3)
+
+# Пролет вперед 1 метр
+navigate(x=1, y=0, z=0, frame_id='body')
+
+# Ожидание 3 секунды
+rospy.sleep(3)
+
+# Посадка
+land()
+```
+
+> **note** Функция navigate не ожидает, пока дрон долетит до целевой точки; скрипт продолжит выполнение сразу. Для блокирующей версии смотрите пример функции [`navigate_wait`](snippets.md#block-nav).
+
+Обратите внимание, что параметр `auto_arm` установлен на `True` только у первого вызова функции `navigate`. Этот параметр армит дрон и переводит его в режим автономного полета (OFFBOARD).
+
+Параметр `frame_id` задает систему координат, относительно которой задаются целевая точка для полета дрона:
+
+* `body` связана с корпусом дрона;
+* `navigate_target` связана с предыдущей целевой точкой полета;
+* `map` связана с локальной системой координат дрона;
+* `aruco_map` связана с картой ArUco-маркеров;
+* `aruco_N` связана ArUco-маркером с ID=N.
+
+Подробности описаны в статье "[Системы координат](frames.md)".
+
+Полное описания API Клевера приведено в статье ["Автономный полет"](simple_offboard.md).
+
+## Дополнительное оборудование
+
+Платформа Клевера также имеет API для работы с периферией. Читайте соответствующие статьи для подробностей:
+
+* [работа со светодиодной лентой](led.md);
+* [лазерный дальномер](laser.md);
+* [GPIO](gpio.md);
+* [ультразвуковой дальномер](sonar.md);
+* [камера](camera.md).