grabardm/lightweight-cobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: update README files with project features and compatibility details

Browse Source
This commit is contained in:
Даниил Грабарь
2026-08-13 17:01:34 +03:00
parent 4547b786a3
commit 08ebd40671
2 changed files with 244 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+117 -64
View File
@@ -1,8 +1,10 @@
# Lightweight Cobot
> **Тестовая версия документации — будет дополнена**
<p align="center">
<strong>Русский</strong> · <a href="README_en.md">English</a>
</p>
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-агентов.
<table>
<tr>
@@ -15,91 +17,138 @@ ROS 2 пакеты для управления роботом **KUKA LBR IIWA 7
</tr>
</table>
---
## Какие задачи решает проект
## Статус
- Даёт единый программный стек для физического робота и симуляции без дублирования управляющего кода.
- Подключает 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-анимации будут добавлены в следующих версиях
## Основные команды
<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>
| Команда | Назначение |
|---|---|
| `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/) | Работа выполнена при поддержке Российского научного фонда |
| <!-- TODO --> | <!-- TODO --> |
| <!-- TODO --> | <!-- TODO --> |
---