feat: add English documentation for Lightweight Cobot

2026-05-24 10:35:35 +03:00
parent cbd05effd2
commit e60402c8f2
2 changed files with 284 additions and 9 deletions
@@ -1,14 +1,149 @@
-## Описание пакетов
+# Lightweight Cobot

-|Наименование|описание|
-|---|---|
-|iiwa_bringup|Все необходимые файлы запуска расположены в этом пакете|
-|iiwa_config|Файлы конфигурации и основной `setting.yam` файл расположены внутри этого пакета|
-|iiwa_controller|Самописный контроллер на физического робота|
-|iiwa_description|urdf/xacro файлы, а также все 3D объекты и webots миры находятся в этом пакете|
-|iiwa_utils|Вспомогательные модули или функции для рабоы всей системы|
+> **Тестовая версия документации — будет дополнена**

+ROS 2 пакеты для управления роботом **KUKA LBR IIWA 7 R800**: связь с реальным роботом через библиотеку [FRI](https://github.com/lbr-stack/fri) (Fast Robot Interface) и симуляция в среде [Webots](https://cyberbotics.com/).

+<table>
+  <tr>
+    <th align="center">LBR IIWA 7 R800</th>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="https://raw.githubusercontent.com/lbr-stack/lbr_fri_ros2_stack/jazzy/lbr_fri_ros2_stack/doc/img/foxglove/iiwa7_r800.png" alt="LBR IIWA 7 R800" width="300">
+    </td>
+  </tr>
+</table>
+
+---
+
+## Статус
+
+| ОС | Дистрибутив ROS | Версия FRI |
+| :--- | :--- | :--- |
+| `Ubuntu 24.04` | `jazzy` | `1.15` |
+
+---
+
+## Быстрый старт
+
+Для установки запустите скрипт одной командой:
+
+```bash
+curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/main/install.sh
+```
+
+Скрипт установит ROS 2 Jazzy, Webots, соберёт рабочее пространство и установит CLI `cobot`.
+
+---
+
+## Команды `cobot`
+
+После установки управляйте системой через CLI:
+
+```
+cobot <команда>
+```
+
+### Настройка
+
+| Команда | Описание |
+| :--- | :--- |
+| `cobot setup` | Первоначальная настройка: документация, среда сборки, конфигурация робота |
+| `cobot local-setup` | Установка ROS 2 Jazzy локально и сборка проекта через colcon |
+| `cobot docker-setup` | Сборка или загрузка Docker-образов |
+| `cobot doc-setup` | Запуск или остановка сервера документации MkDocs |
+| `cobot robot-setup` | Интерактивная настройка файла `cobot-setting.yaml` |
+
+### Запуск
+
+| Команда | Описание |
+| :--- | :--- |
+| `cobot run` | Запуск контроллера робота или симулятора Webots (локально или через Docker) |
+
+### Сборка
+
+| Команда | Описание |
+| :--- | :--- |
+| `cobot rebuild` | Пересборка ROS 2 пакетов из `src/` с помощью colcon |
+| `cobot clean` | Удаление артефактов сборки (`build/` `install/` `log/`) |
+
+### Управление
+
+| Команда | Описание |
+| :--- | :--- |
+| `cobot update` | Получение последних изменений из удалённой ветки и переустановка `cobot` |
+| `cobot delete` | Удаление проекта, Docker-образов, контейнеров и опционально ROS 2 |
+
+---
+
+## Демонстрация
+
+> GIF-анимации будут добавлены в следующих версиях
+
+<table>
+  <tr>
+    <th align="center" width="33%">Симуляция в Webots</th>
+    <th align="center" width="33%">Управление по суставам</th>
+    <th align="center" width="33%">Декартово управление</th>
+  </tr>
+  <tr>
+    <td align="center"><i>— скоро —</i></td>
+    <td align="center"><i>— скоро —</i></td>
+    <td align="center"><i>— скоро —</i></td>
+  </tr>
+</table>
+
+---
+
+## Пакеты
+
+| Пакет | Описание |
+| :--- | :--- |
+| `iiwa_bringup` | Launch-файлы: симуляция Webots, реальный робот через FRI, MoveIt и RViz |
+| `iiwa_config` | Конфигурационные файлы: MoveIt, контроллеры ros2_control, кинематика и общие параметры |
+| `iiwa_controller` | Hardware interface: управление суставами в реальном времени через FRI |
+| `iiwa_description` | URDF/XACRO описание робота и конфигурация мира Webots |
+| `iiwa_msgs` | ROS 2 интерфейсы: action-сообщения для движения по суставам и в декартовых координатах, сервисы именованных поз |
+| `iiwa_planning` | Планирование движения: C++ и Python узлы на базе MoveIt 2 (OMPL, Pilz, moveit_py) |
+| `iiwa_utils` | Утилиты системы: загрузка конфигурации, спавн объектов и камер в Webots, конвертация данных |
+| `iiwa_web` | Веб-интерфейс для мониторинга и дистанционного управления через браузер |
+
+---
+
+## Цитирование
+
+Если вы используете этот проект в своей работе, пожалуйста, оставьте звёздочку ⭐ и укажите ссылку:
+
+```bibtex
+@software{lightweight_cobot_2026,
+  author  = {Грабарь, Даниил},
+  title   = {Lightweight Cobot: ROS 2 stack for KUKA LBR IIWA 7},
+  year    = {2026},
+  url     = {https://gitverse.ru/daniel-robotics/lightweight-cobot}
+}
+```
+
+---
+
+## Благодарности
+
+Выражаем благодарность следующим организациям и грантам:
+
+| Организация | Примечание |
+| :--- | :--- |
+| [Комсомольский-на-Амуре государственный университет](https://knastu.ru/) | Исследования проводились на базе КнАГУ |
+| [Российский научный фонд](https://rscf.ru/) | Работа выполнена при поддержке Российского научного фонда |
+| <!-- TODO --> | <!-- TODO --> |
+| <!-- TODO --> | <!-- TODO --> |
+
+---
+
+<!-- ============================================================ -->
+<!-- Черновые команды — будут удалены в следующих версиях         -->
+<!-- ============================================================ -->
+
+## Черновые команды

 > Вроде уже не обязательно
 Подмена файла по пути обязательна: `/opt/ros/rolling/lib/webots_ros2_driver/ros2_supervisor.py`
@@ -165,8 +300,10 @@ docker build -t evilfisru/lwc:... -f docker/jazzy/.../Dockerfile .
 docker run -it --rm --network host evilfisru/lwa:jazzy-lwa7-noble
 ```

+```bash
 # release - src/build/log удаляются (по умолчанию)
 `docker build -t my-image .`

 # dev - src остаётся для отладки
-`docker build --build-arg BUILD_TYPE=dev -t my-image .`
+`docker build --build-arg BUILD_TYPE=dev -t my-image .`
+```
@@ -0,0 +1,138 @@
+# Lightweight Cobot
+
+> **Draft documentation — work in progress**
+
+ROS 2 packages for controlling the **KUKA LBR IIWA 7 R800**: communication with the real robot via [FRI](https://github.com/lbr-stack/fri) (Fast Robot Interface) and simulation in [Webots](https://cyberbotics.com/).
+
+<table>
+  <tr>
+    <th align="center">LBR IIWA 7 R800</th>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="https://raw.githubusercontent.com/lbr-stack/lbr_fri_ros2_stack/jazzy/lbr_fri_ros2_stack/doc/img/foxglove/iiwa7_r800.png" alt="LBR IIWA 7 R800" width="300">
+    </td>
+  </tr>
+</table>
+
+---
+
+## Status
+
+| OS | ROS Distribution | FRI Version |
+| :--- | :--- | :--- |
+| `Ubuntu 24.04` | `jazzy` | `1.15` |
+
+---
+
+## Quick Start
+
+Install everything with a single command:
+
+```bash
+bash <(curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/main/install.sh)
+```
+
+The script installs ROS 2 Jazzy, Webots, builds the workspace, and installs the `cobot` CLI.
+
+---
+
+## `cobot` Commands
+
+After installation, manage the system via CLI:
+
+```
+cobot <command>
+```
+
+### Setup
+
+| Command | Description |
+| :--- | :--- |
+| `cobot setup` | First-time setup: documentation server, build environment, robot config |
+| `cobot local-setup` | Install ROS 2 Jazzy natively and build the project with colcon |
+| `cobot docker-setup` | Build or pull Docker images |
+| `cobot doc-setup` | Deploy or stop the MkDocs documentation server |
+| `cobot robot-setup` | Configure `cobot-setting.yaml` interactively |
+
+### Run
+
+| Command | Description |
+| :--- | :--- |
+| `cobot run` | Launch the robot controller or Webots simulator (local or Docker) |
+
+### Build
+
+| Command | Description |
+| :--- | :--- |
+| `cobot rebuild` | Rebuild ROS 2 packages in `src/` with colcon |
+| `cobot clean` | Remove colcon build artifacts (`build/` `install/` `log/`) |
+
+### Management
+
+| Command | Description |
+| :--- | :--- |
+| `cobot update` | Pull latest changes from the remote git branch and reinstall `cobot` |
+| `cobot delete` | Remove the project, Docker images, containers, and optionally ROS 2 |
+
+---
+
+## Demo
+
+> GIF animations will be added in upcoming releases
+
+<table>
+  <tr>
+    <th align="center" width="33%">Webots Simulation</th>
+    <th align="center" width="33%">Joint-Space Control</th>
+    <th align="center" width="33%">Cartesian Control</th>
+  </tr>
+  <tr>
+    <td align="center"><i>— coming soon —</i></td>
+    <td align="center"><i>— coming soon —</i></td>
+    <td align="center"><i>— coming soon —</i></td>
+  </tr>
+</table>
+
+---
+
+## Packages
+
+| Package | Description |
+| :--- | :--- |
+| `iiwa_bringup` | Launch files: Webots simulation, real robot via FRI, MoveIt motion planning and RViz visualization |
+| `iiwa_config` | Configuration files: MoveIt, ros2_control controllers, kinematics and general system settings |
+| `iiwa_controller` | Hardware interface: real-time joint control via FRI within the ros2_control ecosystem |
+| `iiwa_description` | URDF/XACRO robot description and Webots world configuration |
+| `iiwa_msgs` | ROS 2 interfaces: action messages for joint-space and Cartesian motion, services for named poses |
+| `iiwa_planning` | Motion planning: C++ and Python nodes built on MoveIt 2 (OMPL, Pilz, moveit_py) |
+| `iiwa_utils` | System utilities: configuration loading, object and camera spawning in Webots, data conversion |
+| `iiwa_web` | Web interface for monitoring and remote control of the cobot via browser |
+
+---
+
+## Citation
+
+If you use this project in your work, please leave a star ⭐ and cite it:
+
+```bibtex
+@software{lightweight_cobot_2026,
+  author  = {Hrabar, Daniil},
+  title   = {Lightweight Cobot: ROS 2 stack for KUKA LBR IIWA 7},
+  year    = {2026},
+  url     = {https://gitverse.ru/daniel-robotics/lightweight-cobot}
+}
+```
+
+---
+
+## Acknowledgements
+
+We gratefully acknowledge the support of the following organizations and grants:
+
+| Organization | Notes |
+| :--- | :--- |
+| [Komsomolsk-on-Amur State University (KnAGU)](https://knastu.ru/) | Research was conducted at KnAGU |
+| [Russian Science Foundation (RSF)](https://rscf.ru/) | Work supported by the Russian Science Foundation |
+| <!-- TODO --> | <!-- TODO --> |
+| <!-- TODO --> | <!-- TODO --> |