update documentation and gitignore

2024-12-06 12:05:53 +03:00 · 2024-12-06 12:05:53 +03:00 · 1addd4f595
commit 1addd4f595
parent e8e6c052b0
9 changed files with 114 additions and 218 deletions
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
--- a/docs/en/add_new_robot.md
+++ b/docs/en/add_new_robot.md
@ -0,0 +1,110 @@
+# 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`.
+
+- **`interactive`**  
+  Specifies whether to run the `motion_control_handle` controller.  
+  Default value: `true`.  
--- a/docs/en/index.md
+++ b/docs/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.
--- a/docs/en/installation.md
+++ b/docs/en/installation.md
@ -0,0 +1,35 @@
+# Framework Installation Guide
+
+First, you need to install [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html). A minimal installation is recommended.
+
+As the second step, you need to build [`ros2_control`](https://github.com/ros-controls/ros2_control) from source using this [fork](https://github.com/solid-sinusoid/ros2_control/tree/gz-ros2-cartesian-controllers). Alternatively, you can use the [`vcstool`](https://github.com/dirk-thomas/vcstool) method, which is included with the basic ROS2 packages.
+
+If using `vcstool`, the required packages will be cloned into the same workspace as the framework. The command would look like this:
+```sh
+vcs import . < robossembler-ros2/repos/all-deps.repos
+```
+
+Additionally, you can run the following command to install all required Python libraries:
+```shell
+pip install -r robossembler-ros2/repos/requirements.txt
+```
+
+> [!IMPORTANT]  
+> Note that to run the above command, you need to install `git lfs` since the `requirements.txt` file includes the `rbs_assets_library` module, which contains large files but is installed as a Python module.
+
+Make sure to execute this command in the `{robossembler_ws}/src/` directory.
+
+For those who prefer a concise sequence of commands, here it is:
+```sh
+cd 
+mkdir -p robossembler-ros2/src && cd robossembler-ros2
+git clone https://seed.robossembler.org/z46gtVRpXaXrGQM7Fxiqu7pLy7kip.git robossembler-ros2
+# Or if you prefer Radicle:
+rad clone rad:z46gtVRpXaXrGQM7Fxiqu7pLy7kip
+cd src
+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
+colcon build --symlink-install
+```
--- a/docs/ru/add_new_robot.md
+++ b/docs/ru/add_new_robot.md
@ -0,0 +1,112 @@
+# Инструкция по добавлению нового робота в фреймворк 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`.
+
+- **`interactive`**  
+  Указывает, нужно ли запускать контроллер `motion_control_handle`.  
+  Значение по умолчанию: `true`.  
--- a/docs/ru/index.md
+++ b/docs/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.
--- a/docs/ru/installation.md
+++ b/docs/ru/installation.md
@ -0,0 +1,37 @@
+# Инструкция по установке фреймворка
+
+Первым делом необходимо установить [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html). Рекомендуется минимальная установка.
+
+Вторым шагом надо собрать [`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 insatll -r robossembler-ros2/repos/requirements.txt
+```
+
+> [!IMPORTANT]
+> Стоит отметить, что для того, чтобы выполнить следующую команду вам необходимо
+> установить `git lfs` так как в `requirements.txt` есть модуль `rbs_assets_library` который содержит
+> в себе тяжелые файлы, но при этом устанавливается как модуль python.
+
+При этом команду надо выполнять в директории `{robossembler_ws}/src/`
+
+Более четкая последовательность команд кому лень:
+```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
+```