diff --git a/docs/robossembler-framework.md b/docs/robossembler-framework.md index b182f9e..69e52c5 100755 --- a/docs/robossembler-framework.md +++ b/docs/robossembler-framework.md @@ -67,4 +67,23 @@ title: Фреймворк Робосборщик - Не поддерживает ROS2 - Не поддерживает алгоритмы машинного обучения. -__AutoAssembly__. Разрабатывается командой робототехников из компании Arrival, известного производителя электромобилей с R&D командой из Санкт-Петербурга. Фреймворк предназначен для автоматической роботизированной сборки напрямую из CAD. В научной публикации с описанием фреймворка представлена практическая реализация на примере двух манипуляторов Universal Robotics. Исходный код проекта не публикуется; многие технические решения (спецификации, схемы данных, описания языков, тип базы данных) неизвестны. Более подробный обзор см. по [ссылке](/docs/papers/auto-assembly). \ No newline at end of file +__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 или более новой версии. \ No newline at end of file diff --git a/docs/software/img/rbs_imitation_learning_usecase.jpg b/docs/software/img/rbs_imitation_learning_usecase.jpg new file mode 100644 index 0000000..7e9fca2 Binary files /dev/null and b/docs/software/img/rbs_imitation_learning_usecase.jpg differ diff --git a/docs/software/ros2.md b/docs/software/ros2.md index 3255dcf..046a313 100644 --- a/docs/software/ros2.md +++ b/docs/software/ros2.md @@ -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**, которая анализирует предоставленные модели и генерирует данные, необходимые для корректного воспроизведения физики объекта в симуляторе. diff --git a/docs/software/ros2/installation.md b/docs/software/ros2/installation.md index 55d2446..2ffcd33 100644 --- a/docs/software/ros2/installation.md +++ b/docs/software/ros2/installation.md @@ -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 +``` + diff --git a/docs/software/shalenikol_commits_4th_milestone.md b/docs/software/shalenikol_commits_4th_milestone.md deleted file mode 100644 index 0b1e470..0000000 --- a/docs/software/shalenikol_commits_4th_milestone.md +++ /dev/null @@ -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:[]}\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 - - - - - - - - - - - - - - - - -``` -* 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-ю эпохами (первая - пропускается, вторая - сбор данных производится, но результаты отбрасываются, три последующих - происходит накопление и сохранение данных). При увеличении количества шагов, при которых накапливается информация о производительности, рост затрат на этот процесс не позволяет ему завершиться и, чаще всего, приводит к сбоям в работе и зависанию компьютера. - diff --git a/docs/software/usecases.md b/docs/software/usecases.md new file mode 100644 index 0000000..d0416a8 --- /dev/null +++ b/docs/software/usecases.md @@ -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 в цикле. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 6ca905b..cd3bebc 100644 --- a/sidebars.js +++ b/sidebars.js @@ -84,6 +84,11 @@ module.exports = { id: 'software/webservice', label: 'Веб-интерфейс', }, + { + type: 'doc', + id: 'software/usecases', + label: 'Сценарии использования', + }, ], }, /* {