robossembler/robossembler.org
7
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

Software use cases page

Browse source
This commit is contained in:
Igor Brylev 2024-12-11 20:13:55 +00:00
parent d87d005f8a
commit fe245d1e49
7 changed files with 232 additions and 362 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/robossembler-framework.md
View file

@ -67,4 +67,23 @@ title: Фреймворк Робосборщик
- Не поддерживает ROS2
- Не поддерживает алгоритмы машинного обучения.
__AutoAssembly__. Разрабатывается командой робототехников из компании Arrival, известного производителя электромобилей с R&D командой из Санкт-Петербурга. Фреймворк предназначен для автоматической роботизированной сборки напрямую из CAD. В научной публикации с описанием фреймворка представлена практическая реализация на примере двух манипуляторов Universal Robotics. Исходный код проекта не публикуется; многие технические решения (спецификации, схемы данных, описания языков, тип базы данных) неизвестны. Более подробный обзор см. по [ссылке](/docs/papers/auto-assembly).
__AutoAssembly__. Разрабатывается командой робототехников из компании Arrival, известного производителя электромобилей с R&D командой из Санкт-Петербурга. Фреймворк предназначен для автоматической роботизированной сборки напрямую из CAD. В научной публикации с описанием фреймворка представлена практическая реализация на примере двух манипуляторов Universal Robotics. Исходный код проекта не публикуется; многие технические решения (спецификации, схемы данных, описания языков, тип базы данных) неизвестны. Более подробный обзор см. по [ссылке](/docs/papers/auto-assembly).
## Минимальные технические требования
Минимальные системные требования для запуска модуля исполнения планов:
1. **Важно!** Совместимо только с операционной системой Ubuntu 22.04.
2. Процессор: 64-разрядный процессор с поддержкой SSE4.2 (например, Intel Core i3 или AMD Ryzen 3).
3. Оперативная память: не менее 8 ГБ RAM.
4. Свободное место на диске: не менее 50 ГБ свободного места на диске.
5. Графический процессор: не требуется, но рекомендуется для визуализации и симуляции; для ускорения инференса моделей весов искусственных нейронных сетей может быть использован графический ускоритель.
6. ROS 2 версия: Humble.
Минимальные системные требования для запуска остальных модулей:
1. Операционная система: Ubuntu 18.04 (Bionic Beaver) или более новая версия, либо Windows 10 или более новая версия.
2. Процессор: 64-разрядный процессор с поддержкой SSE4.2 (например, Intel Core i5 или AMD Ryzen 5).
3. Оперативная память: не менее 16 ГБ RAM.
4. Свободное место на диске: не менее 150 ГБ свободного места на диске.
5. Графический процессор: NVIDIA GeForce RTX 2060 Super с поддержкой CUDA 10.0 или более новой версии.

BIN
docs/software/img/rbs_imitation_learning_usecase.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 176 KiB

113
docs/software/ros2.md
View file

@ -13,7 +13,7 @@ title: Модуль исполнения планов
- **`env_manager`** - менеджер виртуальных сред:
- **`env_manager`** - управление объектами в сцене симуляции Gazebo.
- **`env_manager_interfaces`** - ROS 2 интерфейсы для конфигурации, загрузки, активации и выгрузки сред.
- **`rbs_gym`** - модуль обучения с подкреплением: управление обучением, создание симуляционных сред, управление пространствами действий и наблюдений, утилиты.
- **`rbs_gym`** - модуль обучения с подкреплением: управление обучением, создание симуляционных сред, управление пространствами действий и наблюдений, утилиты. Предназначен для реализации среды обучения с подкреплением для роботов-манипуляторов. Он активно использует возможности пакета **env_manager**, упрощая управление сценой и настройку среды. Подробнее о нём в разделе [Сценарии использования](usecases).
- **`rbs_runtime`** - запуск основного рантайма с использованием `env_manager`.
- **`rbs_bringup`** - запуск сценариев: симуляция, реальный робот, многороботные конфигурации.
- **`rbs_bt_executor`** - выполнение деревьев поведения с Behavior Tree CPP v4.
@ -30,117 +30,6 @@ title: Модуль исполнения планов
Модуль **rbs_runtime** предназначен для управления симуляцией в режиме реального времени. Если **env_manager** отвечает за конфигурирование сцены, а **rbs_gym** связывает обучаемых агентов с ROS2, то **rbs_runtime** используется для стандартного запуска симуляции без ограничения по времени. Этот модуль представляет собой обёртку для запуска **env_manager** как ROS2-ноды и реализует базовые сервисы управления средой. На данный момент доступен сервис сброса симуляции в начальное состояние. При этом, если для объектов сцены установлены параметры рандомизации, они будут пересчитаны и применены при каждом сбросе. Модуль обеспечивает интеграцию конфигураций среды в инфраструктуру ROS2 и позволяет легко запускать симуляцию, оставляя её гибкой для последующего расширения или взаимодействия.
## rbs_gym
Модуль **rbs_gym** предназначен для реализации среды обучения с подкреплением для роботов-манипуляторов. Он активно использует возможности пакета **env_manager**, упрощая управление сценой и настройку среды.
Основные компоненты модуля обеспечивают:
- получение пространства наблюдения,
- передачу управляющих сигналов агенту,
- рандомизацию параметров среды,
- настройку задач, определяющих награды и условия для агента.
### Пространства наблюдения и действий
**Пространство наблюдения** включает:
- скорость на эффекторе робота,
- положения суставов робота,
- изображения с камеры (глубина, цвет или облака точек).
**Пространство действий** позволяет:
- отправлять управляющие сигналы в виде усилий или скоростей в пространстве задач робота,
- управлять положением захватного устройства,
- задавать усилия в конфигурационном пространстве робота.
### Гибкая настройка агентов
В составе модуля реализован класс **ExperimentManager**, который управляет предварительной настройкой агентов обучения. Конфигурации описываются в формате YAML. Пример гиперпараметров для алгоритма TD3 доступен [здесь](https://git.robossembler.org/nodes/seed.robossembler.org/rad:z46gtVRpXaXrGQM7Fxiqu7pLy7kip/tree/env_manager/rbs_gym/hyperparams/td3.yml).
Поддерживаются следующие алгоритмы обучения:
- [TD3](https://arxiv.org/abs/1802.09477)
- [SAC](https://arxiv.org/abs/1801.01290)
- [TQC](https://arxiv.org/abs/2005.04269)
### Общая структура и примеры
Общий вид среды обучения для задачи достиженая точки пространства представлен на изображении:
![rbs_gym_env_view](./img/env.jpg)
_Общий вид среды для задачи "достижения точки" в **rbs_gym**_
На рисунке точка отмечена зеленым шаром. Каждую эпоху обучения выбираются разные позиции для робота в конфигурационном пространстве, а также позиция объекта выбирается случайным образом.
Диаграмма классов на примере задачи Reach детализирует архитектуру модуля:
![rbs_gym_class_diagram](./img/rbs_gym_class_diagram.png)
*Диаграмма классов для задачи Reach*
Агент использует усилия в пространстве задач для достижения до точки.
**Управляющие сигналы**:
$$
\bm{W} = \begin{bmatrix} f_x & f_y & f_z & 0 & 0 & 0 \end{bmatrix}^T
$$
где $f$ — компоненты силы.
**Пространство наблюдения**:
$$
\bm{O} = \begin{bmatrix} \bm{p}_e & \bm{p}_o & \bm{v}_e \end{bmatrix}^T
$$
где:
- $\bm{p}_e = [x, y, z]^T$ — положение эффектора робота,
- $\bm{p}_o = [x, y, z]^T$ — положение цели,
- $\bm{v}_e$ — пространственный вектор скорости эффектора.
**Функция наград**:
1. **За уменьшение дистанции до цели**:
$$
R_d = \sum_{t=0}^{T-1} \Delta D_t \cdot 10
$$
где $T$ — число шагов, $D_t$ — расстояние до цели, $\Delta D_t = D_{t} - D_{t-1}$.
2. **За коллизии**:
$$
R_c = \sum_{t=0}^{T-1} \begin{cases}
-10, & \text{если } q_t \in C_o, \\
0, & \text{иначе}
\end{cases}
$$
где $C_o$ — пространство коллизий.
3. **Штраф за медленное выполнение задачи**:
$$
R_q = \sum_{t=0}^{T-1} -0.01
$$
4. **Бонус за достижение цели**:
$$
R_s = \begin{cases}
100, & \text{если } D_t < 0.05, \\
0, & \text{иначе.}
\end{cases}
$$
**Результирующая награда**:
$$
R = R_c + R_d + R_q + R_s
$$
Агент считается обученным, если $R = 100 \pm 10$ за эпизод.
## rbs_assets_library
**rbs_assets_library** представляет собой инструмент для интеграции трёхмерных объектов в симуляцию. Она содержит все необходимые ресурсы, включая возможность автоматического расчета инерциальных параметров на основе геометрии объекта. Это достигается благодаря использованию библиотеки **trimesh**, которая анализирует предоставленные модели и генерирует данные, необходимые для корректного воспроизведения физики объекта в симуляторе.

83
docs/software/ros2/installation.md
View file

@ -1,32 +1,77 @@
# Инструкция по установке фреймворка
Первым делом необходимо установить [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html). Рекомендуется минимальная установка.
## Шаг 1: Установка ROS2 Humble
Вторым делом надо собрать [`ros2_control`](https://github.com/ros-controls/ros2_control) из исходников из этого [форка](https://github.com/solid-sinusoid/ros2_control/tree/gz-ros2-cartesian-controllers) стоит отметить, что также существует альтернативная установка с использованием [`vsctool`](https://github.com/dirk-thomas/vcstool) который поставляется с базовыми пакетами ROS2.
Для начала установите [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html).
Рекомендуется минимальная установка `ros-humble-ros-base`, а также пакет `ros-dev-tools`.
Если устанавливать через `vcstool` тогда необходимые пакеты будут клонированы в тоже рабочее пространство, что и сам фреймворк. Сама команда будет выглядеть так
## Шаг 2: Проверка среды ROS2
Перед продолжением убедитесь, что среда ROS2 активирована. Для этого выполните:
```sh
vcs import . < robossembler-ros2/repos/all-deps.repos
source /opt/ros/humble/setup.bash
```
Заодно можно выполнить команду для установки всех требуемых библиотек Python
```shell
pip insatll -r robossembler-ros2/repos/requirements.txt
## Шаг 3: Если Вы этого не делали то сделайте
```sh
sudo rosdep init
rosdep update
```
При этом команду надо выполнять в директории `{robossembler_ws}/src/`
## Шаг 4: Установка фреймворка
Более четкая последовательность команд кому лень:
```sh
cd
mkdir -p robossembler-ros2/src && cd robossembler-ros2
git clone git clone https://seed.robossembler.org/z46gtVRpXaXrGQM7Fxiqu7pLy7kip.git robossembler-ros2
# Или если вы предпочитаете radicle
rad clone rad:z46gtVRpXaXrGQM7Fxiqu7pLy7kip
cd src
vcs import . < robossembler-ros2/repos/all-deps.repos
pip insatll -r robossembler-ros2/repos/requirements.txt
cd ..
rosdep install --from-paths src -y --ignore-src
colcon build --symlink-install
mkdir -p robossembler-ws/src && cd robossembler-ws/src
git clone --recurse-submodules https://gitlab.com/robossembler/robossembler-ros2.git
```
Далее необходимо собрать [`ros2_control`](https://github.com/ros-controls/ros2_control) из исходников, используя этот [форк](https://github.com/solid-sinusoid/ros2_control/tree/gz-ros2-cartesian-controllers).
Также доступна альтернатива с использованием [`vsctool`](https://github.com/dirk-thomas/vcstool), который входит в состав базовых пакетов ROS2.
Если вы решили использовать `vcstool`, нужные пакеты будут клонированы в тоже рабочее пространство, что и сам фреймворк. Команда для этого выглядит следующим образом:
```sh
vcs import . < robossembler-ros2/repos/all-deps.repos
```
Вы также можете установить все необходимые библиотеки Python, выполнив команду:
```shell
pip install -r robossembler-ros2/repos/requirements.txt
# Если Вы получили ошибку с установкой Shapely
sudo apt install libgeos-dev
```
> **[!ВНИМАНИЕ]**
> Убедитесь, что у вас установлен `git lfs`. В файле `requirements.txt` указан модуль `rbs_assets_library`, который содержит большие файлы и устанавливается как Python-модуль.
Эти команды нужно выполнять в директории `robossembler-ws/src/`.
Установка зависимостей при помощи `rosdep`
```sh
cd ~/robossembler-ws
rosdep install --from-paths src -y --ignore-src --rosdistro ${ROS_DISTRO}
```
Сборка фреймворка при помощи `colcon`
```sh
colcon build
```
## Полная последовательность команд
Ниже приведён полный набор команд для настройки фреймворка:
```sh
cd
mkdir -p robossembler-ws/src && cd robossembler-ws/src
git clone --recurse-submodules https://gitlab.com/robossembler/robossembler-ros2.git
# Или, если вы предпочитаете Radicle:
git clone --recurse-submodules https://seed.robossembler.org/z46gtVRpXaXrGQM7Fxiqu7pLy7kip.git robossembler-ros2
rad clone rad:z46gtVRpXaXrGQM7Fxiqu7pLy7kip
vcs import . < robossembler-ros2/repos/all-deps.repos
pip install -r robossembler-ros2/repos/requirements.txt
cd ..
rosdep install --from-paths src -y --ignore-src --rosdistro ${ROS_DISTRO}
colcon build
```

230
docs/software/shalenikol_commits_4th_milestone.md
View file

@ -1,230 +0,0 @@
---
id: report4part
title: work for the 4 reporting period
---
## Общий список работ
1) перевод навыков компьютерного зрения на работу через интерфейсную ноду (Object Detection, Pose Estimation)
2) тестирование и отладка интерфейсов веб-сервиса для создания деревьев поведения
- добавление новых деталей в проект
- разработка новой схемы описания зависимостей, основанной на применении топиков ROS2
- использование цифровых двойников (Digital Twins)
- получение интерфейсов ROS2: GetInterfaces
- переход на новую версию деревьев поведения (с 3 на 4)
- добавление условий в деревья поведения (Condition)
- сохранение и использование файла описания навыков, используемых в BT (json)
- тестирование форм-билдера - универсального web-модуля ввода параметров и зависимостей пользователем
3) разработка навыка BT для записи демонстрации rosbag во время симуляции действий робота
4) модуль конвертации файлов rosbag в формат обучения lerobot
5) разработка пользовательского навыка BT (клиента) движения робота в заданную точку (move to pose)
- для cartesian-контроллера
- для MoveIt
6) рефакторинг:
- перенос интерфейсного узла в пакет запуска деревьев поведения
- выделение навыков компьютерного зрения в отдельные пакеты (rbss_objectdetection, rbss_poseestimation)
## Перевод навыков компьютерного зрения на работу через интерфейсную ноду (Object Detection, Pose Estimation)
При разработке интерфейсной ноды, которая позволила упростить обмен данными между испольнительной системой деревьев поведения и конкретными навыками, появилась потребность в адаптации навыков компьютерного зрения для работы с новым API.
В имплементации навыка Object Detection для YoloV8 теперь необходимо все параметры для его работы сохранить в json-описании до его использования с деревом поведения, а зависимости (такие как наименование объекта распознавания, веса модели, имя топика получаемого изображения), задаваемые в узле дерева поведения, встроить в вышеуказанное json-описание. При выполнении дерева поведения для активации распознавания необходимо передать lifecycle-узлу навыка всё json-описание одним пакетом через интерфейсную ноду.
Схожим образом была настроена работа навыка Pose Estimation (методом DOPE).
## Тестирование и отладка интерфейсов веб-сервиса для создания деревьев поведения
Для того, чтобы полноценно разрабатывать алгоритмы поведения робота в различных сценариях использования, нам потребовалось создать механизм создания, редактирования и запуска деревьев поведения, основанный на управляющей программе веб-сервиса. Веб-сервис, в свою очередь, должен взаимодействовать с пакетами ROS2, реализующими конкретные навыки управления роботом (в режиме симуляции, а также в реальной обстановке) для их запуска и получения обратной связи.
Для этого мы разработали стандарт описания пользовательских навыков в виде json.
[Пример описания навыка](https://gitlab.com/robossembler/robossembler-ros2/-/blob/main/rbss_movetopose/rbs_package.json?ref_type=heads):
```json
{
"SkillPackage": { "name": "Robossembler", "version": "1.0", "format": "1" },
"Module": { "name": "MoveToPose", "description": "Move to Pose skill with cartesian controllers", "node_name": "mtp_cartesian" },
"Launch": { "package": "rbss_movetopose", "executable": "mtp_cartesian.py" },
"BTAction": [
{
"name": "move",
"type": "action",
"param": [
{
"type": "move_to_pose",
"dependency": { "robot_name": "arm0",
"pose": { "position": {"x":0.0, "y":0.0, "z":0.0}, "orientation": {"x":0.0, "y":0.0, "z":0.0, "w": 1.0} } }
}
]
}
],
"Settings": {
"result": "{\n  \"params\": \\${ITEM:Array<ITEM>:[]}\n}",
"context": "type ITEM = {\n\"name\": \\${NAME:string:default},\n\"value\": \\${VALUE:string:default}\n};",
"form": [
"{\"name\":\"ITEM\",\"type\":\"Array\",\"id\":\"767a59ff-3d25-4c34-84a2-fa5baf074394\"}"
],
"output": {
"params": [
{
"name": "server_name",
"value": "cartesian_move_to_pose"
},
{
"name": "end_effector_velocity",
"value": "1.0"
},
{
"name": "end_effector_acceleration",
"value": "1.0"
}
]
},
"type": "formBuilder"
}
}
```
### добавление новых деталей в проект
### разработка новой схемы описания зависимостей, основанной на применении топиков ROS2
### использование цифровых двойников (Digital Twins)
### получение интерфейсов ROS2: GetInterfaces
### переход на новую версию деревьев поведения (с 3 на 4)
### добавление условий в деревья поведения (Condition)
Условия в деревьях поведения (Condition) отличаются от действий лишь тем, что возвращают, по итогу, булево значение - true / false.
Для наших целей мы установили, что такие функции должны быть достаточно быстрыми и выполняться в синхронном режиме вопрос-ответ. Поэтому для их реализации в интерфейсной ноде мы их выделили в отдельный класс RbsCondition, а их обработчик - в виде сервиса. По итогам отладки пришли к выводу, что такой подход упрощает проектирование навыков и уменьшает накладные расходы при реализации нашего API.
### сохранение и использование файла описания навыков, используемых в BT (json)
### тестирование форм-билдера - универсального web-модуля ввода параметров и зависимостей пользователем
## Разработка навыка BT для записи демонстрации rosbag во время симуляции действий робота
Положение робота определяется положением его составляющих частей, что в ROS2 описывается сообщениями типа "sensor_msgs/msg/JointState". Если к ним добавить изображения с камер, имеющихся в сцене с роботом, то мы получим полное представление о том, что происходило при прохождении заданного деревом поведения сценария. Поэтому решено было в целях демонстрации, а также в целях получения датасетов для обучения робота создать навык, позволяющий включать и выключать запись таких данных в формат rosbag.
Пример реализации такого навыка в дереве поведения:
```xml
<root BTCPP_format="4">
<BehaviorTree ID="Main">
<Sequence>
<Action ID="RbsAction" do="RecordingDemo" command="rdConfigure" sid="a"></Action>
<Action ID="RbsAction" do="MoveToPose" command="move" sid="c"></Action>
<Action ID="RbsAction" do="RecordingDemo" command="rdStop" sid="a"></Action>
</Sequence>
</BehaviorTree>
<TreeNodesModel>
<Action ID="RbsAction">
<input_port name="do"/>
<input_port name="command"/>
<input_port name="sid"/>
</Action>
</TreeNodesModel>
</root>
```
* skills.json (файл описания навыков, используемых в дереве поведения)
```json
{
"skills": [
{
"sid": "a",
"SkillPackage": { "name": "Robossembler", "version": "1.0", "format": "1" },
"Module": { "name": "RecordingDemo", "description": "Recording a demo via RosBag", "node_name": "lc_record_demo" },
"Launch": { "package": "rbs_utils", "executable": "recording_demo_via_rosbag.py" },
"BTAction": [
{
"name": "rdConfigure",
"type_action": "action",
"type": "run",
"param": [],
"result":[]
},
{ "name": "rdStop", "type_action": "action", "type": "stop", "param": [], "result": [] }
],
"Settings": [
{ "name": "output_path", "value": "rbs_testbag" }
]
},
{
"sid": "c",
"SkillPackage": { "name": "Robossembler", "version": "1.0", "format": "1" },
"Module": { "name": "MoveToPose", "description": "Move to Pose skill with cartesian controllers", "node_name": "mtp_cartesian" },
"Launch": { "package": "rbss_movetopose", "executable": "mtp_cartesian.py" },
"BTAction": [
{
"name": "move",
"type_action": "action",
"type": "action",
"param": [
{
"type": "move_to_pose",
"dependency": { "robot_name": "arm0",
"pose": { "position": {"x":0.1, "y":0.1, "z":0.9}, "orientation": {"x":0.55, "y":0.0, "z":0.45, "w": 1.0} } }
}
]
}
],
"Settings": [
{ "name": "server_name", "value": "cartesian_move_to_pose" },
{ "name": "end_effector_velocity", "value": 1.0 },
{ "name": "end_effector_acceleration", "value": 1.0 }
]
}
]
}
```
В процессе отладки навыка выяснилось, что в используемой нами версии ROS2 - Humble в питоновских нодах не работает функция writer.close(), закрывающая текущий сеанс записи. Выяснили, что этот bug исправлен в последующих релизах (в частности, в Jazzy). Пока вышли из ситуации перезапуском ноды навыка.
## модуль конвертации файлов rosbag в формат обучения lerobot
С целью облегчить внедрение роботов нами принято решение создать подход, использующий имитационное обучение и обучение с покреплением, который можно применять даже не имея реального робота, а в имитационной среде. Для этого мы воспользовались актуальным на данный момент, довольно широко поддерживаемым решением [lerobot](https://github.com/huggingface/lerobot), которое предполагает использование стандарта создания и публикации датасетов для этих целей.
Нами была разработана, протестирована и добавлена конвертации исходного формата "rbs_ros2bag" в lerobot-датасет - см. `lerobot/common/datasets/push_dataset_to_hub/rbs_ros2bag_format.py`.
Пример команды:
```bash
python push_dataset_to_hub.py \
--raw-dir /home/user/rbs_bag_to_lerobot \
--local-dir data/lerobot/rbs_tst_episode \
--repo-id lerobot/rbs_tst_episode \
--raw-format rbs_ros2bag \
--push-to-hub 0 \
--video 0 \
--force-override 1
```
## разработка пользовательского навыка BT (клиента) движения робота в заданную точку (move to pose)
- для cartesian-контроллера
- для MoveIt
## Рефакторинг.
### Перенос интерфейсного узла в пакет запуска деревьев поведения
Интерфейсная нода выполняет 3 основных задачи:
- парсинг зависимостей дерева поведения при старте интерфейсного узла для выделения списка навыков и их запуск,
- передача параметров и зависимостей при выполнении узлов дерева поведения нужным навыкам,
- синхронизация выполнения узлов дерева поведения исполнительной системой behaviortree_cpp и выполнением этих операций через пользовательские навыки в ROS2.
Остановимся подробнее на описании этих функций в интерфейсной ноде.
При создании дерева поведения в редакторе веб-сервиса (bt.xml) каждому узлу присваивается уникальный идентификатор (sid), который позволяет связать эти узлы при выполнении с их описанием (включающим параметры, вводимые пользователем, статичные настройки навыков и зависимости, указывающие на объекты и артефакты среды): skills.json.
Эти данные передаются в качестве параметров при старте интерфейсной ноды (в виде пути к вышеуказанным файлам).
Пример команды запуска интерфейсной ноды:
```bash
ros2 launch rbs_bt_executor interface.launch.py bt_path:=/path/to/bt&skills
```
Модуль запуска также парсит файл skills.json, составляя список пользовательских навыков и передавая его для запуска в ROS2.
Интерфейсная нода при создании создаёт сервер действий (ActionServer) для выполнения узлов действий (RbsAction) дерева поведения и сервис для проверки условий (RbsCondition).
Затем возможно выполнение команды запуска дерева поведения:
```bash
ros2 launch rbs_bt_executor rbs_bt_web.launch.py bt_path:=/path/to/bt&skills
```
Рассмотрим стандартный алгоритм исполнения одного узла дерева поведения на примере RbsAction (т.е. действия).
Вначале в интерфейсную ноду через обратный вызов сервера действий приходит запрос с целью, в которой указан конкретный идентификатор (sid) узла BT, наименование запрашиваемой у навыка команды и её тип. Интерфейсная нода находит в описании параметров дерева нужный блок с этим sid, записывает этот блок в параметр ноды навыка с заранее предопределённым именем (имя ноды навыка + суффикс "_cfg"). В случае с lifecycle-нодой навыка производится процедура конфигурирования и активации этой ноды, либо обратная процедура деактивации и очистки состояния.
Нода навыка, получив нужный параметр, выполняет заданное действие, а интерфейсная нода ожидает выполнения для передачи ответа в исполняющую систему BT.
Аналогично происходит процесс выполнения проверки условия RbsCondition, с той лишь разницей, что происходят обратные вызовы сервиса интерфейсной ноды.
Нужно обратить внимание, что параметр, передаваемый навыку, представляет собой json-строку, в которой передаются все установки и зависимости, необходимые для выполнения запрашиваемого действия или проверки заданного условия.
Таким образом, схема построения пользовательского навыка выглядит следующим образом:
- для lifecycle-узла: обработка вызовов конфигурирования, активации, деактивации и очистки состояния с использованием данных, передаваемых через предопределённый параметр,
- для обычного узла: обработка обратного вызова установки предопределённого параметра, соответственно, с выполнением операций, определяемых этим параметром.
### выделение навыков компьютерного зрения в отдельные пакеты (rbss_objectdetection, rbss_poseestimation)
## Имплементация средств контроля используемых ресурсов
Весьма значительное время и ресурсы компьтерного оборудования используются в процессе подготовки и использования нейросетевых моделей. Мы решили для целей оптимизации и профилирования этих процессов внедрить оценку на основе пакета [TensorBoard](https://www.tensorflow.org/tensorboard?hl=ru) для сбора данных и их представления в веб-сервисе.
При отладке этого модуля выявили некоторые особенности, влияющие на работоспособность данного пакета.
Сбор данных о потреблении ресурсов компьютера следует производить отдельно от сбора данных непосредственно об метриках обучения.
Необходимо ограничить запуск шагов обучения 5-ю эпохами (первая - пропускается, вторая - сбор данных производится, но результаты отбрасываются, три последующих - происходит накопление и сохранение данных). При увеличении количества шагов, при которых накапливается информация о производительности, рост затрат на этот процесс не позволяет ему завершиться и, чаще всего, приводит к сбоям в работе и зависанию компьютера.

142
docs/software/usecases.md Normal file
View file

@ -0,0 +1,142 @@
---
title: Сценарии использования
---
Фреймворк может найти достаточно широкое распространение. Несмотря на то, что основной задачей фреймворка являлась автоматизация процесса разработки программ роботизированной сборки, программное обеспечение может применяться также и для других задач.
В частности,
- веб-сервис с модулями генерации датасетов и интерфейсом создания новых навыков может применяться для запуска любых других поддерживающих API навыков, не связанным напрямую с задачей сборки изделий;
- модуль исполнения программ ROS 2 включает в себя довольно гибкую систему управления исполнением с помощью деревьев поведения и может быть применён к любым задачам планирования, требующих модульности и реактивности;
- для студентов, исследователей и инженеров фреймворк может упростить разработку и отладку программного обеспечения за счёт использования функций высокого уровня абстракции при решении задач манипулирования.
Ниже рассмотрены сценарии использования, которые были разработаны командой Robossembler.
## Обучение с подкреплением - rbs_gym
Модуль **rbs_gym** предназначен для реализации среды обучения с подкреплением для роботов-манипуляторов. Он активно использует возможности открытой библиотеки Робосборщик, упрощая управление сценой и настройку среды.
Основные компоненты модуля обеспечивают:
- получение пространства наблюдения,
- передачу управляющих сигналов агенту,
- рандомизацию параметров среды,
- настройку задач, определяющих награды и условия для агента.
### Пространства наблюдения и действий
**Пространство наблюдения** включает:
- скорость на эффекторе робота,
- положения суставов робота,
- изображения с камеры (глубина, цвет или облака точек).
**Пространство действий** позволяет:
- отправлять управляющие сигналы в виде усилий или скоростей в пространстве задач робота,
- управлять положением захватного устройства,
- задавать усилия в конфигурационном пространстве робота.
### Гибкая настройка агентов
В составе модуля реализован класс **ExperimentManager**, который управляет предварительной настройкой агентов обучения. Конфигурации описываются в формате YAML. Пример гиперпараметров для алгоритма TD3 доступен [здесь](https://git.robossembler.org/nodes/seed.robossembler.org/rad:z46gtVRpXaXrGQM7Fxiqu7pLy7kip/tree/env_manager/rbs_gym/hyperparams/td3.yml).
Поддерживаются следующие алгоритмы обучения:
- [TD3](https://arxiv.org/abs/1802.09477)
- [SAC](https://arxiv.org/abs/1801.01290)
- [TQC](https://arxiv.org/abs/2005.04269)
### Общая структура и примеры
Общий вид среды обучения для задачи достиженая точки пространства представлен на изображении:
![rbs_gym_env_view](img/env.jpg)
_Общий вид среды для задачи "достижения точки" в **rbs_gym**_
На рисунке точка отмечена зеленым шаром. Каждую эпоху обучения выбираются разные позиции для робота в конфигурационном пространстве, а также позиция объекта выбирается случайным образом.
Диаграмма классов на примере задачи Reach детализирует архитектуру модуля:
![rbs_gym_class_diagram](img/rbs_gym_class_diagram.png)
*Диаграмма классов для задачи Reach*
Агент использует усилия в пространстве задач для достижения до точки.
**Управляющие сигналы**:
$$
\bm{W} = \begin{bmatrix} f_x & f_y & f_z & 0 & 0 & 0 \end{bmatrix}^T
$$
где $f$ — компоненты силы.
**Пространство наблюдения**:
$$
\bm{O} = \begin{bmatrix} \bm{p}_e & \bm{p}_o & \bm{v}_e \end{bmatrix}^T
$$
где:
- $\bm{p}_e = [x, y, z]^T$ — положение эффектора робота,
- $\bm{p}_o = [x, y, z]^T$ — положение цели,
- $\bm{v}_e$ — пространственный вектор скорости эффектора.
**Функция наград**:
1. **За уменьшение дистанции до цели**:
$$
R_d = \sum_{t=0}^{T-1} \Delta D_t \cdot 10
$$
где $T$ — число шагов, $D_t$ — расстояние до цели, $\Delta D_t = D_{t} - D_{t-1}$.
2. **За коллизии**:
$$
R_c = \sum_{t=0}^{T-1} \begin{cases}
-10, & \text{если } q_t \in C_o, \\
0, & \text{иначе}
\end{cases}
$$
где $C_o$ — пространство коллизий.
3. **Штраф за медленное выполнение задачи**:
$$
R_q = \sum_{t=0}^{T-1} -0.01
$$
4. **Бонус за достижение цели**:
$$
R_s = \begin{cases}
100, & \text{если } D_t < 0.05, \\
0, & \text{иначе.}
\end{cases}
$$
**Результирующая награда**:
$$
R = R_c + R_d + R_q + R_s
$$
Агент считается обученным, если $R = 100 \pm 10$ за эпизод.
### Тестирование и результаты
На графике представлены результаты обучения:
![train_metrics](img/train_metrics-1.jpg)
*Графики обучения. Допустимая область (100 ± 10) показывает диапазон, при котором агент считается обученным.*
### Самостоятельный запуск обучения
Для самостоятельно запуска этого примера следуйте [инструкции](https://gitlab.com/solid-sinusoid/env_manager/-/blob/main/docs/getting_started/getting_started.ru.md).
## Имитационное обучение с помощью деревьев поведения
Описанный выше модуль `rbs_gym` также можно использовать для более специфических сценариев применения - в частности, для имитационного обучения, где обучение с подкреплением дополняется демонстрациями, полученными в симуляторе или с помощью устройств телеуправления роботом. Ниже приведена диаграмма ориентировочной реализации такого сценария, на которой отражены основные модули системы и их взаимосвязи.
![robossembler imitation learning](img/rbs_imitation_learning_usecase.jpg)
На диаграмме показано каким образом программные модули фреймворка `bt_executor`, `scene_builder`, `rbs_runtime`, `env_manager` интегрируются со сторонними библиотеками - в частности, с библиотекой [lerobot](https://github.com/huggingface/lerobot), из которой используются модули для формирования `Policy`, обучения и конвертации датасета. На диаграмме также выделены примитивы дерева поведения, среди которых можно отметить RecordEpisode, осуществляющий запись демонстраций в runtime в цикле.

5
sidebars.js
View file

@ -84,6 +84,11 @@ module.exports = {
id: 'software/webservice',
label: 'Веб-интерфейс',
},
{
type: 'doc',
id: 'software/usecases',
label: 'Сценарии использования',
},
],
},
/* {