From 0893eb85bc190e33139aa67ff1b1b9d8a7e3ca85 Mon Sep 17 00:00:00 2001
From: Oleg Kalachev <okalachev@gmail.com>
Date: Fri, 10 Aug 2018 01:17:48 +0300
Subject: [PATCH] docs: add some info on ROS

---
 docs/ros.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 68 insertions(+), 6 deletions(-)

diff --git a/docs/ros.md b/docs/ros.md
index 778b55a2..f18afbb5 100644
--- a/docs/ros.md
+++ b/docs/ros.md
@@ -1,15 +1,19 @@
-ROS: основные концепции
-====
+ROS
+===
 
 Основная статья: http://wiki.ros.org
 
-TODO
+ROS – это широкоиспользуемый фреймворк для создания сложных и распределенных роботехнических систем.
 
 Установка
 ---
 
 Основная статья: http://wiki.ros.org/kinetic/Installation/Ubuntu
 
+ROS уже установлен на [образе для RPi](microsd_images.md).
+
+Для использования ROS на компьютере рекомендуется использовать ОС Ubuntu Linux (либо виртуальную машину, например [Parallels Desktop Lite](https://itunes.apple.com/ru/app/parallels-desktop-lite/id1085114709?mt=12) или [VirtualBox](https://www.virtualbox.org)).
+
 Концепции
 ---
 
@@ -17,15 +21,73 @@ TODO
 
 Основная статья: http://wiki.ros.org/Nodes
 
+ROS-нода – это специальная программа (обычно написанная на Python или C++), которая взаимодействует с другими нодами посредством ROS-топиков и ROS-сервисов. Разделение сложных роботехнических систем на изолированные ноды дает определеные преимущества: понижается связанность кода, повышается переиспользуемость и надежность.
+
+Очень многие роботехнические библиотеки и драйвера выполнены именно в виде ROS-нод.
+
+Для того, чтобы превратить обычную программу в ROS-ноду, необходимо подключить к ней библиотеку `rospy` или `roscpp` и добавить инициализирующий код.
+
+Пример ROS-ноды на языке Python:
+
+```
+import rospy
+
+rospy.init_node('my_ros_node')  # имя ROS-ноды
+
+rospy.spin()  # входим в бесонечный цикл...
+```
+
 ### Топики
 
 Основная статья: http://wiki.ros.org/Topics
 
+Топик – это именованная шина данных, по которой ноды обмениваются сообщениями. Любая нода может *опубликовать* сообщение в произвольный топик, а также *подписаться* на произвольный топик.
+
+Пример публикации сообщения типа [`std_msgs/String`](http://docs.ros.org/api/std_msgs/html/msg/String.html) (строка) в топик `/foo` на языке Python:
+
+```python
+from std_msgs.msg import String
+
+# ...
+
+foo_pub = rospy.Publisher('/foo', String, queue_size=1)  # создаем Publisher'а
+foo_pub.publish(data='Hello, world!')
+```
+
+Пример подписки на топик `/foo`:
+
+```python
+
+def foo_callback(msg):
+    print msg.data
+
+rospy.Subscriber('/foo', String, foo_callback)  # при получении сообщения в топик /foo вызывется функция foo_callback
+```
+
+Также, существует возможность работы с топиками с помощью утилиты `rostopic`. Например, с помощью следующей команды можно просматривать сообщения, публикуемые в топик `/mavros/state`:
+
+```bash
+rostopic echo /mavros/state
+```
+
 ### Сервисы
 
 Основная статья: http://wiki.ros.org/Services
 
-Mavros
----
+Сервис – это некоторый аналог функции, которая может быть вызвана из одной ноды, а обработана в другой. У сервиса есть имя, аналогичное имени топика, и 2 типа сообщений: тип запроса и тип ответа.
 
-Основная статья: http://wiki.ros.org/mavros
+Пример вызова ROS-сервиса из языка Python:
+
+```python
+from clever.srv import GetTelemetry
+
+# ...
+
+# Создаем обертку над сервисом get_telemetry пакета clever с типом GetTelemetry:
+get_telemetry = rospy.ServiceProxy('get_telemetry', srv.GetTelemetry)
+
+# Вызываем сервис и получаем телеметрию квадрокоптера:
+telemetry = get_telemetry()
+```
+
+Больше примеров использования сервисов для автономных полетов квадрокоптера Клевер можно посмотреть в [документации ноды simple_offboard](simple_offboard.md).