55 lines
3.7 KiB
Markdown
55 lines
3.7 KiB
Markdown
# External API
|
|
|
|
## Purpose
|
|
|
|
Фиксирует доступные внешним клиентам HTTP и MCP операции для чтения состояния и отправки команд роботу, включая типы данных, проверку ввода и ошибки зависимостей ROS.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Включаемый сервер
|
|
При `web.enabled=true` система SHALL запускать FastAPI на настроенных `host` и `port`, предоставлять OpenAPI-описание и монтировать MCP-приложение по `/mcp`.
|
|
|
|
#### Scenario: Веб-сервер включён
|
|
- **WHEN** основной launch загружает `web.enabled=true`
|
|
- **THEN** запускается `iiwa_web_server` с путями к конфигурации эндпоинтов и суставных лимитов
|
|
|
|
### Requirement: Конфигурируемые маршруты
|
|
Маршруты из `api_endpoints.yaml` SHALL создавать HTTP обработчики типов `topic`, `service`, `action`, `fk` и `tf` с описанными полями и тайм-аутами.
|
|
|
|
#### Scenario: Отключённый маршрут
|
|
- **WHEN** запись маршрута имеет `enabled=false`
|
|
- **THEN** маршрут не появляется в доступном HTTP API
|
|
|
|
### Requirement: Чтение состояния
|
|
`GET /robot/joint_states` SHALL возвращать имена, положения, скорости и усилия из `/joint_states`; `GET /robot/pose` SHALL возвращать TCP относительно `base_link`, XYZ в метрах, кватернион и KUKA ABC в радианах и градусах.
|
|
|
|
#### Scenario: Нет сообщения суставов
|
|
- **WHEN** `/joint_states` не поступает до тайм-аута маршрута
|
|
- **THEN** запрос чтения состояния возвращает HTTP 503
|
|
|
|
### Requirement: Команды движения через HTTP
|
|
`POST /robot/move/joints`, `/robot/move/pose` и `/robot/move/named` SHALL передавать проверенные цели в соответствующие ROS action или service и возвращать `success` и `message`.
|
|
|
|
#### Scenario: Некорректная длина суставов
|
|
- **WHEN** тело запроса `/robot/move/joints` содержит не семь углов
|
|
- **THEN** запрос получает 422 и ROS action не вызывается
|
|
|
|
#### Scenario: Нет ROS-сервера
|
|
- **WHEN** соответствующий ROS action или service недоступен до тайм-аута
|
|
- **THEN** HTTP обработчик возвращает 503
|
|
|
|
### Requirement: Единицы HTTP-позы
|
|
`POST /robot/move/pose` SHALL принимать XYZ в метрах и A/B/C в радианах по соглашению ZYX; `speed` SHALL лежать в `[0.01, 1.0]`.
|
|
|
|
#### Scenario: Выбор планировщика без учёта регистра
|
|
- **WHEN** клиент указывает `planner="PTP"`
|
|
- **THEN** маршрут нормализует ключ до `ptp` до отправки action-цели
|
|
|
|
### Requirement: MCP-представление
|
|
MCP-приложение SHALL строиться из тех же FastAPI-маршрутов, которые зарегистрированы для HTTP управления и чтения.
|
|
|
|
#### Scenario: Запрос каталога инструментов MCP
|
|
- **WHEN** MCP-клиент подключается к `/mcp`
|
|
- **THEN** операции, выведенные из маршрутов FastAPI, доступны через MCP-приложение
|
|
|