lightweight-cobot/README.md

Lightweight Cobot

Русский · English

Lightweight Cobot (LWC) — открытая система управления коллаборативным роботом KUKA LBR iiwa 7 R800 на базе ROS 2. Проект объединяет работу с физическим роботом через FRI и ros2_control, цифровой двойник в Webots, планирование движений MoveIt 2, визуализацию в RViz и Foxglove, а также REST API и MCP для внешних приложений и AI-агентов.

LBR IIWA 7 R800

Какие задачи решает проект

• Даёт единый программный стек для физического робота и симуляции без дублирования управляющего кода.
• Подключает KUKA Sunrise Cabinet к ROS 2 через FRI и предоставляет стандартные интерфейсы ros2_control.
• Выполняет суставные и декартовы движения с помощью MoveIt 2, OMPL и Pilz.
• Упрощает установку, настройку, сборку и запуск через CLI cobot.
• Хранит основные параметры робота, инструментов и сервисов в одном файле cobot-setting.yaml.
• Предоставляет средства мониторинга и интеграции через RViz, Foxglove, HTTP/WebSocket API и MCP.

Возможности

Компонент	Назначение
Физический робот	Управление 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
Зеркало	GitHub
Онлайн-документация	GitVerse Pages
Зеркало документации	GitHub Pages

Подробные инструкции начинаются со страницы «Обзор». Исходные тексты документации находятся в doc/lwc-doc/docs.

Быстрый старт

Требования

• Ubuntu 24.044 LTS;
• доступ в интернет;
• права sudo;
• физический KUKA LBR iiwa 7 R800 либо компьютер для работы только с симулятором.

Установка CLI

Запустите установщик:

curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash

Установщик проверит базовые инструменты, установит Docker, uv и Python 3.11 при необходимости, склонирует проект в ~/.lwc и установит CLI cobot. Каталог можно изменить переменной COBOT_INSTALL_DIR.

Откройте новый терминал или обновите окружение оболочки, затем запустите мастер первоначальной настройки:

cobot setup

Мастер последовательно предложит запустить локальную документацию, настроить cobot-setting.yaml и выбрать среду сборки: нативный ROS 2 или Docker.

Только симуляция

Для работы в Webots физический робот и Sunrise Workbench не требуются. Выполните:

cobot run

Выберите локальную или Docker-среду, а затем пункт Симулятор Webots.

Физический робот

Перед первым запуском подготовьте контроллер и программу ServerFriRos2 по инструкции «Настройка SunriseWorkbench». Проверьте сеть KONI/KLI, IP-адреса, период FRI, выбранный инструмент и его Load Data.

После настройки запустите:

cobot run

Выберите локальную или Docker-среду, а затем пункт Физический контроллер. Подробное описание серверной программы приведено на странице ServerFriRos2.

Основные команды

Команда	Назначение
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.

cobot doc-setup

По умолчанию сайт будет доступен по адресу 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, зеркало — на GitHub Pages.

Пакеты

Пакет	Описание
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	REST API, WebSocket и MCP для мониторинга и внешнего управления

Java-программы для KUKA Sunrise Cabinet находятся отдельно в src/iiwa_sunrise и не входят в сборку colcon.

Безопасность

Перед отправкой команд на физический робот проверьте рабочую область, ограничения суставов, активный инструмент, модель нагрузки и выбранный режим управления. LWC не заменяет штатные средства безопасности KUKA, оценку рисков роботизированной ячейки и контроль оператора.

Лицензия

Проект распространяется по лицензии Apache License 2.0.

Цитирование

Если вы используете проект в исследовании или разработке, укажите ссылку на репозиторий:

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

---

Благодарности

Организация	Примечание
Комсомольский-на-Амуре государственный университет	Исследования проводились на базе КнАГУ
Российский научный фонд	Работа выполнена при поддержке Российского научного фонда

---

Черновые команды

Вроде уже не обязательно Подмена файла по пути обязательна: /opt/ros/rolling/lib/webots_ros2_driver/ros2_supervisor.py необходимо warn заменить на warning в логере

sudo apt install -y ros-${ROS_DISTRO}-webots-ros2 \
                    ros-${ROS_DISTRO}-ros2-control \ 
                    ros-${ROS_DISTRO}-ros2-controllers \
                    ros-${ROS_DISTRO}-moveit \
                    ros-${ROS_DISTRO}-moveit-py \
                    ros-${ROS_DISTRO}-rmw-cyclonedds-cpp \
                    ros-${ROS_DISTRO}-ament-cmake-clang-format \
                    ros-${ROS_DISTRO}-rosbag2-storage-mcap \
                    ros-${ROS_DISTRO}-librealsense2 \
                    ros-${ROS_DISTRO}-realsense2* \
                    libportaudio2 \

Установка moveit2 (внимательно проверяй)

sudo apt install -y build-essential \
                    cmake \
                    git \
                    python3-colcon-common-extensions \
                    python3-flake8 \
                    python3-rosdep \
                    python3-setuptools \
                    python3-vcstool \
                    wget

# Not Using
LC_ALL=C ros2 launch iiwa_moveit demo...

sudo pip3 install transforms3d --break-system-packages

Отправка робота в точку:

ros2 action send_goal /iiwa/move_to_pose iiwa_msgs/action/MoveToPose \
  "{x: 0.5, y: 0.0, z: 0.5, a: 3.14, b: 0, c: 0, speed: 0.1, planner: 'ptp'}"

ros2 action send_goal --feedback /iiwa/move_to_joints iiwa_msgs/action/MoveToJoints \
  "{joints: [0.0, 0.0, 0.0, -1.57, 0.0, 1.57, 0.0], speed: 0.4}"

ros2 service call /iiwa/move_to_named iiwa_msgs/srv/MoveToNamedPose \
  "{name: 'home', speed: 0.5}"

ros2 service call /iiwa/move_to_named iiwa_msgs/srv/MoveToNamedPose \
  "{name: 'work', speed: 0.3}"

ros2 service call /iiwa/stop std_srvs/srv/Trigger "{}"

Примеры использования test_motion_sequence:

ros2 run iiwa_planning motion_sequence_runner \
  --ros-args \
  -p config_path:=/path/to/config.json \
  -p n_iterations:=3 \
  -p delay_between_iterations:=5.0 \
  -p bag_path:=/tmp/my_bag \
  -p joints_action:=my_ns/move_to_joints \
  -p pose_action:=my_ns/move_to_pose

Спавн объекта:

{
    "data": "Solid { name \"test_box2\" translation 0 1 0.5 children [ Shape { appearance PBRAppearance { baseColor 0.901961 0.380392 0 } geometry Box { size 0.1 0.1 0.1 } } ] boundingObject Box { size 0.1 0.1 0.1 } physics Physics { } }"
}

Спавн .proto:

Можно заготовить готовые .proto файлы, и потом случайно спавнить объект по такому принципу + создать Node который будет вызываться и спавнить этот объекты. Может быть шаблон куда потом подставятся данные через .format(). По такому же принципу спавн человека. Остается понять, только задать область спавна относительно робта

Установка зависимостей для сборки пакетов:

rosdep install --from-paths src --ignore-src -r -y --os=ubuntu:jammy

Запись данных в rosbag:

$ sudo apt-get install ros-$ROS_DISTRO-rosbag2-storage-mcap

# Record all topics
ros2 bag record -a --storage mcap -o my_session

# Record specific topics
ros2 bag record \
  /camera/image_raw \
  /lidar/points \
  /imu/data \
  --storage mcap \
  -o robot_drive_session


# LZ4 = faster write, moderate compression (good for real-time recording)
ros2 bag record -a --storage mcap \
  --compression-mode file \
  --compression-format lz4 \
  -o compressed_session

# Zstandard = slower write, better compression (good for post-processing)
ros2 bag record -a --storage mcap \
  --compression-mode file \
  --compression-format zstd \
  -o compressed_zstd_session

# convert existing rosbag2 to mcap format
ros2 bag convert \
  -i robot_drive_old/ \
  -o robot_drive_mcap/ \
  --output-options '{"storage_id": "mcap"}'

chmod +x doc/build_docs.sh

./build_docs.sh #Собирает статику в mkdocs/site/
./build_docs.sh build # То же самое явно
./build_docs.sh serve # Live-preview с авто-перезагрузкой

docker build -t evilfisru/lwc:... -f docker/jazzy/.../Dockerfile .

docker run -it --rm --network host evilfisru/lwa:jazzy-lwa7-noble

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

# dev - src остаётся для отладки
`docker build --build-arg BUILD_TYPE=dev -t my-image .`

# URL для доступа к MCP LLM
http://localhost:8007/mcp/mcp