lightweight-cobot/openspec/README.md

Спецификация Lightweight Cobot

Эти базовые OpenSpec-спецификации описывают поведение, обнаруженное в исходном коде и конфигурации на 5 ноября 2026 года. specs/ задаёт текущий контракт системы; будущие изменения следует оформлять в changes/ и после реализации переносить в основные спецификации через архивирование OpenSpec.

Границы системы

CLI cobot / ROS actions / HTTP и MCP / Foxglove и RViz
                ↓
        iiwa_bringup + конфигурация
                ↓
       MoveIt 2 + motion server
                ↓
    joint_trajectory_controller
             ↙           ↘
    Webots ros2_control   FRI hardware interface → Sunrise Cabinet

Физическое движение опирается на штатные функции безопасности контроллера KUKA и наблюдение оператора. Спецификации описывают поведение программного стека, а не сертификацию безопасности ячейки.

Карта контрактов

Раздел	Содержание	Основные источники
deployment	запуск, режимы, конфигурация	cobot/, iiwa_bringup/, setting_loader.py
robot-model	модель, суставы, инструмент и лимиты	iiwa_description/, iiwa_config/, tool_manager.py
fri-control	связь с Sunrise и аппаратный интерфейс	iiwa_controller/, iiwa_sunrise/
simulation	Webots, объекты, камеры	iiwa_bringup/, iiwa_utils/
motion-planning	суставное, декартово и именованное движение	iiwa_msgs/, move_to_pose_server.py
motion-arbitration	приоритет, TCP-гизма и остановка	motion_priority.py, tcp_gizmo.cpp
direct-trajectories	отправка траекторий JSON/CSV	trajectory.py, direct_trajectory.py
external-api	HTTP, MCP и чтение состояния	iiwa_web/, api_endpoints.yaml
motion-sequences	последовательности целей и запись	motion_sequence_runner.py, runner.py
observability	RViz, Foxglove, состояние и диагностика	iiwa_bringup/, iiwa_controller/
sunrise-program	контроллерная программа и выбор сети	iiwa_sunrise/
project-tooling	CLI, сборка и документация	cobot/, scripts/, docker/

Важные различия и открытые вопросы

• cobot-setting.yaml служит локальной конфигурацией. Спецификация ссылается на структуру настроек и значения в src/iiwa_config/config/setting.yaml, но не закрепляет IP и другие локальные параметры как универсальные.
• MoveToPose.action и HTTP POST /robot/move/pose принимают KUKA ABC в радианах. MoveToPose.srv объявляет углы в градусах и скорость в процентах; в основном launch эта служба не поднимается. Перед использованием её контракт надо пересмотреть отдельно.
• Веб-сервер и Foxglove по настройкам могут слушать 0.0.0.0; в просмотренном коде HTTP/MCP не обнаружена прикладная аутентификация. Развёртывание за пределами доверенной сети требует отдельного решения по доступу.
• README обещает WebSocket API; просмотренные исходники iiwa_web явно создают HTTP/FastAPI и MCP. Отдельный WebSocket endpoint в них не найден. Foxglove предоставляет собственный WebSocket bridge.
• Именованные позы home, work, transport являются конфигурациями суставов в SRDF. Их наличие не доказывает безопасность конкретной физической сцены, нагрузки или инструмента.
• Пределы ускорения и рывка в joint_limits.yaml помечены как проектные, а не подтверждённые характеристики KUKA.
• Прямой API траекторий проверяет суставную кинематику и динамику, но не проверяет столкновения с окружением.
• ServerFriRos2 перед FRI выполняет подъезд к заданной в Java позиции. Значения ZERO_POSITION и MONITOR_WORKING_POSITION требуют проверки для каждой физической ячейки.
• При заданном bag_path runner удаляет существующий каталог записи перед созданием нового MCAP; путь записи нельзя указывать на данные, которые нужно сохранить.

Проверка структуры

openspec list --specs
openspec validate --specs --strict