From 1282a28c2f0a3ebbf25e2e56763c7213fe41e95f Mon Sep 17 00:00:00 2001 From: Oleg Kalachev Date: Wed, 23 Jan 2019 21:40:29 +0300 Subject: [PATCH] docs: update docs for new simple_offboard and frames settings --- docs/ru/arduino.md | 5 +-- docs/ru/aruco.md | 8 ++-- docs/ru/camera_frame.md | 14 ++++--- docs/ru/frames.md | 8 ++-- docs/ru/rviz.md | 2 +- docs/ru/simple_offboard.md | 80 ++++++++++++++++---------------------- docs/ru/snippets.md | 6 +-- docs/ru/sonar.md | 4 +- 8 files changed, 60 insertions(+), 67 deletions(-) diff --git a/docs/ru/arduino.md b/docs/ru/arduino.md index 0150ec606..b5837219d 100644 --- a/docs/ru/arduino.md +++ b/docs/ru/arduino.md @@ -110,7 +110,7 @@ void setup() nav_req.x = 0; nav_req.y = 0; nav_req.z = 2; - nav_req.frame_id = "fcu_horiz"; + nav_req.frame_id = "body"; nav_req.speed = 0.5; navigate.call(nav_req, nav_res); @@ -128,7 +128,7 @@ void setup() nav_req.x = 3; nav_req.y = 0; nav_req.z = 0; - nav_req.frame_id = "fcu_horiz"; + nav_req.frame_id = "body"; nav_req.speed = 0.8; navigate.call(nav_req, nav_res); @@ -145,7 +145,6 @@ void setup() nav_req.y = 0; nav_req.z = 2; nav_req.frame_id = "aruco_map"; - nav_req.update_frame = true; nav_req.speed = 0.8; navigate.call(nav_req, nav_res); diff --git a/docs/ru/aruco.md b/docs/ru/aruco.md index 60c0d05ac..4242f006d 100644 --- a/docs/ru/aruco.md +++ b/docs/ru/aruco.md @@ -1,5 +1,7 @@ # Навигация с использованием ArUco-маркеров +> **Note** Документация для версий [образа](microsd_images.md), начиная с **0.15**. Для более ранних версий см. [документацию для версии **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/aruco.md). + [ArUco-маркеры](https://docs.opencv.org/3.2.0/d5/dae/tutorial_aruco_detection.html) — это популярная технология для позиционирования роботехнических систем с использованием компьютерного зрения. @@ -141,12 +143,12 @@ _Примечание_: указанное выше определение пр ```python # Вначале необходимо взлететь, чтобы коптер увидел карту меток # и появился фрейм aruco_map: -navigate(0, 0, 2, frame_id='fcu_horiz', speed=0.5, auto_arm=True) # взлет на 2 метра +navigate(0, 0, 2, frame_id='body', speed=0.5, auto_arm=True) # взлет на 2 метра time.sleep(5) # Полет в координату 2:2 маркерного поля, высота 2 метра -navigate(2, 2, 2, speed=1, frame_id='aruco_map', update_frame=True) # полет в координату 2:2, высота 3 метра +navigate(2, 2, 2, speed=1, frame_id='aruco_map') # полет в координату 2:2, высота 3 метра ``` См. [другие функции](simple_offboard.md) simple_offboard. @@ -160,7 +162,7 @@ navigate(2, 2, 2, speed=1, frame_id='aruco_map', update_frame=True) # поле Чтобы задавать карту маркеров в "перевернутой" системе координат, необходимо изменить параметр `aruco_orientation` в файле `~/catkin_ws/src/clever/clever/aruco.launch`: ```xml - + ``` При задании вышеуказанного параметра фрейм aruco\_map также окажется "перевернутым". Таким образом, для полета на высоту 2 метра ниже потолка, аргумент `z` нужно устанавливать в 2: diff --git a/docs/ru/camera_frame.md b/docs/ru/camera_frame.md index 453ef9200..01bc66265 100644 --- a/docs/ru/camera_frame.md +++ b/docs/ru/camera_frame.md @@ -1,12 +1,14 @@ # Настройка расположения основной камеры +> **Note** Документация для версий [образа](microsd_images.md), начиная с **0.15**. Для более ранних версий см. [документацию для версии **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/camera_frame.md). + Расположение и ориентация основной камеры задается в файле `~/catkin_ws/src/clever/clever/launch/main_camera.launch`: ```xml - + ``` -Эта строка задает статическую трансформацию между фреймом `fcu` ([соответствует корпусу полетного контроллера](frames.md)) и камерой (`main_camera_optical`) в формате: +Эта строка задает статическую трансформацию между фреймом `base_link` ([соответствует корпусу полетного контроллера](frames.md)) и камерой (`main_camera_optical`) в формате: ```txt сдвиг_x сдвиг_y сдвиг_z угол_рысканье угол_тангаж угол_крен @@ -27,7 +29,7 @@ ### 1. Камера направлена вниз, шлейф назад ```xml - + ``` @@ -36,7 +38,7 @@ ### 2. Камера направлена вниз, шлейф вперёд ```xml - + ``` @@ -45,7 +47,7 @@ ### 3. Камера направлена вверх, шлейф назад ```xml - + ``` @@ -54,7 +56,7 @@ ### 4. Камера направлена вверх, шлейф вперёд ```xml - + ``` diff --git a/docs/ru/frames.md b/docs/ru/frames.md index 93a00526b..52893ef39 100644 --- a/docs/ru/frames.md +++ b/docs/ru/frames.md @@ -1,13 +1,15 @@ Системы координат (фреймы) === +> **Note** Документация для версий [образа](microsd_images.md), начиная с **0.15**. Для более ранних версий см. [документацию для версии **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/frames.md). + ![Системы координаты Клевера (TF2)](../assets/frames.png) Основные фреймы в пакете `clever`: -* `local_origin` — координаты относительно точки инициализации полетного контроллера: белая сетка на иллюстрации; -* `fcu` — координаты относительно квадрокоптера: схематичное изображение квадрокоптера на иллюстрации; -* `fcu_horiz` — координаты относительно квадрокоптера без учета наклонов по тангажу и крену: красная, синия и зеленая линии на иллюстрации. +* `map` — координаты относительно точки инициализации полетного контроллера: белая сетка на иллюстрации; +* `base_link` — координаты относительно квадрокоптера: схематичное изображение квадрокоптера на иллюстрации; +* `body` — координаты относительно квадрокоптера без учета наклонов по тангажу и крену: красная, синия и зеленая линии на иллюстрации. > **Hint** В соответствии с [соглашением](http://www.ros.org/reps/rep-0103.html), для фреймов, связанных с коптером, ось X направлена вперед, Y – налево и Z – вверх. diff --git a/docs/ru/rviz.md b/docs/ru/rviz.md index badb4b982..7a26ef891 100644 --- a/docs/ru/rviz.md +++ b/docs/ru/rviz.md @@ -31,7 +31,7 @@ export ROS_IP=192.168.11.1 ### Визуализация положения коптера -В качестве reference frame рекомендуется установить фрейм `local_origin`. Для визуализации коптера добавьте визуализационные маркеры из топика `/vehicle_markers`. Для визуализации камеры коптера добавьте визуализационные маркеры из топика `/main_camera/camera_markers`. +В качестве reference frame рекомендуется установить фрейм `map`. Для визуализации коптера добавьте визуализационные маркеры из топика `/vehicle_markers`. Для визуализации камеры коптера добавьте визуализационные маркеры из топика `/main_camera/camera_markers`. Результат визуализации коптера и камеры представлен ниже: diff --git a/docs/ru/simple_offboard.md b/docs/ru/simple_offboard.md index 914e1337f..4f1d02745 100644 --- a/docs/ru/simple_offboard.md +++ b/docs/ru/simple_offboard.md @@ -1,26 +1,14 @@ Simple offboard === +> **Note** Документация для версий [образа](microsd_images.md), начиная с **0.15**. Для более ранних версий см. [документацию для версии **0.14**](https://github.com/CopterExpress/clever/blob/v0.14/docs/ru/simple_offboard.md). + Модуль `simple_offboard` пакета `clever` предназначен для упрощенного программирования автономного дрона ([режим](modes.md) `OFFBOARD`). Он позволяет устанавливать желаемые полетные задачи и автоматически трансформирует [систему координат](frames.md). `simple_offboard` является высокоуровневым способом взаимодействия с полетным контроллером. Для более низкоуровневой работы см. [mavros](mavros.md). Основные сервисы – `get_telemetry` (получение всей телеметрии), `navigate` (полет в заданную точку по прямой), `navigate_global` (полет в глобальную точку по прямой), `land` (переход в режим посадки). -Общие для сервисов параметры: - -* `auto_arm` = `true`/`false` – перевести коптер в `OFFBOARD` и заармить автоматически (**коптер взлетит**); -* `frame_id` — система координат в TF2, в которой заданы координаты и рысканье (yaw), [описание систем координат](frames.md), значение по умолчанию: `local_origin`; -* `update_frame` — считать ли систему координат изменяющейся (например, `false` для `local_origin`, `fcu`, `fcu_horiz`, `true` для `marker_map`); -* `x`, `y` – горизонтальные координаты в системе координат `frame_id` *(м)*; -* `z` — высота в системе координат `frame_id` *(м)*; -* `lat`, `lon` – широта и долгота *(градусы)*; -* `yaw` — рысканье в радианах в системе координат `frame_id` (0 – коптер смотрит по оси X); -* `yaw_rate` — угловая скорость по рысканью в радианах в секунду (против часовой), `yaw` должен быть установлен в NaN; -* `thrust` — уровень газа от 0 (нет газа) до 1 (полный газ). - -> **Warning** API модуля `simple_offboard` на данный момент нестабилен и может измениться. - Использование из языка Python --- @@ -59,11 +47,11 @@ release = rospy.ServiceProxy('release', Trigger) Параметры: -* `frame_id` – [фрейм](frames.md) для значений `x`, `y`, `z`, `vx`, `vy`, `vz`. Пример: `local_origin`, `fcu_horiz`, `aruco_map`. Значение по умолчанию: `local_origin`. +* `frame_id` – [система координат](frames.md) для значений `x`, `y`, `z`, `vx`, `vy`, `vz`. Пример: `map`, `body`, `aruco_map`. Значение по умолчанию: `map`. Формат ответа: -* `frame_id` – фрейм; +* `frame_id` – система координат; * `connected` – есть ли подключение к FCU; * `armed` – состояние `armed` винтов (винты включены, если true); * `mode` – текущий [полетный режим](modes.md); @@ -73,7 +61,7 @@ release = rospy.ServiceProxy('release', Trigger) * `vx, vy, vz` – скорость коптера *(м/с)*; * `pitch` – угол по тангажу *(радианы)*; * `roll` – угол по крену *(радианы)*; -* `yaw` – угол по рысканью в фрейме `frame_id`; +* `yaw` – угол по рысканью *(радианы)*; * `pitch_rate` – угловая скорость по тангажу *(рад/с)*; * `roll_rate` – угловая скорость по крену *(рад/с)*; * `yaw_rate` – угловая скорость по рысканью *(рад/с)*; @@ -118,19 +106,19 @@ rosservice call /get_telemetry "{frame_id: ''}" Параметры: -* `x`, `y`, `z` – координаты в системе `frame_id` *(м)*; +* `x`, `y`, `z` – координаты *(м)*; * `yaw` – угол по рысканью *(радианы)*; * `yaw_rate` – угловая скорость по рысканью (применяется при установке yaw в `NaN`) *(рад/с)*; * `speed` – скорость полета (скорость движения setpoint) *(м/с)*; * `auto_arm` – перевести коптер в `OFFBOARD` и заармить автоматически (**коптер взлетит**); -* `frame_id`, `update_frame`. +* `frame_id` – [система координат](frames.md), в которой заданы `x`, `y`, `z` и `yaw` (по умолчанию: `map`). > **Note** Для полета без изменения угла по рыскаью достаточно установить `yaw` в `NaN` (значение угловой скорости по-умолчанию – 0). Взлет на высоту 1.5 м со скоростью взлета 0.5 м/с: ```python -navigate(x=0, y=0, z=1.5, speed=0.5, frame_id='fcu_horiz', auto_arm=True) +navigate(x=0, y=0, z=1.5, speed=0.5, frame_id='body', auto_arm=True) ``` Полет по прямой в точку 5:0 (высота 2) в локальной системе координат со скоростью 0.8 м/с (рысканье установится в 0): @@ -148,37 +136,37 @@ navigate(x=5, y=0, z=3, speed=0.8, yaw=float('nan')) Полет вправо относительно коптера на 3 м: ```python -navigate(x=0, y=-3, z=0, speed=1, frame_id='fcu_horiz') +navigate(x=0, y=-3, z=0, speed=1, frame_id='body') ``` Повернуться на 90 градусов против часовой: ```python -navigate(yaw=math.radians(-90), frame_id='fcu_horiz') +navigate(yaw=math.radians(-90), frame_id='body') ``` Полет в точку 3:2 (высота 2) в системе координат [маркерного поля](aruco.md) со скоростью 1 м/с: ```python -navigate(x=3, y=2, z=2, speed=1, frame_id='aruco_map', update_frame=True) +navigate(x=3, y=2, z=2, speed=1, frame_id='aruco_map') ``` Вращение на месте со скоростью 0.5 рад/c (против часовой): ```python -navigate(x=0, y=0, z=0, yaw=float('nan'), yaw_rate=0.5, frame_id='fcu_horiz') +navigate(x=0, y=0, z=0, yaw=float('nan'), yaw_rate=0.5, frame_id='body') ``` Полет вперед 3 метра со скоростью 0.5 м/с, вращаясь по рысканью со скоростью 0.2 рад/с: ```python -navigate(x=3, y=0, z=0, speed=0.5, yaw=float('nan'), yaw_rate=0.2, frame_id='fcu_horiz') +navigate(x=3, y=0, z=0, speed=0.5, yaw=float('nan'), yaw_rate=0.2, frame_id='body') ``` Взлет на высоту 2 м (командная строка): ```bash -rosservice call /navigate "{x: 0.0, y: 0.0, z: 2, yaw: 0.0, yaw_rate: 0.0, speed: 0.5, frame_id: 'fcu_horiz', update_frame: false, auto_arm: true}" +rosservice call /navigate "{x: 0.0, y: 0.0, z: 2, yaw: 0.0, yaw_rate: 0.0, speed: 0.5, frame_id: 'body', auto_arm: true}" ``` ### navigate_global @@ -188,31 +176,31 @@ rosservice call /navigate "{x: 0.0, y: 0.0, z: 2, yaw: 0.0, yaw_rate: 0.0, speed Параметры: * `lat`, `lon` – широта и долгота *(градусы)*; -* `z` – высота в системе координат `frame_id` *(м)*; +* `z` – высота *(м)*; * `yaw` – угол по рысканью *(радианы)*; * `yaw_rate` – угловая скорость по рысканью (при установке yaw в `NaN`) *(рад/с)*; * `speed` – скорость полета (скорость движения setpoint) *(м/с)*; * `auto_arm` – перевести коптер в `OFFBOARD` и заармить автоматически (**коптер взлетит**); -* `frame_id`, `update_frame`. +* `frame_id` – [система координат](frames.md), в которой заданы `z` и `yaw` (по умолчанию: `map`). > **Note** Для полета без изменения угла по рыскаью достаточно установить `yaw` в `NaN` (значение угловой скорости по-умолчанию – 0). Полет в глобальную точку со скоростью 5 м/с, оставаясь на текущей высоте (`yaw` установится в 0, коптер сориентируется передом на восток): ```python -navigate_global(lat=55.707033, lon=37.725010, z=0, speed=5, frame_id='fcu_horiz') +navigate_global(lat=55.707033, lon=37.725010, z=0, speed=5, frame_id='body') ``` Полет в глобальную точку без изменения угла по рысканью (`yaw` = `NaN`, `yaw_rate` = 0): ```python -navigate_global(lat=55.707033, lon=37.725010, z=0, speed=5, yaw=float('nan'), frame_id='fcu_horiz') +navigate_global(lat=55.707033, lon=37.725010, z=0, speed=5, yaw=float('nan'), frame_id='body') ``` Полет в глобальную точку (командная строка): ```bash -rosservice call /navigate_global "{lat: 55.707033, lon: 37.725010, z: 0.0, yaw: 0.0, yaw_rate: 0.0, speed: 5.0, frame_id: 'fcu_horiz', update_frame: false, auto_arm: false}" +rosservice call /navigate_global "{lat: 55.707033, lon: 37.725010, z: 0.0, yaw: 0.0, yaw_rate: 0.0, speed: 5.0, frame_id: 'body', auto_arm: false}" ``` ### set_position @@ -223,34 +211,34 @@ rosservice call /navigate_global "{lat: 55.707033, lon: 37.725010, z: 0.0, yaw: Параметры: -* `x`, `y`, `z` – координаты точки в системе координат `frame_id` *(м)*; +* `x`, `y`, `z` – координаты точки *(м)*; * `yaw` – угол по рысканью *(радианы)*; * `yaw_rate` – угловая скорость по рысканью (при установке yaw в NaN) *(рад/с)*; * `auto_arm` – перевести коптер в `OFFBOARD` и заармить автоматически (**коптер взлетит**); -* `frame_id`, `update_frame`. +* `frame_id` – [система координат](frames.md), в которой заданы `x`, `y`, `z` и `yaw` (по умолчанию: `map`). Зависнуть на месте: ```python -set_position(frame_id='fcu_horiz') +set_position(frame_id='body') ``` Назначить целевую точку на 3 м выше текущей позиции: ```python -set_position(x=0, y=0, z=3, frame_id='fcu_horiz') +set_position(x=0, y=0, z=3, frame_id='body') ``` Назначить целевую точку на 1 м впереди текущей позиции: ```python -set_position(x=1, y=0, z=0, frame_id='fcu_horiz') +set_position(x=1, y=0, z=0, frame_id='body') ``` Вращение на месте со скоростью 0.5 рад/c: ```python -set_position(x=0, y=0, z=0, frame_id='fcu_horiz', yaw=float('nan'), yaw_rate=0.5) +set_position(x=0, y=0, z=0, frame_id='body', yaw=float('nan'), yaw_rate=0.5) ``` ### set_velocity @@ -261,34 +249,32 @@ set_position(x=0, y=0, z=0, frame_id='fcu_horiz', yaw=float('nan'), yaw_rate=0.5 * `yaw` – угол по рысканью *(радианы)*; * `yaw_rate` – угловая скорость по рысканью (при установке yaw в NaN) *(рад/с)*; * `auto_arm` – перевести коптер в `OFFBOARD` и заармить автоматически (**коптер взлетит**); -* `frame_id`, `update_frame`. +* `frame_id` – [система координат](frames.md), в которой заданы `vx`, `vy`, `vz` и `yaw` (по умолчанию: `map`). > **Note** Параметр `frame_id` определяет только ориентацию результирующего вектора скорости, но не его длину. Полет вперед (относительно коптера) со скоростью 1 м/с: ```python -set_velocity(vx=1, vy=0.0, vz=0, frame_id='fcu_horiz') +set_velocity(vx=1, vy=0.0, vz=0, frame_id='body') ``` Один из вариантов полета по кругу: ```python -set_velocity(vx=0.4, vy=0.0, vz=0, yaw=float('nan'), yaw_rate=0.4, frame_id='fcu_horiz', update_frame=True) +set_velocity(vx=0.4, vy=0.0, vz=0, yaw=float('nan'), yaw_rate=0.4, frame_id='body') ``` ### set_attitude Установить тангаж, крен, рысканье и уровень газа (примерный аналог управления в [режиме `STABILIZED`](modes.md)). Данный сервис может быть использован для более низкоуровнего контроля поведения коптера либо для управления коптером при отсутствии источника достоверных данных о его позиции. -> **Note** Параметр `frame_id` определяет только систему координат, в которой задается рысканье (`yaw`). - Параметры: * `pitch`, `roll`, `yaw` – необходимый угол по тангажу, крену и рысканью *(радианы)*; -* `thrust` – уровень газа от 0 (нет газа) до 1 (полный газ); +* `thrust` – уровень газа от 0 (нет газа, пропеллеры остановлены) до 1 (полный газ); * `auto_arm` – перевести коптер в `OFFBOARD` и заармить автоматически (**коптер взлетит**); -* `frame_id`, `update_frame`. +* `frame_id` – [система координат](frames.md), в которой задан `yaw` (по умолчанию: `map`). ### set_rates @@ -297,14 +283,14 @@ set_velocity(vx=0.4, vy=0.0, vz=0, yaw=float('nan'), yaw_rate=0.4, frame_id='fcu Параметры: * `pitch_rate`, `roll_rate`, `yaw_rate` – угловая скорость по танажу, крену и рыканью *(рад/с)*; -* `thrust` – уровень газа от 0 (нет газа) до 1 (полный газ). +* `thrust` – уровень газа от 0 (нет газа, пропеллеры остановлены) до 1 (полный газ). * `auto_arm` – перевести коптер в `OFFBOARD` и заармить автоматически (**коптер взлетит**); ### land Перевести коптер в [режим](modes.md) посадки (`AUTO.LAND` или аналогичный). -> **Note** Для автоматического отключения винтов после посадки PX4-параметр `COM_DISARM_LAND` должен быть установлен в значение > 0. +> **Note** Для автоматического отключения винтов после посадки [параметр PX4](px4_parameters.md) `COM_DISARM_LAND` должен быть установлен в значение > 0. Посадка коптера: @@ -321,9 +307,11 @@ if res.success: rosservice call /land "{}" ``` + Дополнительные материалы ------------------------ diff --git a/docs/ru/snippets.md b/docs/ru/snippets.md index efa9db5d4..2b2bbe5c3 100644 --- a/docs/ru/snippets.md +++ b/docs/ru/snippets.md @@ -39,7 +39,7 @@ tolerance = 0.2 # точность проверки высоты (м) start = get_telemetry() # Взлетаем на 2 м -print navigate(z=z, speed=0.5, frame_id='fcu_horiz', auto_arm=True) +print navigate(z=z, speed=0.5, frame_id='body', auto_arm=True) # Ожидаем взлета while True: @@ -100,14 +100,14 @@ tf_listener = tf2_ros.TransformListener(tf_buffer) # Создаем объект PoseStamped (либо получаем из топика): pose = PoseStamped() -pose.header.frame_id = 'local_origin' # фрейм, в котором задана позиция +pose.header.frame_id = 'map' # фрейм, в котором задана позиция pose.header.stamp = rospy.get_rostime() # момент времени, для которого задана позиция (текущее время) pose.pose.position.x = 1 pose.pose.position.y = 2 pose.pose.position.z = 3 pose.pose.orientation.w = 1 -frame_id = 'fcu' # целевой фрейм +frame_id = 'base_link' # целевой фрейм transform_timeout = rospy.Duration(0.2) # таймаут ожидания транформации # Преобразовываем позицию из старого фрейма в новый: diff --git a/docs/ru/sonar.md b/docs/ru/sonar.md index e7a59447c..0339abd97 100644 --- a/docs/ru/sonar.md +++ b/docs/ru/sonar.md @@ -123,11 +123,11 @@ while True: Пример полетной программы с использованием [simple_offboard](simple_offboard.md), которая заставляет коптер лететь вперед, пока подключенный ультразвуковой дальномер не задетектирует препятствие: ```python -set_velocity(x=0.5, frame_id='fcu_horiz', auto_arm=True) # полет вперед со скоростью 0.5 мс +set_velocity(x=0.5, frame_id='body', auto_arm=True) # полет вперед со скоростью 0.5 мс while True: if read_distance_filtered() < 1: # если препятствие ближе, чем в 1 м, зависаем в точке - set_position(x=0, y=0, z=0, frame_id='fcu_horiz') + set_position(x=0, y=0, z=0, frame_id='body') rospy.sleep(0.1) ```