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

2026-06-21 07:29:21 +03:00
parent a983a06e41
commit d26d60def4
12 changed files with 182 additions and 88 deletions
@@ -30,7 +30,11 @@ cobot doc-setup --help    # справка по подкомандам конк

 ### `cobot setup`

-Мастер-команда первого запуска. Последовательно вызывает все `*-setup` команды по очереди: настраивает документацию, среду выполнения и параметры робота.
+Мастер-команда первого запуска. Проводит через три шага:
+
+1. Настройка сервера документации
+2. Параметры робота (`cobot-setting.yaml`) — IP, порт FRI, инструмент
+3. Выбор среды сборки: ROS2 Jazzy нативно или Docker-образ

 ```bash
 cobot setup
@@ -162,4 +166,4 @@ cobot delete

 ---

-**Следующий шаг:** [Конфигурация системы](configuration.md)
+**Управление роботом:** [Управление через REST API](control/rest-api.md)
@@ -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)
@@ -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 мс | Стандартное управление и программирование |
@@ -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-линк для декартовых целей |
@@ -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
@@ -5,6 +5,10 @@
 Все параметры системы хранятся в одном файле — **`cobot-setting.yaml`** в корне проекта.
 Это единственный источник истины для IP-адреса робота, портов, путей к конфигам, настроек планировщика и веб-сервера.

+!!! info "Не нужно настраивать вручную до установки"
+    При выполнении `cobot setup` мастер автоматически предложит настроить этот файл на **шаге 2** — вам не нужно делать это заранее.
+    Возвращайтесь к этому разделу когда захотите изменить параметры после первоначальной установки.
+
 !!! danger "Не редактируйте файл вручную"
    Используйте только команду `cobot robot-setup` — интерактивный мастер валидирует значения и не допускает синтаксических ошибок. Ручное редактирование YAML может привести к ошибкам парсинга и невозможности запуска системы.

@@ -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).
@@ -111,4 +111,4 @@ cobot -h

 ---

-**Следующий шаг:** [CLI-команды cobot](cli-reference.md)
+**Следующий шаг:** [Конфигурация системы](configuration.md)
@@ -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`.