From 85eec1b7d7baa0ad09ade35bd3c89e2fa1524190 Mon Sep 17 00:00:00 2001 From: Bill Finger Date: Fri, 15 Nov 2024 23:25:02 +0300 Subject: [PATCH] added doc on how to use framework with your robot or how to add new robot --- doc/en/add_new_robot.md | 106 +++++++++++++++++ doc/en/index.md | 18 +++ doc/index.md | 20 ---- doc/ru/add_new_robot.md | 108 ++++++++++++++++++ doc/ru/index.md | 18 +++ .../rbs_runtime/launch/runtime.launch.py | 41 +++++-- rbs_bringup/launch/rbs_bringup.launch.py | 2 + rbs_bringup/launch/rbs_robot.launch.py | 13 ++- 8 files changed, 292 insertions(+), 34 deletions(-) create mode 100644 doc/en/add_new_robot.md create mode 100644 doc/en/index.md delete mode 100644 doc/index.md create mode 100644 doc/ru/add_new_robot.md create mode 100644 doc/ru/index.md diff --git a/doc/en/add_new_robot.md b/doc/en/add_new_robot.md new file mode 100644 index 0000000..8b069ce --- /dev/null +++ b/doc/en/add_new_robot.md @@ -0,0 +1,106 @@ +# Instructions for Adding a New Robot to the Robossembler ROS 2 Framework + +First, you need to download the robot package containing `xacro` or `urdf` files, as well as geometry files in formats such as `.stl`, `.dae`, `.obj`, etc. + +Before starting, it is important to understand the basics of the [xacro](https://github.com/ros/xacro/wiki) format. This format allows you to reuse existing fragments of a robot's URDF description, making it easier to create and modify descriptions. + +### Steps for Adding a New Robot: + +1. **Install the Robot Package** + After installing the robot package, create a file named `xacro_args.yaml` in the `{description_package}/config/` directory. This file should specify the arguments needed to convert the `xacro` file into a `urdf`. + +2. **Configure the Launch File** + Edit the file [`rbs_bringup.launch.py`](../../rbs_bringup/launch/rbs_bringup.launch.py) to define the parameters required to launch the robot. + + Example of a standard implementation: + ```python + main_script = IncludeLaunchDescription( + PythonLaunchDescriptionSource( + [ + PathJoinSubstitution( + [FindPackageShare("rbs_runtime"), "launch", "runtime.launch.py"] + ) + ] + ), + launch_arguments={ + "with_gripper": "true", + "gripper_name": "rbs_gripper", + "robot_type": "rbs_arm", + "description_package": "rbs_arm", + "description_file": "rbs_arm_modular.xacro", + "robot_name": "rbs_arm", + "use_moveit": "false", + "moveit_config_package": "rbs_arm", + "moveit_config_file": "rbs_arm.srdf.xacro", + "use_sim_time": "true", + "hardware": "gazebo", + "use_controllers": "true", + "scene_config_file": "", + "base_link_name": "base_link", + "ee_link_name": "gripper_grasp_point", + }.items(), + ) + ``` + This configuration launches another file with specific arguments. Below is a description of each argument to help you decide whether it is needed. + +### Parameter Descriptions: + +- **`with_gripper`** + Indicates whether the robot has a gripper. If set to `true`, the `gripper_controller` will be configured and launched. + +- **`gripper_name`** + Used as a keyword to identify links and joints related to the gripper. It is also applied in `xacro` arguments. + +- **`robot_type`** + Specifies a group of robots of the same type, allowing you to semantically group robots with different names but similar designs. + +- **`description_package`** + The package containing the robot's URDF description. This parameter is mandatory and is used to locate the URDF file and controller configuration files. + +- **`description_file`** + The name of the description file, which should be located in `{description_package}/urdf/`. + +- **`robot_name`** + A unique name for the robot to distinguish it from others in the scene. + +- **`use_moveit`** + Indicates whether [MoveIt 2](https://moveit.picknik.ai/humble/index.html) should be used. While it is not required for basic movements, it is recommended when working with obstacles. + +- **`moveit_config_package`** + The name of the MoveIt 2 configuration package generated based on the `{description_package}`. This parameter is required if you plan to use MoveIt 2. + +- **`moveit_config_file`** + The MoveIt 2 launch file located in `{moveit_config_package}/launch/`. + +- **`use_sim_time`** + A mandatory parameter for simulation. It ensures that time is synchronized with the simulator. + +- **`hardware`** + Specifies the interface to be used for controlling the robot. For example, `gazebo`. This parameter is primarily used in `xacro` files. + +- **`use_controllers`** + Indicates whether to use standard controllers. If set to `false`, the robot will not be able to move. This parameter controls the execution of the [control.launch.py](../../rbs_bringup/launch/control.launch.py) file. You can write a custom implementation instead of using this flag. + +- **`scene_config_file`** + A YAML file that defines the scene configuration. A default example is available [here](../../env_manager/rbs_runtime/config/default-scene-config.yaml). Ensure that the degrees of freedom of your robot match the configuration file. + +- **`base_link_name`** + The name of the robot's base link, which defines where the robot begins. This parameter is important for skill configuration. Review your robot's URDF to set this correctly. + +- **`ee_link_name`** + The name of the end-effector link, which defines where the robot ends. This parameter is also important for skill configuration and should be set based on the URDF. + +- **`control_space`** + Specifies the space in which the robot will be controlled. + Possible values: + - `task` — control in task space (e.g., using positions and orientations in the workspace). + - `joint` — control in joint space (e.g., using angular values for each robot joint). + Default value: `task`. + +- **`control_strategy`** + Specifies the control strategy for the robot. + Possible values: + - `position` — position control, where desired positions are set for joints or the workspace target point. + - `velocity` — velocity control, where desired movement speeds are set. + - `effort` — effort control, where torques or forces applied to the joints are specified. + Default value: `position`. diff --git a/doc/en/index.md b/doc/en/index.md new file mode 100644 index 0000000..597fe05 --- /dev/null +++ b/doc/en/index.md @@ -0,0 +1,18 @@ +Robossembler ROS 2 Packages + +- **`env_manager`** - virtual environment manager: + - **`env_manager`** - manages objects in Gazebo simulation scenes. + - **`env_manager_interfaces`** - ROS 2 interfaces for configuring, loading, activating, and unloading environments. + - **`rbs_gym`** - reinforcement learning module: training management, simulation environment creation, action and observation space handling, utilities. + - **`rbs_runtime`** - runs the main runtime using `env_manager`. + +- **`rbs_bringup`** - launch scenarios: simulation, real robot, multi-robot configurations. +- **`rbs_bt_executor`** - executes behavior trees with Behavior Tree CPP v4. +- **`rbs_interface`** - interface linking behavior trees with skill servers (recommended to merge with `rbs_bt_executor`). +- **`rbs_perception`** - machine vision module with multiple implementations. +- **`rbs_simulation`** - simulation models (recommended to merge with `env_manager` or `rbs_gym`). +- **`rbs_skill_interfaces`** - common interfaces for interacting with skill servers and behavior trees. +- **`rbs_skill_servers`** - packages for skill servers (recommended to replace with individual packages for each server). +- **`rbs_task_planner`** - task planner based on PDDL. +- **`rbs_utils`** - utilities for working with configurations containing grasp positions. +- **`rbss_objectdetection`** - skill server for object detection using YOLOv8. diff --git a/doc/index.md b/doc/index.md deleted file mode 100644 index b8282f3..0000000 --- a/doc/index.md +++ /dev/null @@ -1,20 +0,0 @@ -Robossembler ROS 2 Packages - -- `env_manager` - менеджер переключения виртуальных сред - - `env_interface` - базовый класс для создания конкретной среды на базе ROS 2 LifeCycle Node - - `env_manager` - основной пакет менеджера переключения виртуальных сред - - `env_manager_interfaces` - интерфейсы ROS 2 для env_manager, описывают сообщения о состоянии среды, сервисы по конфигурации/загрузке/включению/выгрузке среды - - `gz_environment` - конкретный экземпляр `env_interface` для симулятора Gazebo - - `planning_scene_manager` - управление сценой планирования для MoveIt (среда для MoveIt) - - `rbs_gym` - модуль обучения с подреплением: управление процесом обучения, формирование сред симуляции, управление пространствами действий(actions) и восприятия(observation), управление задачами, утилиты - -- `rbs_bringup` - пакет для запуска разных launch сценариев: симуляция, реальный робот, разные конфигурации оборудования (multi-robot) -- `rbs_bt_executor` - модуль запуска деревьев поведения на Behavior Tree CPP v4 -- `rbs_interface` - пакет для связывания деревьев со скилл-серверами (объединить с - `rbs_bt_executor`) -- `rbs_perception` - модуль машинного восприятия, где реализованы разные версии -- `rbs_simulation` - модели для симуляции (к удалить или объединить с env_manager/rbs_gym) -- `rbs_skill_interfaces` - общеиспользуемые (common) интерфейсы для взаимодействия с Серверами Навыков и Деревом поведения (специфичные интерфейсы размещаются в пакетах Серверов Навыков) -- `rbs_skill_servers` - пакеты Серверов Навыков (упразднить, для каждого Сервера Навыков свой пакет) -- `rbs_task_planner` - планировщик задач на базе PDDL -- `rbs_utils` - работа с конфигом, содержащим позиции захвата для деталей -- `rbss_objectdetection` - Сервер Навыка обнаружения объектов с помощью YOLOv8 \ No newline at end of file diff --git a/doc/ru/add_new_robot.md b/doc/ru/add_new_robot.md new file mode 100644 index 0000000..f9cebd2 --- /dev/null +++ b/doc/ru/add_new_robot.md @@ -0,0 +1,108 @@ +# Инструкция по добавлению нового робота в фреймворк Robossembler ROS 2 + +Прежде всего необходимо скачать пакет робота, содержащий файлы `xacro` или `urdf`, а также файлы геометрии робота в формате `.stl`, `.dae`, `.obj` и других. + +Перед началом работы важно ознакомиться с основными аспектами формата [xacro](https://github.com/ros/xacro/wiki). Этот формат позволяет переиспользовать существующие фрагменты URDF-описания робота, что упрощает создание и модификацию описания. + +### Шаги по добавлению нового робота: + +1. **Установка пакета робота** + После установки пакета робота создайте файл `xacro_args.yaml` в директории `{description_package}/config/`. В этом файле необходимо указать аргументы для преобразования xacro-файла в URDF. + +2. **Настройка запуска** + Отредактируйте файл [`rbs_bringup.launch.py`](../../rbs_bringup/launch/rbs_bringup.launch.py), указав параметры для запуска робота. + + Пример стандартной реализации: + ```python + main_script = IncludeLaunchDescription( + PythonLaunchDescriptionSource( + [ + PathJoinSubstitution( + [FindPackageShare("rbs_runtime"), "launch", "runtime.launch.py"] + ) + ] + ), + launch_arguments={ + "with_gripper": "true", + "gripper_name": "rbs_gripper", + "robot_type": "rbs_arm", + "description_package": "rbs_arm", + "description_file": "rbs_arm_modular.xacro", + "robot_name": "rbs_arm", + "use_moveit": "false", + "moveit_config_package": "rbs_arm", + "moveit_config_file": "rbs_arm.srdf.xacro", + "use_sim_time": "true", + "hardware": "gazebo", + "use_controllers": "true", + "scene_config_file": "", + "base_link_name": "base_link", + "ee_link_name": "gripper_grasp_point", + "control_space": "task", + "control_strategy": "position", + }.items(), + ) + ``` + Здесь выполняется запуск другого launch-файла с указанными аргументами. Ниже приводится описание каждого аргумента. + +### Описание параметров: + +- **`with_gripper`** + Указывает, есть ли на роботе захватное устройство (гриппер). Если значение `true`, будет настроен и запущен `gripper_controller`. + +- **`gripper_name`** + Используется как ключевое слово для указания линков и джоинтов, относящихся к грипперу. Также применяется в xacro-аргументах. + +- **`robot_type`** + Обозначает группу роботов одного типа. Например, все роботы с разными именами, но одинаковой конструкцией. + +- **`description_package`** + Пакет, содержащий описание URDF робота. Обязательный параметр. Используется для определения пути к файлу описания и конфигурации контроллеров. + +- **`description_file`** + Имя файла описания, который должен находиться в `{description_package}/urdf/`. + +- **`robot_name`** + Уникальное имя робота, которое позволяет отличить его от других в сцене. + +- **`use_moveit`** + Указывает, нужно ли использовать [MoveIt 2](https://moveit.picknik.ai/humble/index.html). Для базовых перемещений MoveIt 2 не обязателен, но для работы с препятствиями рекомендуется его включить. + +- **`moveit_config_package`** + Имя пакета конфигурации MoveIt 2, который генерируется на основе `{description_package}`. Обязательный параметр, если используется MoveIt 2. + +- **`moveit_config_file`** + Файл запуска MoveIt 2, находящийся в `{moveit_config_package}/launch/`. + +- **`use_sim_time`** + Обязательный параметр при работе в симуляции. Обеспечивает синхронизацию времени с симулятором. + +- **`hardware`** + Указывает интерфейс для управления роботом. Например, `gazebo`. Используется в основном в xacro-файлах. + +- **`use_controllers`** + Указывает, нужно ли использовать стандартные контроллеры. Если значение `false`, робот не сможет двигаться. Влияет на запуск файла [control.launch.py](../../rbs_bringup/launch/control.launch.py). + +- **`scene_config_file`** + Файл конфигурации сцены в формате YAML. Пример можно найти [здесь](../../env_manager/rbs_runtime/config/default-scene-config.yaml). Обратите внимание на соответствие количества степеней свободы робота. + +- **`base_link_name`** + Имя базового линка, от которого начинается робот. Важно для настройки навыков. Рекомендуется свериться с URDF. + +- **`ee_link_name`** + Имя конечного линка (энд-эффектора), где заканчивается робот. Этот параметр также настраивается на основе URDF. + +- **`control_space`** + Указывает, в каком пространстве робот будет управляться. + Возможные значения: + - `task` — управление в пространстве задач (например, с использованием позиций и ориентации в рабочем пространстве). + - `joint` — управление в пространстве суставов (например, с использованием угловых значений для каждого сустава робота). + Значение по умолчанию: `task`. + +- **`control_strategy`** + Указывает стратегию управления роботом. + Возможные значения: + - `position` — управление положением, когда задаются желаемые позиции для суставов или рабочей точки. + - `velocity` — управление скоростью, когда задаются желаемые скорости движения. + - `effort` — управление усилием, когда задаются моменты или силы, прикладываемые к суставам. + Значение по умолчанию: `position`. diff --git a/doc/ru/index.md b/doc/ru/index.md new file mode 100644 index 0000000..7e73a5e --- /dev/null +++ b/doc/ru/index.md @@ -0,0 +1,18 @@ +# Robossembler ROS 2 Packages + +- **`env_manager`** - менеджер виртуальных сред: + - **`env_manager`** - управление объектами в сцене симуляции Gazebo. + - **`env_manager_interfaces`** - ROS 2 интерфейсы для конфигурации, загрузки, активации и выгрузки сред. + - **`rbs_gym`** - модуль обучения с подкреплением: управление обучением, создание симуляционных сред, управление пространствами действий и наблюдений, утилиты. + - **`rbs_runtime`** - запуск основного рантайма с использованием `env_manager`. + +- **`rbs_bringup`** - запуск сценариев: симуляция, реальный робот, многороботные конфигурации. +- **`rbs_bt_executor`** - выполнение деревьев поведения с Behavior Tree CPP v4. +- **`rbs_interface`** - интерфейс для связи деревьев поведения со скилл-серверами (рекомендуется объединить с `rbs_bt_executor`). +- **`rbs_perception`** - модуль машинного зрения с различными версиями. +- **`rbs_simulation`** - модели для симуляции (рекомендуется объединить с `env_manager` или `rbs_gym`). +- **`rbs_skill_interfaces`** - общие интерфейсы для взаимодействия с скилл-серверами и деревьями поведения. +- **`rbs_skill_servers`** - пакеты для скилл-серверов (рекомендуется заменить на индивидуальные пакеты для каждого сервера). +- **`rbs_task_planner`** - планировщик задач на основе PDDL. +- **`rbs_utils`** - утилиты для работы с конфигурациями, содержащими позиции захвата. +- **`rbss_objectdetection`** - скилл-сервер для обнаружения объектов с YOLOv8. diff --git a/env_manager/rbs_runtime/launch/runtime.launch.py b/env_manager/rbs_runtime/launch/runtime.launch.py index f142865..0ff5ed9 100644 --- a/env_manager/rbs_runtime/launch/runtime.launch.py +++ b/env_manager/rbs_runtime/launch/runtime.launch.py @@ -38,12 +38,17 @@ def launch_setup(context, *args, **kwargs): ee_link_name = LaunchConfiguration("ee_link_name").perform(context) base_link_name = LaunchConfiguration("base_link_name").perform(context) + control_space = LaunchConfiguration("control_space").perform(context) + control_strategy = LaunchConfiguration("control_strategy").perform(context) + if not scene_config_file == "": config_file = {"config_file": scene_config_file} else: config_file = {} - description_package_abs_path = get_package_share_directory(description_package.perform(context)) + description_package_abs_path = get_package_share_directory( + description_package.perform(context) + ) simulation_controllers = os.path.join( description_package_abs_path, "config", "controllers.yaml" @@ -91,9 +96,11 @@ def launch_setup(context, *args, **kwargs): robot_description_content = robot_description_doc.toprettyxml(indent=" ") robot_description = {"robot_description": robot_description_content} - + # Parse robot and configure controller's file for ControllerManager - robot = URDF_parser.load_string(robot_description_content, ee_link_name="gripper_grasp_point") + robot = URDF_parser.load_string( + robot_description_content, ee_link_name="gripper_grasp_point" + ) ControllerManager.save_to_yaml( robot, description_package_abs_path, "controllers.yaml" ) @@ -122,7 +129,9 @@ def launch_setup(context, *args, **kwargs): "use_controllers": "true", "robot_description": robot_description_content, "base_link_name": base_link_name, - "ee_link_name": ee_link_name + "ee_link_name": ee_link_name, + "control_space": control_space, + "control_strategy": control_strategy, }.items(), ) @@ -155,14 +164,6 @@ def generate_launch_description(): default_value="rbs_arm", ) ) - # General arguments - # declared_arguments.append( - # DeclareLaunchArgument( - # "controllers_file", - # default_value="controllers.yaml", - # description="YAML file with the controllers configuration.", - # ) - # ) declared_arguments.append( DeclareLaunchArgument( "description_package", @@ -267,6 +268,22 @@ def generate_launch_description(): description="Base link name if robot arm", ) ) + declared_arguments.append( + DeclareLaunchArgument( + "control_space", + default_value="task", + choices=["task", "joint"], + description="Specify the control space for the robot (e.g., task space).", + ) + ) + declared_arguments.append( + DeclareLaunchArgument( + "control_strategy", + default_value="position", + choices=["position", "velocity", "effort"], + description="Specify the control strategy (e.g., position control).", + ) + ) return LaunchDescription( declared_arguments + [OpaqueFunction(function=launch_setup)] diff --git a/rbs_bringup/launch/rbs_bringup.launch.py b/rbs_bringup/launch/rbs_bringup.launch.py index 63253b4..06c1047 100644 --- a/rbs_bringup/launch/rbs_bringup.launch.py +++ b/rbs_bringup/launch/rbs_bringup.launch.py @@ -35,6 +35,8 @@ def launch_setup(context, *args, **kwargs): "scene_config_file": "", "base_link_name": "base_link", "ee_link_name": "gripper_grasp_point", + "control_space": "task", + "control_strategy": "position", }.items(), ) diff --git a/rbs_bringup/launch/rbs_robot.launch.py b/rbs_bringup/launch/rbs_robot.launch.py index 2d42d35..adef203 100644 --- a/rbs_bringup/launch/rbs_robot.launch.py +++ b/rbs_bringup/launch/rbs_robot.launch.py @@ -225,7 +225,17 @@ def generate_launch_description(): DeclareLaunchArgument( "robot_type", description="Type of robot to launch, specified by name.", - choices=["rbs_arm", "ar4", "ur3", "ur3e", "ur5", "ur5e", "ur10", "ur10e", "ur16e"], + choices=[ + "rbs_arm", + "ar4", + "ur3", + "ur3e", + "ur5", + "ur5e", + "ur10", + "ur10e", + "ur16e", + ], default_value="rbs_arm", ) ) @@ -416,7 +426,6 @@ def generate_launch_description(): ) ) - return LaunchDescription( declared_arguments + [OpaqueFunction(function=launch_setup)] )