# ServerFriRos2

**ServerFriRos2** — программа для контроллера KUKA Sunrise Cabinet, которая создаёт FRI-соединение между роботом KUKA LBR iiwa и компьютером с ROS 2. Через это соединение `ros2_control` получает текущее состояние робота и, в зависимости от выбранного режима, передаёт контроллеру команды движения.

Именно эта программа связывает две части системы: приложение на контроллере KUKA и управляющий узел ROS 2 на внешнем компьютере. Без запущенного `ServerFriRos2` управлять физическим роботом через ROS 2 не получится.

Программа проверена на KUKA LBR iiwa 7 R800 с Sunrise OS 1.16 и FRI 1.16. Исходный код находится в проекте по пути [`src/iiwa_sunrise/src/ServerFriRos2.java`](https://github.com/Daniel-Robotic/lightweight-cobot/blob/dev/src/iiwa_sunrise/src/ServerFriRos2.java).

Общие сведения о канале обмена приведены в разделе [FRI-протокол](../../../getting-started/concepts/fri-protocol.md), а подключение кабелей и подготовка Sunrise-проекта описаны в [настройке SunriseWorkbench](../../../getting-started/sunrise-setup.md).

!!! warning "Перед запуском"
    Проверьте, что выбранные исходные положения безопасны для установленного инструмента и рабочей ячейки. Во время автоматического перемещения рабочая зона должна оставаться свободной. Режимы импедансного управления и ручного ведения не заменяют штатные функции безопасности KUKA.

## Что необходимо настроить

Перед синхронизацией проекта с контроллером откройте `ServerFriRos2.java` в Sunrise Workbench и проверьте параметры своего стенда.

### Сетевые адреса

В Java-классе задаются адреса **компьютера с ROS 2**, доступные со стороны соответствующего интерфейса контроллера:

```java
private static final String KONI_IP = "192.170.10.10";
private static final String KLI_IP  = "192.168.21.31";
```

Не путайте их с параметром `robot.ip` в `cobot-setting.yaml`: там указывается адрес **контроллера KUKA**, к которому обращается ROS 2-компьютер. Настройка этого файла подробно описана в разделе [Конфигурация системы](../../../getting-started/configuration.md).

### Инструмент и данные нагрузки

Программа подключает к фланцу инструмент, указанный в аннотации `@Named`:

```java
@Named("tool1")
private Tool _tool;
```

Замените `tool1` именем своего инструмента из **Sunrise Workbench → Object Templates**. Для режима Monitor обязательно заполните **Load Data**: массу, центр масс и тензор инерции. Программа проверяет эти параметры перед включением гравитационной компенсации и предупреждает оператора, если модель нагрузки заполнена неправильно.

О калибровке и проверке нагрузки можно прочитать в разделе [Данные нагрузки](../features/robot-menu.md).

### Исходные положения

Перед запуском FRI робот автоматически занимает одну из заданных суставных позиций:

```java
private static final double[] ZERO_POSITION =
    {0, 0, 0, 0, 0, 0, 0};

private static final double[] MONITOR_WORKING_POSITION =
    {0, 0, 0, -1.57, 0, 1.57, 0};
```

`ZERO_POSITION` используется в режимах Position и JointImpedance. В режиме Monitor робот сначала проходит через нулевое положение, а затем переходит в `MONITOR_WORKING_POSITION`. При необходимости измените эти массивы так, чтобы движение не приводило к столкновению с оснасткой, столом или установленным инструментом.

### Период FRI

Для режимов Position и JointImpedance значение, выбранное на smartPAD, должно совпадать с `robot.fri_cycle_ms` в `cobot-setting.yaml`:

| Выбранный период | Частота обмена | Когда использовать |
|---|---:|---|
| 10 мс | 100 Гц | Стандартный и наиболее устойчивый вариант; обязателен для KLI. |
| 5 мс | 200 Гц | Более частое управление через выделенный интерфейс KONI. |

Monitor использует фиксированный период 2 мс и не показывает отдельный диалог выбора периода.

## Запуск приложения

Откройте раздел [Приложения](../features/applications.md) на smartPAD, найдите `ServerFriRos2` в списке приложений робота и активируйте его. После выбора программа появится в верхней строке smartHMI.

![Выбор ServerFriRos2 в списке приложений](../../assets/programms/server_fri_ros2/apps.png)

Для запуска нажмите зелёную кнопку **Старт** на smartPAD. Программа последовательно предложит выбрать сетевой интерфейс, режим управления и, если это требуется, дополнительные параметры FRI.

## Шаг 1. Выбор сетевого интерфейса

В первом диалоге отображаются настроенные адреса ROS 2-компьютера. Выберите интерфейс, к которому физически подключён управляющий компьютер.

![Выбор сетевого интерфейса FRI](../../assets/programms/server_fri_ros2/chose-interface.png)

| Интерфейс | Особенности | Доступные режимы | Период |
|---|---|---|---|
| **KONI (X66)** | Выделенная сеть FRI, рекомендуемый вариант | Position, JointImpedance, Monitor | 5 или 10 мс; Monitor — 2 мс |
| **KLI (X6)** | Общая управляющая сеть, резервный вариант | Position, JointImpedance | Только 10 мс |

KONI лучше подходит для управления в реальном времени: выделенный канал обеспечивает меньшую задержку и более стабильный цикл. KLI можно использовать, когда KONI недоступен, но из-за задержек общей сети режим Monitor через него отключён.

## Шаг 2. Выбор режима управления

Набор доступных кнопок зависит от выбранного сетевого интерфейса.

При работе через KLI можно выбрать только Position или JointImpedance:

![Выбор режима управления через KLI](../../assets/programms/server_fri_ros2/chose-interface-kli.png)

При работе через KONI дополнительно доступен Monitor:

![Выбор режима управления через KONI](../../assets/programms/server_fri_ros2/koni-choose-mode.png)

### Position

Position — основной режим для обычного управления из ROS 2, включая выполнение траекторий MoveIt. Контроллер точно следует позиционным командам, а регулирование жёсткости суставов в этом режиме недоступно.

После выбора параметров робот перемещается в `ZERO_POSITION`, создаёт FRI-сессию в командном режиме `POSITION` и ожидает подключения ROS 2-клиента.

![Ожидание ROS 2-клиента в режиме Position](../../assets/programms/server_fri_ros2/pose-start.png)

### JointImpedance

JointImpedance также получает из ROS 2 команды положения, но выполняет их с заданной жёсткостью суставов. Такой режим используется, когда необходимо управлять механическим импедансом робота, сохраняя следование заданной траектории.

После выбора режима программа предлагает установить одинаковую жёсткость для всех семи суставов:

![Выбор жёсткости суставов](../../assets/programms/server_fri_ros2/koni-choose-jointImpedance-stiffnes.png)

| Жёсткость | Поведение робота |
|---:|---|
| 1500 Н·м/рад | Наиболее жёсткое следование командам из доступных вариантов. |
| 1000 Н·м/рад | Высокая жёсткость суставов. |
| 800 Н·м/рад | Средняя жёсткость суставов. |
| 500 Н·м/рад | Наиболее мягкое поведение из доступных вариантов. |

Демпфирование во всех суставах задаётся программой на уровне 0,7. После настройки робот переходит в `ZERO_POSITION` и ожидает FRI-клиента, как и в режиме Position.

![Ожидание ROS 2-клиента в режиме JointImpedance](../../assets/programms/server_fri_ros2/jointmpedance-start.png)

### Monitor

Monitor предназначен для ручного ведения робота и передачи его текущего состояния в ROS 2. Компьютер не отправляет команды движения: FRI-сессия работает в `NO_COMMAND_MODE`, а контроллер передаёт положения и моменты суставов с периодом 2 мс.

Перед подключением робот проходит через `ZERO_POSITION` в `MONITOR_WORKING_POSITION`. Затем программа проверяет Load Data инструмента и включает суставной импеданс с нулевой жёсткостью и демпфированием 0,7. Благодаря гравитационной компенсации робот можно аккуратно перемещать рукой.

Перед подтверждением диалога запустите ROS 2-узел на компьютере. Нажимайте **OK — ROS2 готов** только после появления активного `ros2_control_node`.

![Запуск ROS 2-клиента для режима Monitor](../../assets/programms/server_fri_ros2/monitor-start.png)

!!! danger "Monitor и модель нагрузки"
    Не включайте ручное ведение с неверными параметрами инструмента. Ошибка в массе, центре масс или инерции приводит к неточной гравитационной компенсации: робот может сопротивляться оператору или самопроизвольно смещаться.

## Шаг 3. Выбор периода отправки

При выборе Position или JointImpedance через KONI программа предлагает период 10 или 5 мс. Для KLI этот шаг пропускается, потому что период автоматически фиксируется на 10 мс.

![Выбор периода отправки FRI](../../assets/programms/server_fri_ros2/koni-choose-pose-and-jointImpedance-time.png)

Если нет особых требований к частоте управления, начните с 10 мс. Период 5 мс имеет смысл использовать через KONI для задач, которым действительно нужен цикл 200 Гц.

## Подключение ROS 2

На ROS 2-компьютере запустите систему для физического робота командой:

```bash
cobot run
```

При запуске выберите работу с реальным роботом. Команда поднимает `ros2_control_node`, аппаратный интерфейс FRI, контроллеры, MoveIt и настроенные дополнительные сервисы. Подробное описание команды приведено в разделе [CLI-команды cobot](../../../getting-started/cli-reference.md), а способы отправки команд — в разделе [Управление через ROS 2](../../../getting-started/control/ros2-control.md).

Для наиболее надёжного запуска сначала выполните `cobot run` на компьютере, а затем запустите `ServerFriRos2` на smartPAD. Если приложение KUKA уже перешло к ожиданию клиента, ROS 2 необходимо запустить в течение 30 секунд. После таймаута программа закроет созданную FRI-сессию и сообщит об ошибке в журнале.

После соединения в журнале smartHMI отображаются:

- состояние FRI-сессии;
- качество соединения;
- задержка (`latency`);
- разброс времени доставки пакетов (`jitter`).

При остановке FRI-клиента сессия закрывается, активный режим завершается, а ресурсы соединения освобождаются. Для нового подключения снова запустите приложение на smartPAD.

## Если соединение не устанавливается

В первую очередь проверьте:

1. Выбран ли тот интерфейс, к которому подключён ROS 2-компьютер.
2. Соответствуют ли `KONI_IP` или `KLI_IP` адресу компьютера в выбранной сети.
3. Указан ли в `cobot-setting.yaml` адрес контроллера KUKA, а не компьютера.
4. Совпадает ли период 5/10 мс в Java-программе и `robot.fri_cycle_ms`.
5. Запущен ли `ros2_control_node` до истечения 30-секундного таймаута.
6. Настроен ли UDP-порт FRI `30200` и не блокируется ли он межсетевым экраном.

Если приложение не запускается из-за потерянной конфигурации инструмента или фреймов, воспользуйтесь разделом [Ошибка конфигурации](../../../troubleshooting/config-error.md).