Даниил Грабарь
3a5bc28bba
Add a native Webots marker for setting the active tool's TCP position and orientation. Dragging edits the preview; releasing the mouse submits one complete, checked joint trajectory with configured TCP speed limits. Unreachable targets reset the marker to the current TCP. Preserve coordinate, joint, and control-file commands through motion reservations and a controller action proxy. Give the gizmo lowest priority and finish its committed trajectory before dispatching queued regular commands, including waits longer than the former two-second service timeout. Place the patron TCP at its working end, 55.2 mm along local Z, and use the flange TCP when no tool is attached. Add digital_twin.tcp_gizmo configuration, ROS interfaces, launch integration, and regression coverage. Document operation, configuration, tool attachment, speed limits, and troubleshooting in both Russian and English. Validation: 42 Python tests and 8 C++ tests passed. Webots regressions covered one action per release, translation and rotation with and without a tool, unreachable targets, and ordinary commands waiting for gizmo completion.
12 KiB
Конфигурация системы
Главный конфигурационный файл
Все параметры системы хранятся в одном файле — cobot-setting.yaml в корне проекта.
Это единственный источник истины для IP-адреса робота, портов, путей к конфигам, настроек планировщика и веб-сервера.
!!! info "Не нужно настраивать вручную до установки"
При выполнении cobot setup мастер автоматически предложит настроить этот файл на шаге 2 — вам не нужно делать это заранее.
Возвращайтесь к этому разделу когда захотите изменить параметры после первоначальной установки.
!!! danger "Не редактируйте файл вручную"
Используйте только команду cobot robot-setup — интерактивный мастер валидирует значения и не допускает синтаксических ошибок. Ручное редактирование YAML может привести к ошибкам парсинга и невозможности запуска системы.
cobot robot-setup
Блок robot — параметры робота
Отвечает за соединение с физическим контроллером KUKA по протоколу FRI.
robot:
name: "iiwa7"
ip: "192.170.10.2"
port: 30200
fri_cycle_ms: 10
description: pkg://iiwa_description/urdf/iiwa7.urdf.xacro
| Параметр | Описание | Рекомендации |
|---|---|---|
name |
Модель робота | Не менять — iiwa7 |
ip |
IP-адрес контроллера KUKA | Изменить на реальный IP вашего контроллера |
port |
UDP-порт FRI | По умолчанию 30200 — менять только при конфликте портов |
fri_cycle_ms |
Период цикла FRI: 5 мс = 200 Гц, 10 мс = 100 Гц |
10 для стабильной работы, 5 для высокоточных задач |
joint_position_tau |
Постоянная времени EMA команд FRI, с | 0.04; 0 отключает сглаживание |
description |
Путь к URDF-описанию робота | Не менять |
Управление движением всегда выполняет JointTrajectoryController. Перед отправкой в FRI позиционная команда сглаживается EMA с постоянной времени robot.joint_position_tau; фильтр скорости не применяется.
Блок digital_twin — симулятор
Настройки виртуальной среды Webots и визуализации в RViz.
digital_twin:
tcp_gizmo:
enabled: true
publish_period: 0.032
command_timeout: 0.3
state_timeout: 0.5
max_linear_speed: 0.50
max_angular_speed: 0.4
webots:
world: pkg://iiwa_description/worlds/iiwa.wbt
transform: "-0.25 0 0.79"
rotation: "0 0 1 0"
controller_timer: "50"
cameras:
- pkg://iiwa_config/config/cameras/d455_top.yaml
rviz:
config: pkg://iiwa_config/config/rviz/rviz_moveit.rviz
| Параметр | Описание |
|---|---|
webots.world |
Путь к .wbt-миру симулятора |
webots.transform |
Смещение базы робота в мире [x y z] в метрах |
webots.rotation |
Ориентация базы [x y z угол] в радианах |
webots.cameras |
Список YAML-конфигов подключённых камер |
rviz.config |
Путь к конфигурации RViz |
Перемещение за TCP в Webots
Порядок действий приведён в руководстве по симуляции.
Выберите маркер TCP, переместите или поверните его штатной гизмой Webots и отпустите левую кнопку мыши. Пока кнопка удерживается, меняется только маркер. После отпускания отправляется одна полная траектория. Следующее перетаскивание доступно после её завершения. Если цель недостижима или траектория проходит через столкновение, маркер возвращается к текущему TCP.
Гизма использует звено tcp активного инструмента независимо от planning.pose_link. Для patron это рабочий торец патрона (55,2 мм от начала звена patron вдоль его локальной оси Z); без инструмента — фланец link_ee. Этот TCP также используется обычными декартовыми командами, когда planning.pose_link: tcp.
У гизмы самый низкий приоритет: во время обычного движения она недоступна. Если команда координат, joints или файла приходит во время уже начатого движения гизмы, она ждёт завершения этой траектории.
Параметр tcp_gizmo |
Описание |
|---|---|
enabled |
false полностью отключает гизму при следующем запуске; доступна только в симуляции |
publish_period |
Период обновления состояния, с |
command_timeout |
Максимальный возраст входящей цели, с; не задержка после перетаскивания |
state_timeout |
Допустимый возраст обратной связи робота, с |
max_linear_speed |
Верхний предел скорости TCP, м/с |
max_angular_speed |
Верхний предел угловой скорости TCP, рад/с |
Отпускание определяется по состоянию кнопки мыши, поэтому таймер ожидания не нужен. Скорость может быть ниже заданного предела из-за ограничений суставов, ускорения и торможения. Траектория интерполируется в суставах и достигает заданной позы TCP; прямолинейность пути TCP не гарантируется.
Блок tool — активный инструмент
Указывает, какой захват или инструмент закреплён на роботе.
tool:
active: "patron"
| Значение | Описание |
|---|---|
none |
Без инструмента |
patron |
Захват «Patron» (патрон) |
Список доступных инструментов находится в файле src/iiwa_config/config/tools.yaml. Для добавления нового инструмента необходимо описать его там, после чего указать имя в tool.active.
Применяйте выбор через cobot robot-setup: мастер обновляет описание инструмента и SRDF. После смены инструмента пересоберите проект и перезапустите симуляцию.
Блок planning — планирование движений
Параметры MoveIt 2 и конфигурации траекторного планировщика.
planning:
pose_link: "tcp"
planning_group: "iiwa_arm"
default_frame: "base_link"
default_planner: "ompl"
planning_attempts: 3
| Параметр | Описание | Рекомендации |
|---|---|---|
pose_link |
TCP-линк для декартовых целей | Соответствует фрейму в URDF — не менять без изменения URDF |
planning_group |
Группа планирования из SRDF | Не менять — iiwa_arm |
default_frame |
Система отсчёта по умолчанию | Не менять — base_link |
default_planner |
Планировщик: ompl, pilz_industrial_motion_planner |
ompl — универсальный; pilz — для предсказуемых траекторий |
planning_attempts |
Число попыток планирования при неудаче | Увеличивать при сложных траекториях |
Блок web — REST API и MCP-сервер
FastAPI-сервер для управления роботом через HTTP и MCP (интеграция с AI-агентами).
web:
enabled: true
host: "0.0.0.0"
port: 8007
endpoints: pkg://iiwa_config/config/api_endpoints.yaml
joint_limits: pkg://iiwa_config/config/moveit/joint_limits.yaml
| Параметр | Описание |
|---|---|
enabled |
Включить (true) или отключить (false) веб-сервер |
host |
Адрес прослушивания: 0.0.0.0 — все интерфейсы, 127.0.0.1 — только локально |
port |
Порт HTTP API (по умолчанию 8007) |
endpoints |
Путь к описанию REST-эндпоинтов |
joint_limits |
Путь к файлу ограничений суставов для валидации команд |
После запуска REST API доступен по адресу http://<host>:8007, MCP — по пути /mcp.
Блок foxglove — мониторинг через Foxglove Studio
Foxglove Studio — инструмент визуализации и мониторинга ROS 2 топиков в реальном времени.
foxglove:
enabled: true
port: 8765
debug: false
address: 0.0.0.0
| Параметр | Описание |
|---|---|
enabled |
Включить или отключить Foxglove Bridge |
port |
WebSocket-порт для подключения Foxglove Studio (по умолчанию 8765) |
debug |
Подробное логирование bridge-процесса |
address |
Адрес прослушивания WebSocket |
Остальные параметры блока (tls, topic_whitelist, min_qos_depth и др.) относятся к продвинутой конфигурации и в большинстве случаев менять их не требуется.
Что менять, что оставить
| Параметр | Действие | |
|---|---|---|
| ✅ | robot.ip |
Обязательно изменить на IP вашего контроллера |
| ✅ | robot.fri_cycle_ms |
Выбрать 10 (стандарт) или 5 (высокая частота) |
| ✅ | tool.active |
Указать активный инструмент |
| ✅ | web.enabled |
Выключить (false), если веб-интерфейс не нужен |
| ⚠️ | planning.* |
Менять при необходимости другого планировщика или параметров |
| ❌ | robot.description |
Не трогать — путь к URDF |
| ❌ | controller.moveit.* |
Не трогать — пути к конфигам MoveIt внутри пакетов |
| ❌ | digital_twin.webots.world |
Не трогать без знания структуры Webots-миров |