diff --git a/cobot/commands/setup.py b/cobot/commands/setup.py index d41c5b1..771eb14 100644 --- a/cobot/commands/setup.py +++ b/cobot/commands/setup.py @@ -19,8 +19,8 @@ def register(subparsers): 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 шага") @@ -29,10 +29,15 @@ def run(args: argparse.Namespace) -> None: if ui.confirm("Шаг 1/3 — настроить сервер документации?", default=True): _doc_setup(args) - # Step 2 - build environment: local ROS2 or Docker. - # Шаг 2 - среда сборки: локальный ROS2 или Docker. + # Step 2 - robot parameters in cobot-setting.yaml. + # Шаг 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( - "Шаг 2/3 — как настроить среду сборки?", + "Шаг 3/3 — как настроить среду сборки?", [ "local-setup — установить ROS2 Jazzy на эту машину и собрать через colcon", "docker-setup — собрать Docker-образ с предустановленным ROS2 Jazzy", @@ -45,8 +50,3 @@ def run(args: argparse.Namespace) -> None: _local_setup(args) else: _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) diff --git a/doc/lwc-doc/docs/getting-started/cli-reference.md b/doc/lwc-doc/docs/getting-started/cli-reference.md index 578b2bd..63e2716 100644 --- a/doc/lwc-doc/docs/getting-started/cli-reference.md +++ b/doc/lwc-doc/docs/getting-started/cli-reference.md @@ -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) diff --git a/doc/lwc-doc/docs/getting-started/concepts/architecture.md b/doc/lwc-doc/docs/getting-started/concepts/architecture.md new file mode 100644 index 0000000..2674bdb --- /dev/null +++ b/doc/lwc-doc/docs/getting-started/concepts/architecture.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) diff --git a/doc/lwc-doc/docs/getting-started/concepts/fri-protocol.md b/doc/lwc-doc/docs/getting-started/concepts/fri-protocol.md new file mode 100644 index 0000000..868cefe --- /dev/null +++ b/doc/lwc-doc/docs/getting-started/concepts/fri-protocol.md @@ -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 мс | Стандартное управление и программирование | diff --git a/doc/lwc-doc/docs/getting-started/concepts/motion-planning.md b/doc/lwc-doc/docs/getting-started/concepts/motion-planning.md new file mode 100644 index 0000000..e86cf8f --- /dev/null +++ b/doc/lwc-doc/docs/getting-started/concepts/motion-planning.md @@ -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-линк для декартовых целей | diff --git a/doc/lwc-doc/docs/getting-started/concepts/simulation.md b/doc/lwc-doc/docs/getting-started/concepts/simulation.md new file mode 100644 index 0000000..6795ad7 --- /dev/null +++ b/doc/lwc-doc/docs/getting-started/concepts/simulation.md @@ -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 diff --git a/doc/lwc-doc/docs/getting-started/configuration.md b/doc/lwc-doc/docs/getting-started/configuration.md index 5e8e08b..b68d2ad 100644 --- a/doc/lwc-doc/docs/getting-started/configuration.md +++ b/doc/lwc-doc/docs/getting-started/configuration.md @@ -5,6 +5,10 @@ Все параметры системы хранятся в одном файле — **`cobot-setting.yaml`** в корне проекта. Это единственный источник истины для IP-адреса робота, портов, путей к конфигам, настроек планировщика и веб-сервера. +!!! info "Не нужно настраивать вручную до установки" + При выполнении `cobot setup` мастер автоматически предложит настроить этот файл на **шаге 2** — вам не нужно делать это заранее. + Возвращайтесь к этому разделу когда захотите изменить параметры после первоначальной установки. + !!! danger "Не редактируйте файл вручную" Используйте только команду `cobot robot-setup` — интерактивный мастер валидирует значения и не допускает синтаксических ошибок. Ручное редактирование YAML может привести к ошибкам парсинга и невозможности запуска системы. diff --git a/doc/lwc-doc/docs/getting-started/index.md b/doc/lwc-doc/docs/getting-started/index.md new file mode 100644 index 0000000..e033186 --- /dev/null +++ b/doc/lwc-doc/docs/getting-started/index.md @@ -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). diff --git a/doc/lwc-doc/docs/getting-started/installation.md b/doc/lwc-doc/docs/getting-started/installation.md index 688b1b6..7ce68e5 100644 --- a/doc/lwc-doc/docs/getting-started/installation.md +++ b/doc/lwc-doc/docs/getting-started/installation.md @@ -111,4 +111,4 @@ cobot -h --- -**Следующий шаг:** [CLI-команды cobot](cli-reference.md) +**Следующий шаг:** [Конфигурация системы](configuration.md) diff --git a/doc/lwc-doc/docs/getting-started/overview.md b/doc/lwc-doc/docs/getting-started/overview.md deleted file mode 100644 index 4ed221b..0000000 --- a/doc/lwc-doc/docs/getting-started/overview.md +++ /dev/null @@ -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`. diff --git a/doc/lwc-doc/docs/index.md b/doc/lwc-doc/docs/index.md index 7f19d45..6bd51f2 100644 --- a/doc/lwc-doc/docs/index.md +++ b/doc/lwc-doc/docs/index.md @@ -1,23 +1,8 @@ -# Lightweight Cobot — Документация - -**Lightweight Cobot (LWC)** — открытая система управления коллаборативным роботом **KUKA LBR IIWA 7 R800** на базе **ROS 2 Jazzy**. Поддерживает работу как с физическим роботом (через FRI), так и в виртуальной среде (симулятор Webots). В состав проекта входят CLI-инструмент `cobot`, аппаратный интерфейс ROS 2 Control, планировщик движений MoveIt 2 и REST/MCP API для интеграции с AI-агентами. - +--- +hide: + - navigation + - toc + - footer --- -## Репозитории - -| Платформа | Ссылка | Статус | -|---|---|---| -| **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), чтобы пройти полный путь от подключения робота до первого запуска. + diff --git a/doc/lwc-doc/mkdocs.yml b/doc/lwc-doc/mkdocs.yml index fc0a8aa..8e24009 100644 --- a/doc/lwc-doc/mkdocs.yml +++ b/doc/lwc-doc/mkdocs.yml @@ -39,19 +39,24 @@ markdown_extensions: - pymdownx.tabbed: alternate_style: true nav: - - Главная: index.md - - - Быстрый старт: - - Обзор: getting-started/overview.md + - Начало работы: + - Обзор: getting-started/index.md - Настройка SunriseWorkbench: getting-started/sunrise-setup.md - - Подключение к серверу: getting-started/remote-access.md - - Установка проекта: getting-started/installation.md - - CLI-команды cobot: getting-started/cli-reference.md - - Конфигурация системы: getting-started/configuration.md - - Управление: - - ROS2 (Bash): getting-started/control/ros2-control.md - - Foxglove Studio: getting-started/control/foxglove.md - - REST API: getting-started/control/rest-api.md + - Подключение к серверу: getting-started/remote-access.md + - Установка проекта: getting-started/installation.md + - Конфигурация системы: getting-started/configuration.md + + - Основные концепции: + - Архитектура системы: getting-started/concepts/architecture.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/overview.md @@ -60,22 +65,23 @@ nav: - Linux: - Обзор: sunrise/sun_install/linux/linux.md - Установка эмулятора Windows: sunrise/sun_install/linux/emulator.md - - Установка SunriseWorkbench: sunrise/sun_install/linux/workbench.md + - Установка SunriseWorkbench: sunrise/sun_install/linux/workbench.md - Конфигурация проекта: - - Создание нового проекта: sunrise/config/new-project.md + - Создание нового проекта: sunrise/config/new-project.md - Загрузка готового проекта: sunrise/config/load-project.md - - Установка библиотек: sunrise/config/libraries.md + - Установка библиотек: sunrise/config/libraries.md - KUKA LBR IIWA 7: - Описание программ: - - TeachKuka: sunrise/kuka/programs/teach-kuka.md - - LBRserver: sunrise/kuka/programs/lbr-server.md + - TeachKuka: sunrise/kuka/programs/teach-kuka.md + - LBRserver: sunrise/kuka/programs/lbr-server.md - RobotPowerControl: sunrise/kuka/programs/robot-power-control.md - Функциональные возможности: - - Станция: sunrise/kuka/features/station.md + - Станция: sunrise/kuka/features/station.md - Дополнительное меню: sunrise/kuka/features/extra-menu.md - - Приложения: sunrise/kuka/features/applications.md - - Меню робота: sunrise/kuka/features/robot-menu.md - - Меню IO Group: sunrise/kuka/features/io-group.md + - Приложения: sunrise/kuka/features/applications.md + - Меню робота: sunrise/kuka/features/robot-menu.md + - Меню IO Group: sunrise/kuka/features/io-group.md + - Решение проблем: - Ошибка конфигурации: troubleshooting/config-error.md