lightweight-cobot/openspec/specs/fri-control/spec.md

FRI Control

Purpose

Описывает контракт управления физическим iiwa 7 через Sunrise FRI 1.16 и ros2_control, включая синхронизацию циклов, допустимые команды и отказ при потере надёжной связи.

Requirements

Requirement: Разделение циклов

FRI-клиент SHALL выполнять отдельный циклический обмен с Sunrise и синхронизировать его с блокирующим циклом controller_manager.

Scenario: Согласованный период

• WHEN аппаратный режим запускается с robot.fri_cycle_ms=10
• THEN частота controller_manager задаётся равной 100 Гц

Scenario: Несовпадение периода

• WHEN Sunrise сообщает период, отличный от настроенного FRI-периода
• THEN обмен фиксирует ошибку вместо продолжения движения

Requirement: Позиционный интерфейс

Аппаратный интерфейс SHALL предоставлять команду положения для семи суставов и публиковать измеренные положение, скорость, усилие и внешний момент там, где доступны данные FRI.

Scenario: Активное позиционное управление

• WHEN FRI находится в COMMANDING_ACTIVE с POSITION и JOINT overlay
• THEN клиент передаёт полный массив семи суставных положений в радианах

Requirement: Проверка режима и телеметрии

Система MUST отвергать командование при неверном режиме, недостаточном качестве связи, нарушении safety-состояния, неактивных приводах или нечисловой телеметрии.

Scenario: Неверный FRI-режим

• WHEN Sunrise сообщает командный режим, отличный от POSITION с JOINT overlay
• THEN цикл командования завершается ошибкой и не принимает новую цель приложения

Requirement: Ограничение команды

Клиент MUST проверять конечность каждого целевого угла и допустимый диапазон до отправки; между циклами он SHALL ограничивать шаг по настроенной скорости и применять настроенное сглаживание положения.

Scenario: Цель за пределом

• WHEN получена суставная цель вне настроенных пределов
• THEN команда отвергается до вызова FRI setJointPosition

Requirement: Остановка при нарушении цикла

Система MUST считать пропуск FRI-пакета, отсутствие продвижения временной метки, истечение watchdog и выход из COMMANDING_ACTIVE отказом, требующим явного восстановления.

Scenario: Застывший цикл ros2_control

• WHEN FRI-цикл не завершён ros2_control за 100 мс
• THEN FRI worker отмечает отказ и прекращает дальнейшую нормальную выдачу целей

Scenario: Нет готовой сессии

• WHEN сессия не достигла MONITORING_READY за 15 секунд после начала обмена
• THEN инициализация завершается ошибкой