diff --git a/docs/assets/right-hand-rotate.png b/docs/assets/right-hand-rotate.png new file mode 100644 index 00000000..036f27f4 Binary files /dev/null and b/docs/assets/right-hand-rotate.png differ diff --git a/docs/assets/right-hand-rule.svg b/docs/assets/right-hand-rule.svg new file mode 100644 index 00000000..2bdcf5b9 --- /dev/null +++ b/docs/assets/right-hand-rule.svg @@ -0,0 +1,87 @@ + + + +]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/ru/SUMMARY.md b/docs/ru/SUMMARY.md index 16029a39..a5a47fc5 100644 --- a/docs/ru/SUMMARY.md +++ b/docs/ru/SUMMARY.md @@ -49,11 +49,8 @@ * [`mavros`](mavros.md) * ROS: учебник * [Общая информация](ros.md) - * [ROS-ноды](ros_node.md) - * [ROS-топики](ros_topic.md) - * [ROS-сервисы](ros_service.md) - * [ROS-параметры](ros_params.md) * [Графические инструменты](ros_gui.md) + * [Соглашения ROS](ros_conventions.md) * [Продвинутое использование](ros_advanced.md) * Дополнительные материалы * [COEX Pix](coex_pix.md) diff --git a/docs/ru/ros.md b/docs/ru/ros.md index 2704603e..32f7ab42 100644 --- a/docs/ru/ros.md +++ b/docs/ru/ros.md @@ -1,29 +1,26 @@ -ROS -=== +# Введение в ROS -Основная статья: http://wiki.ros.org +Основная документация: http://wiki.ros.org. -ROS – это широко используемый фреймворк для создания сложных и распределенных робототехнических систем. +**ROS** – это широко используемый фреймворк для создания сложных, распределенных робототехнических систем. На ROS основана [программная платформа Клевера](programming.md). -Установка ---- +## Установка -Основная статья: http://wiki.ros.org/melodic/Installation/Ubuntu +ROS уже установлен на [образе для RPi для Клевера](image.md). -ROS уже установлен на [образе для RPi](image.md). +Для использования ROS на компьютере рекомендуется ОС Ubuntu Linux (либо виртуальная машина, например [Parallels Desktop Lite](https://itunes.apple.com/ru/app/parallels-desktop-lite/id1085114709?mt=12) или [VirtualBox](https://www.virtualbox.org)). Воспользуйтесь [официальной документацией](http://wiki.ros.org/melodic/Installation/Ubuntu) для установки ROS на компьютер. -Для использования ROS на компьютере рекомендуется ОС Ubuntu Linux (либо виртуальная машина, например [Parallels Desktop Lite](https://itunes.apple.com/ru/app/parallels-desktop-lite/id1085114709?mt=12) или [VirtualBox](https://www.virtualbox.org)). +Для быстрого старта вы можете воспользоваться [образом виртуальной машины с ROS и симулятором Клевера](simulation_vm.md). > **Note** Для дистрибутива ROS Melodic рекомендуется Ubuntu версии 18.04. -Концепции ---- +## Концепции ### Ноды -Основная статья: http://wiki.ros.org/Nodes +Основная статья: http://wiki.ros.org/Nodes. -ROS-нода – это специальная программа (обычно написанная на Python или C++), которая взаимодействует с другими нодами посредством ROS-топиков и ROS-сервисов. Разделение сложных робототехнических систем на изолированные ноды дает определенные преимущества: понижается связанность кода, повышается переиспользуемость и надежность. +ROS-нода[^1] – это специальная программа (обычно написанная на Python или C++), которая взаимодействует с другими нодами посредством ROS-топиков и ROS-сервисов. Разделение сложных робототехнических систем на изолированные ноды дает определенные преимущества: понижается связанность кода, повышается переиспользуемость и надежность. Очень многие робототехнические библиотеки и драйвера выполнены именно в виде ROS-нод. @@ -39,22 +36,36 @@ rospy.init_node('my_ros_node') # имя ROS-ноды rospy.spin() # входим в бесконечный цикл... ``` +> **Info** Любая [программа для автономного полета Клевера](programming.md) является ROS-нодой. + ### Топики -Основная статья: http://wiki.ros.org/Topics +Основная статья: http://wiki.ros.org/Topics. -Топик – это именованная шина данных, по которой ноды обмениваются сообщениями. Любая нода может *опубликовать* сообщение в произвольный топик, а также *подписаться* на произвольный топик. +Топик – это именованная шина данных, по которой ноды обмениваются сообщениями. Любая нода может опубликовать сообщение в произвольный топик, а также подписаться на произвольный топик. -Пример публикации сообщения типа [`std_msgs/String`](http://docs.ros.org/api/std_msgs/html/msg/String.html) (строка) в топик `/foo` на языке Python: +Для каждого созданного топика должен быть задан тип сообщений, которые по нему передаются. ROS включает в себя большое количество стандартных типов сообщений, покрывающих различные аспекты робототехники, но при необходимости возможно создание собственных типов сообщений. Примеры стандартных типов сообщений: + +|Тип сообщения|Описание| +|-|-| +|[`std_msgs/Int64`](http://docs.ros.org/api/std_msgs/html/msg/Int64.html)|Целое число.| +|[`std_msgs/Float64`](http://docs.ros.org/api/std_msgs/html/msg/Float64.html)|Число с плавающей точкой (дробное) двойной точности.| +|[`std_msgs/String`](http://docs.ros.org/api/std_msgs/html/msg/String.html)|Строка.| +|[`geometry_msgs/PoseStamped`](http://docs.ros.org/api/geometry_msgs/html/msg/PoseStamped.html)|Позиция и ориентация объекта с заданной [системой координат](frames.md) и временной меткой (широко используется для передачи текущей позиции робота и его частей).| +|[`geometry_msgs/TwistStamped`](http://docs.ros.org/api/geometry_msgs/html/msg/TwistStamped.html)|Линейная и угловая скорость объекта с заданной системой координат и временной меткой.| +|[`sensor_msgs/Image`](http://docs.ros.org/api/sensor_msgs/html/msg/Image.html)|Изображение (см. [статью о работе с камерой](camera.md))| + +> **Info** Смотрите остальные стандартные типы сообщений в пакетах [`common_msgs`](http://wiki.ros.org/common_msgs), [`std_msgs`](http://wiki.ros.org/std_msgs), [`geometry_msgs`](http://wiki.ros.org/geometry_msgs), [`sensor_msgs`](http://wiki.ros.org/sensor_msgs) и других. + +Пример публикации сообщения типа [`std_msgs/String`](http://docs.ros.org/api/std_msgs/html/msg/String.html) в топик `/foo` на языке Python: ```python +import rospy from std_msgs.msg import String -# ... +rospy.init_node('my_ros_node') -foo_pub = rospy.Publisher('/foo', String, queue_size=1) # создаем Publisher'а - -# ... +foo_pub = rospy.Publisher('/foo', String, queue_size=1) # создаем Publisher foo_pub.publish(data='Hello, world!') # публикуем сообщение ``` @@ -62,31 +73,43 @@ foo_pub.publish(data='Hello, world!') # публикуем сообщение Пример подписки на топик `/foo`: ```python +import rospy +from std_msgs.msg import String + +rospy.init_node('my_ros_node') + def foo_callback(msg): print msg.data # Подписываемся. При получении сообщения в топик /foo будет вызвана функция foo_callback. rospy.Subscriber('/foo', String, foo_callback) + +rospy.spin() # входим в бесконечный цикл, чтобы программа не завершила работу ``` -Также, существует возможность работы с топиками с помощью утилиты `rostopic`. Например, с помощью следующей команды можно просматривать сообщения, публикуемые в топик `/mavros/state`: +Также существует возможность работы с топиками с помощью утилиты `rostopic`. Например, с помощью следующей команды можно просматривать сообщения, публикуемые в топик `/mavros/state`: ```bash rostopic echo /mavros/state ``` +Данные в топиках можно мониторить и визуализировать и в [графических инструментах ROS](ros_gui.md). + ### Сервисы -Основная статья: http://wiki.ros.org/Services +Основная статья: http://wiki.ros.org/Services. -Сервис – это некоторый аналог функции, которая может быть вызвана из одной ноды, а обработана в другой. У сервиса есть имя, аналогичное имени топика, и 2 типа сообщений: тип запроса и тип ответа. +Сервис – это аналог функции, которая вызывается в одной ноде, а обрабатывается в другой. У сервиса есть имя, строящееся аналогично имени топика, и тип, включающий в себя поля запроса и поля ответа. + +Таким образом, сервисы реализуют паттерн [*удаленного вызова процедур*](https://ru.wikipedia.org/wiki/Удалённый_вызов_процедур). Пример вызова ROS-сервиса из языка Python: ```python +import rospy from clover.srv import GetTelemetry -# ... +rospy.init_node('my_ros_node') # Создаем обертку над сервисом get_telemetry пакета clover с типом GetTelemetry: get_telemetry = rospy.ServiceProxy('get_telemetry', srv.GetTelemetry) @@ -103,9 +126,68 @@ rosservice call /get_telemetry "{frame_id: ''}" Больше примеров использования сервисов для автономных полетов квадрокоптера Клевер можно посмотреть в [документации ноды simple_offboard](simple_offboard.md). -Работа на нескольких машинах ---- +### Параметры + +TODO + +### Имена + +Основная статья: http://wiki.ros.org/Names. + +Любой топик, сервис или параметр идентифицируется с помощью уникального имени. ROS-имя представляет собой иерархическую структуру с символом `/` в качестве разделителя (сходно с именами в файловой системе). + +Примеры ROS-имен: + +* `/` (глобальное пространство имен) +* `/foo` +* `/stanford/robot/name` +* `/wg/node1` + +Эти имена является глобальными (аналогично полному пути в файлу в файловой системе). На практике рекомендуется использование *приватных* или *относительных* имен. + +#### Приватное имя + +Каждая нода может использовать собственное приватное пространство имен (соответствующее имени ноды) для своих ресурсов. Например, нода `aruco_detect` может публиковать такие топики: + +* `/aruco_detect/markers` +* `/aruco_detect/visualization` +* `/aruco_detect/debug` + +Когда нода ссылается на свой приватный ресурс, вместо пространства имен (`/aruco_detect/`) используется символ `~`, например: + +* `~markers` +* `~visualization` +* `~debug` + +Таким образом, создание топика `foo` в приватном пространство имен из Python будет выглядеть так: + +```python +private_foo_pub = rospy.Publisher('~foo', String, queue_size=1) +``` + +#### Относительное имя + +Несколько нод также могут объединяться в общее пространство имен (например, при одновременной работе нескольких роботов). Для того, чтобы ссылаться на топики с учетом общего пространства имен, в названии ресурса опускается начальный символ `/`. + +Пример создание топика `foo` с учетом общего пространства имен: + +```python +relative_foo_pub = rospy.Publisher('foo', String, queue_size=1) +``` + +> **Hint** В общем случае всегда рекомендуется использовать приватные или относительные имена ресурсов и никогда не использовать глобальные. + +## Работа на нескольких машинах Основная статья: http://wiki.ros.org/ROS/Tutorials/MultipleMachines. Преимуществом использования ROS является возможность распределения нод на несколько машин в сети. Например, ноду, осуществляющую распознавание образом на изображении можно запустить на более мощном компьютере; ноду, управляющую коптером можно запустить непосредственно на Raspberry Pi, подключенном к полетному контроллеру и т. д. + +## Дополнительные материалы + +* Учебник по ROS от Voltbro - http://docs.voltbro.ru/starting-ros/. +* Другие книги по ROS - http://wiki.ros.org/Books. + +**Далее**: [Графические инструменты ROS](ros_gui.md). + +[^1]: Также встречается перевод "узел". diff --git a/docs/ru/ros_advanced.md b/docs/ru/ros_advanced.md index 109de85f..26fb23f7 100644 --- a/docs/ru/ros_advanced.md +++ b/docs/ru/ros_advanced.md @@ -1,9 +1,25 @@ # Продвинутое использование ROS +## Работа с `roslaunch` + +Основная статья: https://wiki.ros.org/roslaunch + +TODO + ## Создание пакетов +ROS-пакет содержит ноды, типы сообщений и сервисов, launch-файлы и другие ресурсы, объединенные единой задачей. + +TODO + ## Создание собственных типов сообщений -### Топики +Основная статья: http://wiki.ros.org/ROS/Tutorials/CreatingMsgAndSrv. -### Сервисы +Для обмена данными [ROS-ноды](ros.md#Ноды) пересылают сообщения определенных типов. ROS включает в себя большое количество стандартных типов сообщений, покрывающих различные аспекты робототехники. Предпочтительным является использование стандартных типов сообщений, так как это может дать совместимость с большим количеством стандартным пакетом. + +Если для ваших данных стандартного типа сообщений не находится, можно создать собственный тип. + +ROS-сообщения описываются в файлах а расширением `.msg`. Они должны находиться в каталоге `msg` вашего пакета. Эти файлы являются простыми текстовыми файлами со списком типом и названий полей сообщения. + +TODO diff --git a/docs/ru/ros_conventions.md b/docs/ru/ros_conventions.md new file mode 100644 index 00000000..047a2bf5 --- /dev/null +++ b/docs/ru/ros_conventions.md @@ -0,0 +1,40 @@ +# Соглашения ROS + +Чтобы упростить взаимодействие компонентов системы и избежать ошибок, ROS вводит определенное количество соглашений. Программная платформа, где возможно, Клевера соответствует этим соглашениями. + +## Системы координат + +Все системы координат в ROS должны быть правыми тройками векторов, то есть соответствовать [правилу правой руки](https://ru.wikipedia.org/wiki/Правило_буравчика). Положительное направление вращения вокруг оси определяется правилом буравчика. + + + +## Единцы измерения + +Основной REP: https://www.ros.org/reps/rep-0103.html. + +Все ноды ROS должны (если возможно) использовать следующие единицы измерения во всех своих внешних интерфейсах. + +### Основные единицы + +|Наименование|Единица| +|------------|-------| +|Длина|метр| +|Масса|килограмм| +|Время|секунда| +|Сила тока|ампер| + +### Производные единицы + +|Наименование|Единица| +|------------|-------| +|Угол|радиан| +|Частота|герц| +|Сила|ньютон| +|Мощность|ватт| +|Напряжение|вольт| +|Температура|градус Цельсия| +|Магнитная индукция|тесла| + +> **Hint** Распространенной ошибкой является попытка использования градусов в качестве единиц измерения углов в интерфейсах ROS. Правильным является использование [радианов](https://ru.wikipedia.org/wiki/Радиан). + +**Далее**: [Продвинутое использование ROS](ros_advanced.md). diff --git a/docs/ru/ros_gui.md b/docs/ru/ros_gui.md index 5b6650ea..6abe0c6b 100644 --- a/docs/ru/ros_gui.md +++ b/docs/ru/ros_gui.md @@ -1 +1,5 @@ # Инструменты визуализации ROS + +TODO + +**Далее**: [Соглашения ROS](ros_conventions.md).