# Конфигурация системы

## Главный конфигурационный файл

Все параметры системы хранятся в одном файле — **`cobot-setting.yaml`** в корне проекта.
Это единственный источник истины для IP-адреса робота, портов, путей к конфигам, настроек планировщика и веб-сервера.

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

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

```bash
cobot robot-setup
```

---

## Блок `robot` — параметры робота

Отвечает за соединение с физическим контроллером KUKA по протоколу FRI.

```yaml
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.

```yaml
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

Порядок действий приведён в [руководстве по симуляции](concepts/simulation.md).

Выберите маркер 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` — активный инструмент

Указывает, какой захват или инструмент закреплён на роботе.

```yaml
tool:
  active: "patron"
```

| Значение | Описание |
|---|---|
| `none` | Без инструмента |
| `patron` | Захват «Patron» (патрон) |

Список доступных инструментов находится в файле `src/iiwa_config/config/tools.yaml`. Для добавления нового инструмента необходимо описать его там, после чего указать имя в `tool.active`.

Применяйте выбор через `cobot robot-setup`: мастер обновляет описание инструмента и SRDF. После смены инструмента пересоберите проект и перезапустите симуляцию.

---

## Блок `planning` — планирование движений

Параметры MoveIt 2 и конфигурации траекторного планировщика.

```yaml
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-агентами).

```yaml
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](https://foxglove.dev/) — инструмент визуализации и мониторинга ROS 2 топиков в реальном времени.

```yaml
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-миров |