added doc on how to use framework with your robot or how to add new robot

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`.

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.

doc/index.md

@@ -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

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`.

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.

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)]

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(),
     )
 

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)]
     )