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

refactor: update setup wizard steps and documentation; remove overview section

Browse Source
This commit is contained in:
Даниил Грабарь
2026-06-21 07:29:21 +03:00
parent a983a06e41
commit d26d60def4
12 changed files with 182 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cobot/commands/setup.py
+10 -10
View File
@@ -19,8 +19,8 @@ def register(subparsers):
def run(args: argparse.Namespace) -> None: def run(args: argparse.Namespace) -> None:
"""Run the three-step first-time setup wizard: docs -> build env -> robot config. """Run the three-step first-time setup wizard: docs -> robot config -> build env.
Запускает трёхшаговый мастер первичной настройки: документация -> среда сборки -> конфиг. Запускает трёхшаговый мастер первичной настройки: документация -> конфиг робота -> среда сборки.
""" """
ui.header("Первичная настройка", "3 шага") ui.header("Первичная настройка", "3 шага")
@@ -29,10 +29,15 @@ def run(args: argparse.Namespace) -> None:
if ui.confirm("Шаг 1/3 — настроить сервер документации?", default=True): if ui.confirm("Шаг 1/3 — настроить сервер документации?", default=True):
_doc_setup(args) _doc_setup(args)
# Step 2 - build environment: local ROS2 or Docker. # Step 2 - robot parameters in cobot-setting.yaml.
# Шаг 2 - среда сборки: локальный ROS2 или Docker. # Шаг 2 - параметры робота в cobot-setting.yaml.
if ui.confirm("Шаг 2/3 — настроить параметры робота (cobot-setting.yaml)?", default=True):
_robot_setup(args)
# Step 3 - build environment: local ROS2 or Docker.
# Шаг 3 - среда сборки: локальный ROS2 или Docker.
env_choice = ui.select( env_choice = ui.select(
"Шаг 2/3 — как настроить среду сборки?", "Шаг 3/3 — как настроить среду сборки?",
[ [
"local-setup — установить ROS2 Jazzy на эту машину и собрать через colcon", "local-setup — установить ROS2 Jazzy на эту машину и собрать через colcon",
"docker-setup — собрать Docker-образ с предустановленным ROS2 Jazzy", "docker-setup — собрать Docker-образ с предустановленным ROS2 Jazzy",
@@ -45,8 +50,3 @@ def run(args: argparse.Namespace) -> None:
_local_setup(args) _local_setup(args)
else: else:
_docker_setup(args) _docker_setup(args)
# Step 3 - robot parameters in cobot-setting.yaml.
# Шаг 3 - параметры робота в cobot-setting.yaml.
if ui.confirm("Шаг 3/3 — настроить параметры робота (cobot-setting.yaml)?", default=True):
_robot_setup(args)
doc/lwc-doc/docs/getting-started/cli-reference.md
+6 -2
View File
@@ -30,7 +30,11 @@ cobot doc-setup --help # справка по подкомандам конк
### `cobot setup` ### `cobot setup`
Мастер-команда первого запуска. Последовательно вызывает все `*-setup` команды по очереди: настраивает документацию, среду выполнения и параметры робота. Мастер-команда первого запуска. Проводит через три шага:
1. Настройка сервера документации
2. Параметры робота (`cobot-setting.yaml`) — IP, порт FRI, инструмент
3. Выбор среды сборки: ROS2 Jazzy нативно или Docker-образ
```bash ```bash
cobot setup cobot setup
@@ -162,4 +166,4 @@ cobot delete
--- ---
**Следующий шаг:** [Конфигурация системы](configuration.md) **Управление роботом:** [Управление через REST API](control/rest-api.md)
doc/lwc-doc/docs/getting-started/concepts/architecture.md
+15
View File
@@ -0,0 +1,15 @@
# Архитектура системы
!!! info "Раздел в разработке"
Подробное описание архитектуры системы готовится.
Система LWC построена как набор взаимосвязанных ROS 2 пакетов. Ключевые компоненты:
- **iiwa_bringup** — launch-файлы, точка входа для запуска всей системы
- **iiwa_controller** — hardware interface, реализует связь с контроллером KUKA по протоколу FRI
- **iiwa_planning** — планирование движений на базе MoveIt 2
- **iiwa_web** — REST API и MCP-сервер для внешнего управления
- **iiwa_description** — URDF-описание робота и миры Webots
- **iiwa_config** — все конфигурационные файлы (MoveIt, контроллеры, камеры)
- **iiwa_utils** — вспомогательные Python-утилиты, загрузка конфигов
- **iiwa_msgs** — кастомные ROS 2 типы сообщений (action, srv)
doc/lwc-doc/docs/getting-started/concepts/fri-protocol.md
+24
View File
@@ -0,0 +1,24 @@
# FRI-протокол
!!! info "Раздел в разработке"
Подробное описание FRI-протокола готовится.
**FRI (Fast Robot Interface)** — UDP-протокол низкоуровневого управления роботом KUKA в реальном времени. Работает поверх Ethernet и обеспечивает детерминированный цикл обмена данными между внешним ПК и контроллером KUKA.
## Основные характеристики
- **Транспорт:** UDP (без гарантии доставки — критично для RT)
- **Период цикла:** 5 мс (200 Гц) или 10 мс (100 Гц), задаётся в `cobot-setting.yaml` → `robot.fri_cycle_ms`
- **Режимы управления:** позиция, момент (крутящий момент), импеданс
## Требования к сетевому подключению
!!! warning "Важно: цикл 5 мс требует KONI"
Для работы с периодом цикла **5 мс (200 Гц)** необходимо подключение через порт **KONI**
(KUKA Optional Network Interface). Порт KLI поддерживает только 10 мс цикл.
При использовании KLI устанавливайте `fri_cycle_ms: 10`.
| Порт | Мин. цикл | Назначение |
|---|---|---|
| **KONI** | 5 мс | Высокочастотное управление, рекомендуется для FRI |
| **KLI** | 10 мс | Стандартное управление и программирование |
doc/lwc-doc/docs/getting-started/concepts/motion-planning.md
+23
View File
@@ -0,0 +1,23 @@
# Планирование движений
!!! info "Раздел в разработке"
Подробное описание планирования движений готовится.
LWC использует **MoveIt 2** — стандартный фреймворк планирования движений для ROS 2.
## Основные понятия
- **Группа планирования** (`iiwa_arm`) — набор суставов, для которых строится план. Задаётся в SRDF.
- **Планировщик** — алгоритм построения траектории. Доступны:
- `ompl` — универсальный вероятностный планировщик (по умолчанию)
- `pilz_industrial_motion_planner` — детерминированные траектории типа PTP, LIN, CIRC
- **TCP (Tool Center Point)** — точка инструмента, для которой задаётся целевая поза. Настраивается в `cobot-setting.yaml` → `planning.pose_link`
- **Система отсчёта** — координатная система целей. По умолчанию: `base_link`
## Настройки в `cobot-setting.yaml`
| Параметр | Описание |
|---|---|
| `planning.default_planner` | Планировщик по умолчанию: `ompl` или `pilz_industrial_motion_planner` |
| `planning.planning_attempts` | Число попыток при неудаче планирования |
| `planning.pose_link` | TCP-линк для декартовых целей |
doc/lwc-doc/docs/getting-started/concepts/simulation.md
+18
View File
@@ -0,0 +1,18 @@
# Симуляция (Webots)
!!! info "Раздел в разработке"
Подробное описание работы в симуляторе готовится.
**Webots** — симулятор роботов с открытым исходным кодом. В LWC используется как цифровой двойник робота KUKA LBR IIWA 7: позволяет разрабатывать и отлаживать алгоритмы управления без доступа к физическому роботу.
## Ключевые особенности
- Симулятор использует те же ROS 2 топики и интерфейсы, что и реальный робот
- Мир симуляции задаётся в `cobot-setting.yaml` → `digital_twin.webots.world`
- Для запуска: `cobot run --simulate`
## Отличия от реального робота
- Нет ограничений по безопасности (можно двигаться быстрее)
- Физика не идеальна — инерция, трение и упругость приближённые
- FRI-протокол не задействован — связь идёт через Webots-драйвер ROS 2
doc/lwc-doc/docs/getting-started/configuration.md
+4
View File
@@ -5,6 +5,10 @@
Все параметры системы хранятся в одном файле — **`cobot-setting.yaml`** в корне проекта. Все параметры системы хранятся в одном файле — **`cobot-setting.yaml`** в корне проекта.
Это единственный источник истины для IP-адреса робота, портов, путей к конфигам, настроек планировщика и веб-сервера. Это единственный источник истины для IP-адреса робота, портов, путей к конфигам, настроек планировщика и веб-сервера.
!!! info "Не нужно настраивать вручную до установки"
При выполнении `cobot setup` мастер автоматически предложит настроить этот файл на **шаге 2** — вам не нужно делать это заранее.
Возвращайтесь к этому разделу когда захотите изменить параметры после первоначальной установки.
!!! danger "Не редактируйте файл вручную" !!! danger "Не редактируйте файл вручную"
Используйте только команду `cobot robot-setup` — интерактивный мастер валидирует значения и не допускает синтаксических ошибок. Ручное редактирование YAML может привести к ошибкам парсинга и невозможности запуска системы. Используйте только команду `cobot robot-setup` — интерактивный мастер валидирует значения и не допускает синтаксических ошибок. Ручное редактирование YAML может привести к ошибкам парсинга и невозможности запуска системы.
doc/lwc-doc/docs/getting-started/index.md
+48
View File
@@ -0,0 +1,48 @@
# Обзор
**Lightweight Cobot (LWC)** — открытая система управления коллаборативным роботом **KUKA LBR IIWA 7 R800** на базе **ROS 2 Jazzy**. Поддерживает работу как с физическим роботом (через протокол FRI), так и в виртуальной среде (симулятор Webots). В состав проекта входят CLI-инструмент `cobot`, аппаратный интерфейс ROS 2 Control, планировщик движений MoveIt 2 и REST/MCP API для интеграции с AI-агентами.
---
## Репозитории
| Платформа | Ссылка | Статус |
|---|---|---|
| **GitVerse** (предпочтительный) | [daniel-robotics/lightweight-cobot](https://gitverse.ru/daniel-robotics/lightweight-cobot) | основной |
| GitHub | [Daniel-Robotic/lightweight-cobot](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/) — зеркало
---
## Предпосылки
- Физический робот **KUKA LBR IIWA 7 R800** — если планируете работу с реальным оборудованием
- Либо желание работать только в симуляторе **Webots** — физический робот не нужен
- ПК или сервер с **Ubuntu 24.04** (или подключение к существующему серверу по SSH)
- Доступ к сети, в которой находится контроллер робота
---
## Порядок шагов
1. [**Настройка SunriseWorkbench**](sunrise-setup.md) — подготовка контроллера KUKA: подключение кабелей, загрузка программы `ServerFriRos2`, настройка сетевых параметров. *(Только для физического робота)*
2. [**Подключение к серверу**](remote-access.md) — выбор варианта развёртывания (локально или удалённо), SSH-подключение к серверу управления.
3. [**Установка проекта**](installation.md) — скачивание и установка LWC через `curl`, `git` или вручную. После установки запустите `cobot setup` — мастер проведёт по оставшимся шагам автоматически.
4. [**Конфигурация системы**](configuration.md) — настройка `cobot-setting.yaml`: IP робота, порты, инструменты. Выполняется на шаге 2 мастера `cobot setup`, либо в любой момент позже через `cobot robot-setup`.
5. [**CLI-инструмент cobot**](cli-reference.md) — все команды управления проектом: запуск, сборка, обновление.
---
!!! tip "Только симуляция?"
Если физический робот недоступен, пропустите шаг 1 и начните сразу с [установки проекта](installation.md). Запустите симулятор командой `cobot run --simulate`.
!!! info "`cobot setup` сделает шаги 3–4 автоматически"
После установки проекта достаточно выполнить `cobot setup` — мастер последовательно предложит: настройку документации, параметры робота (`cobot-setting.yaml`) и выбор среды сборки (ROS2 или Docker).
doc/lwc-doc/docs/getting-started/installation.md
+1 -1
View File
@@ -111,4 +111,4 @@ cobot -h
--- ---
**Следующий шаг:** [CLI-команды cobot](cli-reference.md) **Следующий шаг:** [Конфигурация системы](configuration.md)
doc/lwc-doc/docs/getting-started/overview.md
-33
View File
@@ -1,33 +0,0 @@
# Быстрый старт
**Lightweight Cobot** позволяет управлять роботом KUKA LBR IIWA 7 через ROS 2: планировать траектории с помощью MoveIt 2, работать в симуляторе Webots или подключаться к физическому роботу по протоколу FRI. Весь проект управляется единым CLI-инструментом `cobot`.
Этот раздел проведёт вас от нулевого состояния до первого запуска системы.
---
## Предпосылки
- Физический робот **KUKA LBR IIWA 7 R800** — если планируете работу с реальным оборудованием
- Либо желание работать только в симуляторе **Webots** — физический робот не нужен
- ПК или сервер с **Ubuntu 24.04** (или подключение к существующему серверу по SSH)
- Доступ к сети, в которой находится контроллер робота
---
## Порядок шагов
1. [**Настройка SunriseWorkbench**](sunrise-setup.md) — подготовка контроллера KUKA: подключение кабелей, загрузка программы `ServerFriRos2`, настройка сетевых параметров. *(Только для физического робота)*
2. [**Подключение к серверу**](remote-access.md) — выбор варианта развёртывания (локально или удалённо), SSH-подключение к серверу управления.
3. [**Установка проекта**](installation.md) — скачивание и установка LWC через `curl`, `git` или вручную.
4. [**CLI-команды cobot**](cli-reference.md) — обзор всех команд: настройка, запуск, сборка, управление.
5. [**Конфигурация системы**](configuration.md) — подробное описание `cobot-setting.yaml`: что менять, что оставить по умолчанию.
---
!!! tip "Только симуляция?"
Если физический робот недоступен, пропустите шаг 1 и начните сразу с [установки проекта](installation.md). Запустите симулятор командой `cobot run --simulate`.
doc/lwc-doc/docs/index.md
+6 -21
View File
@@ -1,23 +1,8 @@
# Lightweight Cobot — Документация ---
hide:
**Lightweight Cobot (LWC)** — открытая система управления коллаборативным роботом **KUKA LBR IIWA 7 R800** на базе **ROS 2 Jazzy**. Поддерживает работу как с физическим роботом (через FRI), так и в виртуальной среде (симулятор Webots). В состав проекта входят CLI-инструмент `cobot`, аппаратный интерфейс ROS 2 Control, планировщик движений MoveIt 2 и REST/MCP API для интеграции с AI-агентами. - navigation
- toc
- footer
--- ---
## Репозитории <meta http-equiv="refresh" content="0; url=./getting-started/">
| Платформа | Ссылка | Статус |
|---|---|---|
| **GitVerse** (предпочтительный) | [daniel-robotics/lightweight-cobot](https://gitverse.ru/daniel-robotics/lightweight-cobot) | основной |
| GitHub | [Daniel-Robotic/lightweight-cobot](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/) — зеркало
---
## С чего начать
Перейдите в раздел [**Быстрый старт → Обзор**](getting-started/overview.md), чтобы пройти полный путь от подключения робота до первого запуска.
doc/lwc-doc/mkdocs.yml
+15 -9
View File
@@ -39,19 +39,24 @@ markdown_extensions:
- pymdownx.tabbed: - pymdownx.tabbed:
alternate_style: true alternate_style: true
nav: nav:
- Главная: index.md - Начало работы:
- Обзор: getting-started/index.md
- Быстрый старт:
- Обзор: getting-started/overview.md
- Настройка SunriseWorkbench: getting-started/sunrise-setup.md - Настройка SunriseWorkbench: getting-started/sunrise-setup.md
- Подключение к серверу: getting-started/remote-access.md - Подключение к серверу: getting-started/remote-access.md
- Установка проекта: getting-started/installation.md - Установка проекта: getting-started/installation.md
- CLI-команды cobot: getting-started/cli-reference.md
- Конфигурация системы: getting-started/configuration.md - Конфигурация системы: getting-started/configuration.md
- Управление:
- ROS2 (Bash): getting-started/control/ros2-control.md - Основные концепции:
- Foxglove Studio: getting-started/control/foxglove.md - Архитектура системы: getting-started/concepts/architecture.md
- REST API: getting-started/control/rest-api.md - CLI-инструмент cobot: getting-started/cli-reference.md
- FRI-протокол: getting-started/concepts/fri-protocol.md
- Симуляция (Webots): getting-started/concepts/simulation.md
- Планирование движений: getting-started/concepts/motion-planning.md
- Использование LWC:
- Управление через ROS2: getting-started/control/ros2-control.md
- Управление через Foxglove: getting-started/control/foxglove.md
- Управление через REST API: getting-started/control/rest-api.md
- Sunrise Workbench: - Sunrise Workbench:
- Обзор: sunrise/overview.md - Обзор: sunrise/overview.md
@@ -76,6 +81,7 @@ nav:
- Приложения: sunrise/kuka/features/applications.md - Приложения: sunrise/kuka/features/applications.md
- Меню робота: sunrise/kuka/features/robot-menu.md - Меню робота: sunrise/kuka/features/robot-menu.md
- Меню IO Group: sunrise/kuka/features/io-group.md - Меню IO Group: sunrise/kuka/features/io-group.md
- Решение проблем: - Решение проблем:
- Ошибка конфигурации: troubleshooting/config-error.md - Ошибка конфигурации: troubleshooting/config-error.md