From 08ebd406711bc60cfc01a53159e5bda1719c5521 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=B0=D0=BD=D0=B8=D0=B8=D0=BB=20=D0=93=D1=80=D0=B0?= =?UTF-8?q?=D0=B1=D0=B0=D1=80=D1=8C?= Date: Thu, 13 Aug 2026 17:01:34 +0300 Subject: [PATCH] docs: update README files with project features and compatibility details --- README.md | 181 +++++++++++++++++++++++++++++---------------- README_en.md | 203 ++++++++++++++++++++++++++++++++------------------- 2 files changed, 244 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index e5f71ab..0ba83a3 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # Lightweight Cobot -> **Тестовая версия документации — будет дополнена** +

+ Русский · English +

-ROS 2 пакеты для управления роботом **KUKA LBR IIWA 7 R800**: связь с реальным роботом через библиотеку [FRI](https://github.com/lbr-stack/fri) (Fast Robot Interface) и симуляция в среде [Webots](https://cyberbotics.com/). +**Lightweight Cobot (LWC)** — открытая система управления коллаборативным роботом **KUKA LBR iiwa 7 R800** на базе ROS 2. Проект объединяет работу с физическим роботом через FRI и `ros2_control`, цифровой двойник в Webots, планирование движений MoveIt 2, визуализацию в RViz и Foxglove, а также REST API и MCP для внешних приложений и AI-агентов. @@ -15,91 +17,138 @@ ROS 2 пакеты для управления роботом **KUKA LBR IIWA 7
---- +## Какие задачи решает проект -## Статус +- Даёт единый программный стек для физического робота и симуляции без дублирования управляющего кода. +- Подключает KUKA Sunrise Cabinet к ROS 2 через FRI и предоставляет стандартные интерфейсы `ros2_control`. +- Выполняет суставные и декартовы движения с помощью MoveIt 2, OMPL и Pilz. +- Упрощает установку, настройку, сборку и запуск через CLI `cobot`. +- Хранит основные параметры робота, инструментов и сервисов в одном файле `cobot-setting.yaml`. +- Предоставляет средства мониторинга и интеграции через RViz, Foxglove, HTTP/WebSocket API и MCP. -| ОС | Дистрибутив ROS | Версия FRI | -| :--- | :--- | :--- | -| `Ubuntu 24.04` | `jazzy` | `1.16` | +## Возможности ---- +| Компонент | Назначение | +|---|---| +| Физический робот | Управление KUKA LBR iiwa 7 R800 через FRI и `ServerFriRos2` | +| Цифровой двойник | Симуляция робота, инструментов и окружения в Webots | +| Планирование | Суставные и декартовы траектории через MoveIt 2 | +| Управление | `ros2_control`, ROS 2 actions/services, REST API и MCP | +| Наблюдение | RViz, Foxglove и состояние системы через веб-интерфейс | +| Инфраструктура | Локальное окружение или Docker, единый CLI и централизованная конфигурация | + +## Совместимость + +| Компонент | Поддерживаемая версия | +|---|---| +| Операционная система | **Ubuntu 24.04 LTS** — подтверждённая ОС для нативной установки | +| ROS 2 | Jazzy | +| Webots | 2025a | +| Python для CLI | 3.11 | +| KUKA Sunrise OS | 1.16 | +| KUKA FRI | 1.16 | + +Docker можно использовать как альтернативную среду на совместимом Linux-хосте. Полноценная работа проекта на Windows и macOS не заявлена. Sunrise Workbench используется отдельно для подготовки и синхронизации проекта контроллера KUKA. + +## Репозитории и документация + +| Ресурс | Ссылка | +|---|---| +| Основной репозиторий | [GitVerse](https://gitverse.ru/daniel-robotics/lightweight-cobot) | +| Зеркало | [GitHub](https://github.com/Daniel-Robotic/lightweight-cobot) | +| Онлайн-документация | [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/) | +| Зеркало документации | [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/) | + +Подробные инструкции начинаются со страницы [«Обзор»](doc/lwc-doc/docs/getting-started/index.md). Исходные тексты документации находятся в `doc/lwc-doc/docs`. ## Быстрый старт -Для установки запустите скрипт одной командой: +### Требования + +- Ubuntu 24.04 LTS; +- доступ в интернет; +- права `sudo`; +- физический KUKA LBR iiwa 7 R800 либо компьютер для работы только с симулятором. + +### Установка CLI + +Запустите установщик: ```bash curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash ``` -Скрипт установит ROS 2 Jazzy, Webots, соберёт рабочее пространство и установит CLI `cobot`. +Установщик проверит базовые инструменты, установит Docker, `uv` и Python 3.11 при необходимости, склонирует проект в `~/.lwc` и установит CLI `cobot`. Каталог можно изменить переменной `COBOT_INSTALL_DIR`. ---- +Откройте новый терминал или обновите окружение оболочки, затем запустите мастер первоначальной настройки: -## Команды `cobot` - -После установки управляйте системой через CLI: - -``` -cobot <команда> +```bash +cobot setup ``` -### Настройка +Мастер последовательно предложит запустить локальную документацию, настроить `cobot-setting.yaml` и выбрать среду сборки: нативный ROS 2 или Docker. -| Команда | Описание | -| :--- | :--- | -| `cobot setup` | Первоначальная настройка: документация, среда сборки, конфигурация робота | -| `cobot local-setup` | Установка ROS 2 Jazzy локально и сборка проекта через colcon | -| `cobot docker-setup` | Сборка или загрузка Docker-образов | -| `cobot doc-setup` | Запуск или остановка сервера документации MkDocs | -| `cobot robot-setup` | Интерактивная настройка файла `cobot-setting.yaml` | +### Только симуляция -### Запуск +Для работы в Webots физический робот и Sunrise Workbench не требуются. Выполните: -| Команда | Описание | -| :--- | :--- | -| `cobot run` | Запуск контроллера робота или симулятора Webots (локально или через Docker) | +```bash +cobot run +``` -### Сборка +Выберите локальную или Docker-среду, а затем пункт **Симулятор Webots**. -| Команда | Описание | -| :--- | :--- | -| `cobot rebuild` | Пересборка ROS 2 пакетов из `src/` с помощью colcon | -| `cobot clean` | Удаление артефактов сборки (`build/` `install/` `log/`) | +### Физический робот -### Управление +Перед первым запуском подготовьте контроллер и программу `ServerFriRos2` по инструкции [«Настройка SunriseWorkbench»](doc/lwc-doc/docs/getting-started/sunrise-setup.md). Проверьте сеть KONI/KLI, IP-адреса, период FRI, выбранный инструмент и его Load Data. -| Команда | Описание | -| :--- | :--- | -| `cobot update` | Получение последних изменений из удалённой ветки и переустановка `cobot` | -| `cobot delete` | Удаление проекта, Docker-образов, контейнеров и опционально ROS 2 | +После настройки запустите: ---- +```bash +cobot run +``` -## Демонстрация +Выберите локальную или Docker-среду, а затем пункт **Физический контроллер**. Подробное описание серверной программы приведено на странице [ServerFriRos2](doc/lwc-doc/docs/sunrise/kuka/programs/server-fri-ros2.md). -> GIF-анимации будут добавлены в следующих версиях +## Основные команды - - - - - - - - - - - -
Симуляция в WebotsУправление по суставамДекартово управление
— скоро —— скоро —— скоро —
+| Команда | Назначение | +|---|---| +| `cobot setup` | Первоначальная настройка документации, робота и среды сборки | +| `cobot robot-setup` | Интерактивное изменение `cobot-setting.yaml` | +| `cobot local-setup` | Установка ROS 2 Jazzy и локальная сборка workspace | +| `cobot docker-setup` | Загрузка или сборка Docker-образов | +| `cobot run` | Интерактивный выбор среды и запуск робота или Webots | +| `cobot run local` | Запуск через нативный ROS 2 с последующим выбором робота или Webots | +| `cobot run docker` | Запуск в Docker с последующим выбором робота или Webots | +| `cobot rebuild` | Пересборка ROS 2 workspace | +| `cobot clean` | Удаление артефактов `build`, `install` и `log` | +| `cobot update` | Обновление проекта и переустановка CLI | +| `cobot --help` | Полный список доступных команд | ---- +## Документация локально + +Для локального просмотра необходим Docker. + +```bash +cobot doc-setup +``` + +По умолчанию сайт будет доступен по адресу [http://localhost:8000](http://localhost:8000). Исходные Markdown-файлы отслеживаются автоматически. + +| Команда | Назначение | +|---|---| +| `cobot doc-setup` | Запустить локальный сервер документации | +| `cobot doc-setup build` | Собрать статический сайт и единый PDF в `doc/lwc-doc/site` | +| `cobot doc-setup rebuild` | Пересобрать Docker-образ и перезапустить сервер | +| `cobot doc-setup down` | Остановить локальный сервер | + +Онлайн-версия доступна на [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/), зеркало — на [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/). ## Пакеты | Пакет | Описание | -| :--- | :--- | +|---|---| | `iiwa_bringup` | Launch-файлы: симуляция Webots, реальный робот через FRI, MoveIt и RViz | | `iiwa_config` | Конфигурационные файлы: MoveIt, контроллеры ros2_control, кинематика и общие параметры | | `iiwa_controller` | Hardware interface: управление суставами в реальном времени через FRI | @@ -107,13 +156,21 @@ cobot <команда> | `iiwa_msgs` | ROS 2 интерфейсы: action-сообщения для движения по суставам и в декартовых координатах, сервисы именованных поз | | `iiwa_planning` | Планирование движения: C++ и Python узлы на базе MoveIt 2 (OMPL, Pilz, moveit_py) | | `iiwa_utils` | Утилиты системы: загрузка конфигурации, спавн объектов и камер в Webots, конвертация данных | -| `iiwa_web` | Веб-интерфейс для мониторинга и дистанционного управления через браузер | +| `iiwa_web` | REST API, WebSocket и MCP для мониторинга и внешнего управления | ---- +Java-программы для KUKA Sunrise Cabinet находятся отдельно в `src/iiwa_sunrise` и не входят в сборку colcon. + +## Безопасность + +Перед отправкой команд на физический робот проверьте рабочую область, ограничения суставов, активный инструмент, модель нагрузки и выбранный режим управления. LWC не заменяет штатные средства безопасности KUKA, оценку рисков роботизированной ячейки и контроль оператора. + +## Лицензия + +Проект распространяется по лицензии [Apache License 2.0](LICENSE). ## Цитирование -Если вы используете этот проект в своей работе, пожалуйста, оставьте звёздочку ⭐ и укажите ссылку: +Если вы используете проект в исследовании или разработке, укажите ссылку на репозиторий: ```bibtex @software{lightweight_cobot_2026, @@ -128,14 +185,10 @@ cobot <команда> ## Благодарности -Выражаем благодарность следующим организациям и грантам: - | Организация | Примечание | -| :--- | :--- | +|---|---| | [Комсомольский-на-Амуре государственный университет](https://knastu.ru/) | Исследования проводились на базе КнАГУ | | [Российский научный фонд](https://rscf.ru/) | Работа выполнена при поддержке Российского научного фонда | -| | | -| | | --- diff --git a/README_en.md b/README_en.md index 4147b70..ee28a17 100644 --- a/README_en.md +++ b/README_en.md @@ -1,119 +1,176 @@ # Lightweight Cobot -> **Draft documentation — work in progress** +

+ Русский · English +

-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/). +**Lightweight Cobot (LWC)** is an open control system for the **KUKA LBR iiwa 7 R800** collaborative robot built on ROS 2. It combines physical robot control through FRI and `ros2_control`, a Webots digital twin, MoveIt 2 motion planning, RViz and Foxglove visualization, plus REST and MCP interfaces for external applications and AI agents. - +
LBR IIWA 7 R800LBR iiwa 7 R800
- LBR IIWA 7 R800 + LBR iiwa 7 R800
---- +## Problems solved by the project -## Status +- Provides one software stack for both the physical robot and simulation without duplicating control code. +- Connects KUKA Sunrise Cabinet to ROS 2 through FRI and exposes standard `ros2_control` interfaces. +- Executes joint-space and Cartesian motions using MoveIt 2, OMPL, and Pilz. +- Simplifies installation, configuration, builds, and startup through the `cobot` CLI. +- Keeps the main robot, tool, and service parameters in one `cobot-setting.yaml` file. +- Provides monitoring and integration through RViz, Foxglove, HTTP/WebSocket APIs, and MCP. -| OS | ROS Distribution | FRI Version | -| :--- | :--- | :--- | -| `Ubuntu 24.04` | `jazzy` | `1.16` | +## Features ---- +| Component | Purpose | +|---|---| +| Physical robot | KUKA LBR iiwa 7 R800 control through FRI and `ServerFriRos2` | +| Digital twin | Robot, tool, and environment simulation in Webots | +| Motion planning | Joint-space and Cartesian trajectories through MoveIt 2 | +| Control | `ros2_control`, ROS 2 actions/services, REST API, and MCP | +| Monitoring | RViz, Foxglove, and system state through the web interface | +| Infrastructure | Native or Docker environment, a unified CLI, and centralized configuration | -## Quick Start +## Compatibility -Install everything with a single command: +| Component | Supported version | +|---|---| +| Operating system | **Ubuntu 24.04 LTS** — verified for native installation | +| ROS 2 | Jazzy | +| Webots | 2025a | +| CLI Python | 3.11 | +| KUKA Sunrise OS | 1.16 | +| KUKA FRI | 1.16 | + +Docker is available as an alternative environment on a compatible Linux host. Full Windows and macOS support is not claimed. Sunrise Workbench is used separately to prepare and synchronize the KUKA controller project. + +## Repositories and documentation + +| Resource | Link | +|---|---| +| Primary repository | [GitVerse](https://gitverse.ru/daniel-robotics/lightweight-cobot) | +| Mirror | [GitHub](https://github.com/Daniel-Robotic/lightweight-cobot) | +| Online documentation | [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/) | +| Documentation mirror | [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/) | + +The detailed guide starts on the [Overview](doc/lwc-doc/docs/getting-started/index.md) page. Documentation sources are stored under `doc/lwc-doc/docs`. + +## Quick start + +### Requirements + +- Ubuntu 24.04 LTS; +- internet access; +- `sudo` privileges; +- a physical KUKA LBR iiwa 7 R800, or a computer if only the simulator will be used. + +### Install the CLI + +Run the installer: ```bash curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash ``` -The script installs ROS 2 Jazzy, Webots, builds the workspace, and installs the `cobot` CLI. +The installer checks the basic tools, installs Docker, `uv`, and Python 3.11 when required, clones the project into `~/.lwc`, and installs the `cobot` CLI. Set `COBOT_INSTALL_DIR` to use a different location. ---- +Open a new terminal or reload the shell environment, then start the first-time setup wizard: -## `cobot` Commands - -After installation, manage the system via CLI: - -``` -cobot +```bash +cobot setup ``` -### Setup +The wizard offers to start the local documentation, configure `cobot-setting.yaml`, and prepare either a native ROS 2 or Docker build environment. -| 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 | +### Simulation only -### Run +A physical robot and Sunrise Workbench are not required for Webots simulation. Run: -| Command | Description | -| :--- | :--- | -| `cobot run` | Launch the robot controller or Webots simulator (local or Docker) | +```bash +cobot run +``` -### Build +Choose the native or Docker environment, then select **Webots simulator**. -| Command | Description | -| :--- | :--- | -| `cobot rebuild` | Rebuild ROS 2 packages in `src/` with colcon | -| `cobot clean` | Remove colcon build artifacts (`build/` `install/` `log/`) | +### Physical robot -### Management +Before the first run, prepare the controller and `ServerFriRos2` as described in [Sunrise Workbench setup](doc/lwc-doc/docs/getting-started/sunrise-setup.md). Verify the KONI/KLI network, IP addresses, FRI period, selected tool, and its Load Data. -| 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 | +Then run: ---- +```bash +cobot run +``` -## Demo +Choose the native or Docker environment, then select **Physical controller**. See the [ServerFriRos2](doc/lwc-doc/docs/sunrise/kuka/programs/server-fri-ros2.md) page for details about the controller-side application. -> GIF animations will be added in upcoming releases +## Main commands - - - - - - - - - - - -
Webots SimulationJoint-Space ControlCartesian Control
— coming soon —— coming soon —— coming soon —
+| Command | Purpose | +|---|---| +| `cobot setup` | Configure documentation, robot parameters, and the build environment | +| `cobot robot-setup` | Edit `cobot-setting.yaml` interactively | +| `cobot local-setup` | Install ROS 2 Jazzy and build the workspace natively | +| `cobot docker-setup` | Pull or build the Docker images | +| `cobot run` | Select an environment and launch the physical robot or Webots interactively | +| `cobot run local` | Use native ROS 2, then select the physical robot or Webots | +| `cobot run docker` | Use Docker, then select the physical robot or Webots | +| `cobot rebuild` | Rebuild the ROS 2 workspace | +| `cobot clean` | Remove the `build`, `install`, and `log` artifacts | +| `cobot update` | Update the project and reinstall the CLI | +| `cobot --help` | Show every available command | ---- +## Local documentation + +Docker is required for the local documentation server. + +```bash +cobot doc-setup +``` + +By default, the site is available at [http://localhost:8000](http://localhost:8000). Markdown source changes are watched automatically. + +| Command | Purpose | +|---|---| +| `cobot doc-setup` | Start the local documentation server | +| `cobot doc-setup build` | Build the static site and combined PDF under `doc/lwc-doc/site` | +| `cobot doc-setup rebuild` | Rebuild the Docker image and restart the server | +| `cobot doc-setup down` | Stop the local server | + +The online documentation is hosted on [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot/), with a mirror on [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/). ## 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 | +|---|---| +| `iiwa_bringup` | Launch files for Webots, the physical FRI robot, MoveIt, and RViz | +| `iiwa_config` | MoveIt, `ros2_control`, kinematics, and shared configuration files | +| `iiwa_controller` | Real-time FRI hardware interface for `ros2_control` | +| `iiwa_description` | URDF/Xacro robot description, meshes, tools, and Webots worlds | +| `iiwa_msgs` | ROS 2 actions and services for joint, Cartesian, and named-pose motions | +| `iiwa_planning` | C++ and Python motion nodes based on MoveIt 2, OMPL, Pilz, and `moveit_py` | +| `iiwa_utils` | Configuration loading, data conversion, and Webots object/camera utilities | +| `iiwa_web` | REST API, WebSocket, and MCP interfaces for monitoring and external control | ---- +Java applications for KUKA Sunrise Cabinet live separately under `src/iiwa_sunrise` and are not part of the colcon build. + +## Safety + +Before commanding the physical robot, verify the work area, joint limits, active tool, load model, and selected control mode. LWC does not replace KUKA safety functions, a robotic-cell risk assessment, or operator supervision. + +## License + +This project is available under the [Apache License 2.0](LICENSE). ## Citation -If you use this project in your work, please leave a star ⭐ and cite it: +If you use the project in research or development, cite the repository: ```bibtex @software{lightweight_cobot_2026, @@ -124,15 +181,9 @@ If you use this project in your work, please leave a star ⭐ and cite it: } ``` ---- - ## 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 | -| | | -| | |