grabardm/lightweight-cobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Добавлена документация по CLI-командам, конфигурации системы, управлению через Foxglove Studio и REST API, а также инструкции по установке и удалённому доступу к серверу. Включены разделы о настройке SunriseWorkbench для работы с реальным роботом KUKA LBR IIWA 7.

Browse Source
This commit is contained in:
Даниил Грабарь
2026-06-20 13:15:56 +03:00
parent ed02b59177
commit a983a06e41
11 changed files with 1271 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/lwc-doc/docs/getting-started/cli-reference.md
+165
View File
@@ -0,0 +1,165 @@
# CLI-команды cobot
`cobot` — единая точка входа для управления всем проектом. Все операции с роботом, симулятором, Docker-контейнерами и документацией выполняются через эту команду.
## Справка
```bash
cobot -h
```
Вывод справки разделён на 4 группы команд:
- **Setup commands** — настройка системы
- **Run commands** — запуск проекта
- **Build commands** — сборка ROS 2
- **Management commands** — управление пакетом
Некоторые команды имеют собственные подкоманды. Пример:
```bash
cobot doc-setup rebuild # подкоманда rebuild для doc-setup
cobot doc-setup --help # справка по подкомандам конкретной команды
```
---
## Setup commands
Команды первичной и повторной настройки системы.
### `cobot setup`
Мастер-команда первого запуска. Последовательно вызывает все `*-setup` команды по очереди: настраивает документацию, среду выполнения и параметры робота.
```bash
cobot setup
```
Используйте эту команду при первой установке вместо ручного запуска каждой setup-команды.
---
### `cobot local-setup`
Локальная установка ROS 2 Jazzy без Docker: скачивает зависимости через `rosdep`, собирает workspace через `colcon`.
```bash
cobot local-setup
```
!!! note
После выполнения обязательно выполните `source ~/.bashrc` или откройте новый терминал.
---
### `cobot docker-setup`
Сборка или скачивание готовых Docker-образов для запуска проекта в изоляции. Доступны два варианта:
- **Сборка из Dockerfile** — дольше, но даёт актуальную версию
- **Скачивание готового образа** — быстрее, использует pre-built образ
```bash
cobot docker-setup
```
---
### `cobot doc-setup`
Разворачивает локальный MkDocs-сервер документации — полную копию [онлайн-документации](https://daniel-robotics.gitverse.site/lightweight-cobot/).
```bash
cobot doc-setup # запустить / собрать документацию
cobot doc-setup rebuild # пересобрать документацию
```
После запуска документация будет доступна по адресу `http://localhost:8000`.
---
### `cobot robot-setup`
Интерактивный мастер настройки файла `cobot-setting.yaml`. Запрашивает IP-адрес робота, порт FRI, активный инструмент и другие параметры.
```bash
cobot robot-setup
```
!!! tip
Используйте именно эту команду для изменения конфигурации — она валидирует введённые значения и исключает синтаксические ошибки. Подробнее о параметрах — в разделе [Конфигурация системы](configuration.md).
---
## Run commands
### `cobot run`
Запускает весь стек: hardware interface, MoveIt 2, RViz и опциональные компоненты (Foxglove, REST API). При запуске предлагает выбор:
- **Docker или локально**
- **Симулятор (Webots) или реальный робот**
```bash
cobot run # интерактивный выбор режима
cobot run --simulate # принудительно запустить симулятор
```
---
## Build commands
### `cobot rebuild`
Пересборка ROS 2 workspace через `colcon`. Используется при изменении исходного кода пакетов.
```bash
cobot rebuild
```
!!! note
Работает только для локальной установки (не Docker). Эквивалент `colcon build --mixin release`.
---
### `cobot clean`
Удаляет сгенерированные папки сборки. Предлагает выбор, какие именно удалить:
- `build/` — артефакты компиляции
- `install/` — установленные файлы пакетов
- `log/` — логи сборки
```bash
cobot clean
```
---
## Management commands
### `cobot update`
Скачивает последнюю версию проекта с GitVerse и переустанавливает CLI `cobot`.
```bash
cobot update
```
---
### `cobot delete`
Удаляет компоненты проекта с системы. Предложит выбор: удалить только проект, Docker-образы и контейнеры, или также ROS 2.
```bash
cobot delete
```
!!! danger
Операция необратима. Удалённые файлы и Docker-образы потребуют повторной установки.
---
**Следующий шаг:** [Конфигурация системы](configuration.md)
doc/lwc-doc/docs/getting-started/configuration.md
+174
View File
@@ -0,0 +1,174 @@
# Конфигурация системы
## Главный конфигурационный файл
Все параметры системы хранятся в одном файле — **`cobot-setting.yaml`** в корне проекта.
Это единственный источник истины для IP-адреса робота, портов, путей к конфигам, настроек планировщика и веб-сервера.
!!! 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
joint_position_tau: 0.04
joint_velocity_tau: 0.01
active_controller: "jtc"
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-фильтр позиций [с] — сглаживает команды перед отправкой | Уменьшать для более быстрой реакции, увеличивать при вибрациях |
| `joint_velocity_tau` | EMA-фильтр скорости [с] — убирает выбросы конечных разностей | Аналогично `joint_position_tau` |
| `active_controller` | Режим управления: `jtc` (MoveIt / JointTrajectory) или `forward` (прямое управление) | `jtc` для большинства задач |
| `description` | Путь к URDF-описанию робота | Не менять |
---
## Блок `digital_twin` — симулятор
Настройки виртуальной среды Webots и визуализации в RViz.
```yaml
digital_twin:
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 |
---
## Блок `tool` — активный инструмент
Указывает, какой захват или инструмент закреплён на роботе.
```yaml
tool:
active: "patron"
```
| Значение | Описание |
|---|---|
| `none` | Без инструмента |
| `patron` | Захват «Patron» (патрон) |
Список доступных инструментов находится в файле `src/iiwa_config/config/tools.yaml`. Для добавления нового инструмента необходимо описать его там, после чего указать имя в `tool.active`.
---
## Блок `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`), если веб-интерфейс не нужен |
| ⚠️ | `robot.active_controller` | Менять только при намеренном переключении режима управления |
| ⚠️ | `planning.*` | Менять при необходимости другого планировщика или параметров |
| ❌ | `robot.description` | Не трогать — путь к URDF |
| ❌ | `controller.moveit.*` | Не трогать — пути к конфигам MoveIt внутри пакетов |
| ❌ | `digital_twin.webots.world` | Не трогать без знания структуры Webots-миров |
doc/lwc-doc/docs/getting-started/control/foxglove.md
+10
View File
@@ -0,0 +1,10 @@
# Управление через Foxglove Studio
!!! info "Раздел в разработке"
Подробная документация по управлению и мониторингу через Foxglove Studio готовится.
[Foxglove Studio](https://foxglove.dev/home) — инструмент визуализации и мониторинга ROS2-данных в реальном времени. Подключается к запущенному стеку через WebSocket-bridge (порт `8765` по умолчанию, настраивается в `cobot-setting.yaml` → блок `foxglove`).
## Скачать Foxglove Studio
Перейдите на [официальный сайт Foxglove](https://foxglove.dev/home) и скачайте приложение для своей ОС.
doc/lwc-doc/docs/getting-started/control/rest-api.md
+573
View File
@@ -0,0 +1,573 @@
# Управление через REST API
REST API предоставляет HTTP-интерфейс для управления роботом из любой среды: Bash, Python, MATLAB, Postman и других инструментов.
## Веб-панель (Swagger UI)
Интерактивная документация со встроенным тест-клиентом доступна по адресу:
- **Локально:** [http://localhost:8007/docs](http://localhost:8007/docs)
- **Удалённо:** `http://ip-сервера:8007/docs`
---
## Подготовка к работе
!!! tip "Не знакомы с инструментами?"
- **Bash / curl** — [введение в Bash-скрипты](https://easy-quest.github.io/my-docs/en/docs/Bash-x/bash_scripts_001/)
- **Python** — [руководство для начинающих](https://metanit.com/python/tutorial/) или [официальная документация](https://docs.python.org/3/)
- **MATLAB** — [официальная документация MATLAB](https://www.mathworks.com/help/matlab/index.html)
### Константы
Для Python и MATLAB определите константы в начале скрипта. Для Bash они указываются непосредственно в командах.
=== "Python"
```python
import httpx, math
HOST = "http://localhost:8007"
T_FAST = 10 # тайм-аут для чтения состояния [с]
T_MOVE = 60 # тайм-аут для команд движения [с]
```
=== "MATLAB"
```matlab
HOST = 'http://localhost:8007';
T_FAST = 10;
T_MOVE = 60;
```
---
## Эндпоинты
### 1. GET `/robot/joint_states` — углы суставов
Возвращает текущие значения углов (в радианах) всех 7 суставов.
Используйте для мониторинга положения робота перед отправкой команд.
=== "Bash"
```bash
curl -s --max-time 10 http://localhost:8007/robot/joint_states | python3 -m json.tool
```
=== "Python"
```python
r = httpx.get(f"{HOST}/robot/joint_states", timeout=T_FAST)
print(r.json()["position"])
```
=== "MATLAB"
```matlab
r = webread([HOST '/robot/joint_states'], weboptions('Timeout', T_FAST));
disp(r.position)
```
---
### 2. GET `/robot/pose` — текущая поза TCP
Возвращает декартову позу инструментального центра (TCP): координаты `x, y, z` [м] и ориентацию в углах Эйлера [градусы].
Используйте для контроля положения инструмента в пространстве.
=== "Bash"
```bash
curl -s --max-time 10 http://localhost:8007/robot/pose | python3 -m json.tool
```
=== "Python"
```python
r = httpx.get(f"{HOST}/robot/pose", timeout=T_FAST)
pose = r.json()
print(pose)
```
=== "MATLAB"
```matlab
r = webread([HOST '/robot/pose'], weboptions('Timeout', T_FAST));
fprintf('x=%.4f y=%.4f z=%.4f\n', r.position.x, r.position.y, r.position.z);
fprintf('A=%.4f B=%.4f C=%.4f\n', r.orientation.euler_deg.a, r.orientation.euler_deg.b, r.orientation.euler_deg.c);
```
---
### 3. GET `/robot/positions` — именованные позиции
Возвращает список всех сохранённых именованных позиций (name + description).
Используйте для получения допустимых значений для `/robot/move/named`.
=== "Bash"
```bash
curl -s --max-time 10 http://localhost:8007/robot/positions
```
=== "Python"
```python
r = httpx.get(f"{HOST}/robot/positions", timeout=T_FAST)
for pos in r.json():
print(pos["name"], "—", pos["description"])
```
=== "MATLAB"
```matlab
r = webread([HOST '/robot/positions'], weboptions('Timeout', T_FAST));
for i = 1:numel(r)
fprintf('%s — %s\n', r(i).name, r(i).description);
end
```
---
### 4. POST `/robot/stop` — экстренная остановка
Немедленно останавливает текущее движение робота.
Используйте при необходимости прервать выполняемую команду.
=== "Bash"
```bash
curl -s --max-time 10 -X POST http://localhost:8007/robot/stop
```
=== "Python"
```python
r = httpx.post(f"{HOST}/robot/stop", timeout=T_FAST)
print(r.json())
```
=== "MATLAB"
```matlab
opts = weboptions('RequestMethod', 'post', 'MediaType', 'application/json', 'Timeout', T_FAST);
r = webwrite([HOST '/robot/stop'], struct(), opts);
disp(r.success)
```
---
### 5. POST `/robot/move/named` — движение в именованную позицию
Перемещает робота в одну из заранее сохранённых позиций (см. `/robot/positions`).
Используйте для воспроизводимых переходов между рабочими позициями.
| Параметр | Тип | Описание |
|---|---|---|
| `name` | string | Имя позиции |
| `speed` | float | Масштаб скорости (0.0–1.0) |
| `accel_scale` | float | Масштаб ускорения (0.0 = по умолчанию) |
=== "Bash"
```bash
curl -s --max-time 60 -X POST http://localhost:8007/robot/move/named \
-H "Content-Type: application/json" \
-d '{"name": "home", "speed": 0.1, "accel_scale": 0.0}'
```
=== "Python"
```python
r = httpx.post(f"{HOST}/robot/move/named",
json={"name": "home", "speed": 0.1, "accel_scale": 0.0},
timeout=T_MOVE)
print(r.json())
```
=== "MATLAB"
```matlab
opts = weboptions('RequestMethod', 'post', 'MediaType', 'application/json', 'Timeout', T_MOVE);
body = struct('name', 'home', 'speed', 0.1, 'accel_scale', 0.0);
r = webwrite([HOST '/robot/move/named'], body, opts);
disp(r.success)
```
---
### 6. POST `/robot/move/pose` — движение по декартовой позе
Перемещает TCP в заданную точку пространства. Ориентация задаётся углами Эйлера (A, B, C) в радианах.
Используйте когда нужно задать точное положение и ориентацию инструмента.
| Параметр | Тип | Описание |
|---|---|---|
| `x, y, z` | float | Координаты [м] |
| `a, b, c` | float | Углы Эйлера [рад] |
| `speed` | float | Масштаб скорости (0.0–1.0) |
| `planner` | string | Планировщик: `ptp`, `lin`, `circ` |
| `frame_id` | string | Система отсчёта (пусто = `base_link`) |
=== "Bash"
```bash
curl -s --max-time 60 -X POST http://localhost:8007/robot/move/pose \
-H "Content-Type: application/json" \
-d '{"x": 0.4, "y": 0.0, "z": 0.5, "a": 0.0, "b": 3.14159, "c": 0.0, "speed": 0.1, "planner": "ptp"}'
```
=== "Python"
```python
r = httpx.post(f"{HOST}/robot/move/pose",
json={"x": 0.4, "y": 0.0, "z": 0.5,
"a": 0.0, "b": math.pi, "c": 0.0,
"speed": 0.1, "planner": "ptp", "frame_id": ""},
timeout=T_MOVE)
print(r.json())
```
=== "MATLAB"
```matlab
opts = weboptions('RequestMethod', 'post', 'MediaType', 'application/json', 'Timeout', T_MOVE);
body = struct('x', 0.4, 'y', 0.0, 'z', 0.5, ...
'a', 0.0, 'b', pi, 'c', 0.0, ...
'speed', 0.1, 'planner', 'ptp', 'frame_id', '');
r = webwrite([HOST '/robot/move/pose'], body, opts);
disp(r.success)
```
---
### 7. POST `/robot/move/joints` — движение по углам суставов
Перемещает робота в позицию, заданную углами всех 7 суставов (в радианах).
Используйте когда нужен прямой контроль над конфигурацией робота без планирования в декартовом пространстве.
| Параметр | Тип | Описание |
|---|---|---|
| `joints` | float[7] | Углы суставов J1–J7 [рад] |
| `speed` | float | Масштаб скорости (0.0–1.0) |
=== "Bash"
```bash
curl -s --max-time 60 -X POST http://localhost:8007/robot/move/joints \
-H "Content-Type: application/json" \
-d '{"joints": [0.0, 0.5, 0.0, -1.5708, 0.0, 1.5708, 0.0], "speed": 0.1}'
```
=== "Python"
```python
r = httpx.post(f"{HOST}/robot/move/joints",
json={"joints": [0.0, 0.5, 0.0, -math.pi/2, 0.0, math.pi/2, 0.0],
"speed": 0.1},
timeout=T_MOVE)
print(r.json())
```
=== "MATLAB"
```matlab
opts = weboptions('RequestMethod', 'post', 'MediaType', 'application/json', 'Timeout', T_MOVE);
body = struct('joints', {{0.0, 0.5, 0.0, -pi/2, 0.0, pi/2, 0.0}}, 'speed', 0.1);
r = webwrite([HOST '/robot/move/joints'], body, opts);
disp(r.success)
```
---
### 8. POST `/trajectory/send` — отправка траектории
Выполняет многоточечную траекторию, заданную набором waypoints с метками времени.
Используйте для плавного воспроизведения записанных или синтезированных движений.
| Параметр | Тип | Описание |
|---|---|---|
| `points[].positions` | float[7] | Углы суставов в точке [рад] |
| `points[].time_from_start` | float | Время от старта [с] |
| `validate_limits` | bool | Проверять ли ограничения суставов |
=== "Bash"
```bash
curl -s --max-time 60 -X POST http://localhost:8007/trajectory/send \
-H "Content-Type: application/json" \
-d '{
"points": [
{"positions": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], "time_from_start": 0.0},
{"positions": [0.0, 0.5, 0.0, -1.0, 0.0, 1.0, 0.0], "time_from_start": 3.0},
{"positions": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], "time_from_start": 6.0}
],
"validate_limits": true
}'
```
=== "Python"
```python
r = httpx.post(f"{HOST}/trajectory/send",
json={
"points": [
{"positions": [0.0]*7, "time_from_start": 0.0},
{"positions": [0.0, 0.5, 0.0, -1.0, 0.0, 1.0, 0.0], "time_from_start": 3.0},
{"positions": [0.0]*7, "time_from_start": 6.0},
],
"validate_limits": True,
},
timeout=T_MOVE)
print(r.json())
```
=== "MATLAB"
```matlab
opts = weboptions('RequestMethod', 'post', 'MediaType', 'application/json', 'Timeout', T_MOVE);
p1 = struct('positions', {{0,0,0,0,0,0,0}}, 'time_from_start', 0.0);
p2 = struct('positions', {{0,0.5,0,-1.0,0,1.0,0}}, 'time_from_start', 3.0);
p3 = struct('positions', {{0,0,0,0,0,0,0}}, 'time_from_start', 6.0);
body = struct('points', {{p1, p2, p3}}, 'validate_limits', true);
r = webwrite([HOST '/trajectory/send'], body, opts);
disp(r)
```
---
### 9. POST `/trajectory/send_csv` — загрузка траектории из CSV
Загружает траекторию из CSV-файла и выполняет её. Формат файла: строки — точки, столбцы — углы суставов + время.
Используйте для воспроизведения траекторий, подготовленных во внешних инструментах.
=== "Bash"
```bash
curl -s --max-time 60 -X POST http://localhost:8007/trajectory/send_csv \
-F "file=@trajectory.csv" \
-F "separator=," \
-F "validate_limits=true"
```
=== "Python"
```python
with open("trajectory.csv", "rb") as f:
r = httpx.post(f"{HOST}/trajectory/send_csv",
files={"file": ("trajectory.csv", f, "text/csv")},
data={"separator": ",", "validate_limits": "true"},
timeout=T_MOVE)
print(r.json())
```
=== "MATLAB"
!!! warning "Требует уточнения"
Код ниже использует `matlab.net.http` и может потребовать доработки в зависимости от вашей версии MATLAB.
```matlab
import matlab.net.http.*
import matlab.net.http.io.*
csvData = fileread('trajectory.csv');
part = FormProvider(FormField('file', csvData, 'filename', 'trajectory.csv', ...
'content-type', 'text/csv'), ...
FormField('separator', ','), ...
FormField('validate_limits', 'true'));
req = RequestMessage('POST', [], part);
opts = matlab.net.http.HTTPOptions('ConnectTimeout', T_MOVE, 'ResponseTimeout', T_MOVE);
[resp, ~] = req.send([HOST '/trajectory/send_csv'], opts);
disp(resp.Body.Data)
```
---
### 10. POST `/trajectory/stop` — остановка траектории
Прерывает выполнение текущей траектории.
Используйте для аварийной остановки во время воспроизведения.
=== "Bash"
```bash
curl -s --max-time 10 -X POST http://localhost:8007/trajectory/stop
```
=== "Python"
```python
r = httpx.post(f"{HOST}/trajectory/stop", timeout=T_FAST)
print(r.json())
```
=== "MATLAB"
```matlab
opts = weboptions('RequestMethod', 'post', 'Timeout', T_FAST);
r = webread([HOST '/trajectory/stop'], opts);
disp(r)
```
---
### 11. GET `/trajectory/logs` — лог выполнения траектории
Возвращает последние `n` строк лога выполнения траектории.
Используйте для диагностики после выполнения команды.
=== "Bash"
```bash
curl -s --max-time 10 "http://localhost:8007/trajectory/logs?n=20"
```
=== "Python"
```python
r = httpx.get(f"{HOST}/trajectory/logs", params={"n": 20}, timeout=T_FAST)
for line in r.json()["lines"]:
print(line)
```
=== "MATLAB"
```matlab
r = webread([HOST '/trajectory/logs'], weboptions('Timeout', T_FAST), 'n', 20);
disp(r.lines)
```
---
### 12. POST `/sequences/start` — запуск последовательности движений
Запускает автоматическую последовательность движений из JSON-конфига (`motion_sequence_config.json`).
Используйте для воспроизведения повторяющихся циклов работы.
| Параметр | Тип | Описание |
|---|---|---|
| `config` | file | JSON-файл конфигурации последовательности |
| `n_iterations` | int | Число повторений (0 = бесконечно) |
| `delay_between_iterations` | float | Пауза между итерациями [с] |
=== "Bash"
```bash
curl -s --max-time 10 -X POST http://localhost:8007/sequences/start \
-F "config=@motion_sequence_config.json" \
-F "n_iterations=3" \
-F "delay_between_iterations=5.0"
```
=== "Python"
```python
with open("motion_sequence_config.json", "rb") as f:
r = httpx.post(f"{HOST}/sequences/start",
files={"config": ("config.json", f, "application/json")},
data={"n_iterations": "3", "delay_between_iterations": "5.0"},
timeout=T_FAST)
print(r.json())
```
=== "MATLAB"
!!! warning "Требует уточнения"
Код ниже использует `matlab.net.http` и может потребовать доработки в зависимости от вашей версии MATLAB.
```matlab
import matlab.net.http.*
import matlab.net.http.io.*
jsonData = fileread('motion_sequence_config.json');
part = FormProvider(FormField('config', jsonData, 'filename', 'config.json', ...
'content-type', 'application/json'), ...
FormField('n_iterations', '3'), ...
FormField('delay_between_iterations', '5.0'));
req = RequestMessage('POST', [], part);
opts = matlab.net.http.HTTPOptions('ConnectTimeout', T_FAST, 'ResponseTimeout', T_FAST);
[resp, ~] = req.send([HOST '/sequences/start'], opts);
disp(resp.Body.Data)
```
---
### 13. GET `/sequences/status` — статус последовательности
Возвращает текущий статус выполнения последовательности.
Используйте для polling-мониторинга выполнения.
=== "Bash"
```bash
curl -s --max-time 10 http://localhost:8007/sequences/status
```
=== "Python"
```python
r = httpx.get(f"{HOST}/sequences/status", timeout=T_FAST)
print(r.json())
```
=== "MATLAB"
```matlab
r = webread([HOST '/sequences/status'], weboptions('Timeout', T_FAST));
disp(r.status)
```
---
### 14. GET `/sequences/logs` — лог последовательности
Возвращает последние `n` строк лога выполнения последовательности.
=== "Bash"
```bash
curl -s --max-time 10 "http://localhost:8007/sequences/logs?n=50"
```
=== "Python"
```python
r = httpx.get(f"{HOST}/sequences/logs", params={"n": 50}, timeout=T_FAST)
for line in r.json()["lines"]:
print(line)
```
=== "MATLAB"
```matlab
r = webread([HOST '/sequences/logs'], weboptions('Timeout', T_FAST), 'n', 50);
disp(r.lines)
```
---
### 15. POST `/sequences/stop` — остановка последовательности
Прерывает выполнение текущей последовательности движений.
=== "Bash"
```bash
curl -s --max-time 10 -X POST http://localhost:8007/sequences/stop
```
=== "Python"
```python
r = httpx.post(f"{HOST}/sequences/stop", timeout=T_FAST)
print(r.json())
```
=== "MATLAB"
```matlab
opts = weboptions('RequestMethod', 'post', 'Timeout', T_FAST);
r = webread([HOST '/sequences/stop'], opts);
disp(r)
```
doc/lwc-doc/docs/getting-started/control/ros2-control.md
+11
View File
@@ -0,0 +1,11 @@
# Управление через ROS2
!!! info "Раздел в разработке"
Подробная документация по управлению через ROS2-топики и action-серверы готовится.
Этот способ предполагает прямую отправку команд в ROS2 через CLI-инструменты (`ros2 topic pub`, `ros2 action send_goal`) или написание собственных ROS2-нод на Python/C++.
## Дополнительные ресурсы
- [Документация ROS2 Jazzy](https://docs.ros.org/en/jazzy/index.html) — официальная документация: топики, сервисы, action-серверы, написание нод
- [MATLAB Robotics System Toolbox](https://www.mathworks.com/help/ros/index.html?s_tid=CRUX_lftnav) — управление роботом через ROS2 из MATLAB
doc/lwc-doc/docs/getting-started/installation.md
+114
View File
@@ -0,0 +1,114 @@
# Установка проекта
## Быстрая установка
Самый простой способ — установить через `curl` одной командой. Убедитесь, что `curl` установлен:
```bash
sudo apt update && sudo apt upgrade -y && sudo apt install curl
```
Перейдите в домашнюю директорию и запустите скрипт установки:
=== "Стабильная версия (master)"
```bash
cd ~
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh | bash
```
=== "Dev-версия (dev)"
```bash
cd ~
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/dev/install.sh | bash -s dev
```
---
## Установка через Git
Проект доступен как на [GitVerse](https://gitverse.ru/daniel-robotics/lightweight-cobot) (предпочтительно), так и на [GitHub](https://github.com/Daniel-Robotic/lightweight-cobot).
!!! tip "Не знакомы с Git?"
Если вы впервые работаете с Git и GitHub, рекомендуем [прочитать эту статью на Хабре](https://habr.com/ru/companies/yandex_praktikum/articles/700708/) — там всё объясняется с нуля.
Клонируйте репозиторий и запустите скрипт установки:
=== "GitVerse"
```bash
cd ~
git clone https://gitverse.ru/daniel-robotics/lightweight-cobot.git
cd ~/lightweight-cobot
sudo chmod +x ./install.sh
./install.sh
```
=== "GitHub"
```bash
cd ~
git clone https://github.com/Daniel-Robotic/lightweight-cobot.git
cd ~/lightweight-cobot
sudo chmod +x ./install.sh
./install.sh
```
---
## Ручная установка
Если ни `curl`, ни `git` недоступны — скачайте архив проекта вручную со страницы репозитория (кнопка «Скачать ZIP»), разархивируйте и выполните:
```bash
cd ~/lightweight-cobot
sudo chmod +x ./install.sh
./install.sh
```
---
## Процесс установки
Скрипт [`install.sh`](https://gitverse.ru/daniel-robotics/lightweight-cobot/raw/branch/master/install.sh) автоматически установит:
- **Git** — система контроля версий
- **Docker** — контейнеризация для изолированного запуска
- **CLI-инструмент `cobot`** — основной инструмент управления проектом
- Системные зависимости Ubuntu
### Перезагрузка после установки
После завершения скрипта может потребоваться перезагрузка, чтобы заработал Docker:
```bash
sudo reboot now
```
Следите за выводом в терминале — скрипт сам сообщит, нужна ли перезагрузка.
### Если лог пуст
Если после запуска скрипта не выводится никакой информации, обновите среду bash и продолжите настройку вручную:
```bash
source ~/.bashrc # обновление переменных окружения
cobot setup # продолжение настройки системы
```
---
## Проверка установки
После завершения убедитесь, что `cobot` доступен:
```bash
cobot -h
```
Если команда выводит список доступных подкоманд — установка прошла успешно.
---
**Следующий шаг:** [CLI-команды cobot](cli-reference.md)
doc/lwc-doc/docs/getting-started/overview.md
+32 -2
View File
@@ -1,3 +1,33 @@
# Обзор # Быстрый старт
*Описание проекта, что это такое и зачем.* **Lightweight Cobot** позволяет управлять роботом KUKA LBR IIWA 7 через ROS 2: планировать траектории с помощью MoveIt 2, работать в симуляторе Webots или подключаться к физическому роботу по протоколу FRI. Весь проект управляется единым CLI-инструментом `cobot`.
Этот раздел проведёт вас от нулевого состояния до первого запуска системы.
---
## Предпосылки
- Физический робот **KUKA LBR IIWA 7 R800** — если планируете работу с реальным оборудованием
- Либо желание работать только в симуляторе **Webots** — физический робот не нужен
- ПК или сервер с **Ubuntu 24.04** (или подключение к существующему серверу по SSH)
- Доступ к сети, в которой находится контроллер робота
---
## Порядок шагов
1. [**Настройка SunriseWorkbench**](sunrise-setup.md) — подготовка контроллера KUKA: подключение кабелей, загрузка программы `ServerFriRos2`, настройка сетевых параметров. *(Только для физического робота)*
2. [**Подключение к серверу**](remote-access.md) — выбор варианта развёртывания (локально или удалённо), SSH-подключение к серверу управления.
3. [**Установка проекта**](installation.md) — скачивание и установка LWC через `curl`, `git` или вручную.
4. [**CLI-команды cobot**](cli-reference.md) — обзор всех команд: настройка, запуск, сборка, управление.
5. [**Конфигурация системы**](configuration.md) — подробное описание `cobot-setting.yaml`: что менять, что оставить по умолчанию.
---
!!! tip "Только симуляция?"
Если физический робот недоступен, пропустите шаг 1 и начните сразу с [установки проекта](installation.md). Запустите симулятор командой `cobot run --simulate`.
doc/lwc-doc/docs/getting-started/remote-access.md
+78
View File
@@ -0,0 +1,78 @@
# Подключение к серверу
## Варианты развёртывания
Проект можно развернуть двумя способами:
| Вариант | Описание | Когда использовать |
|---|---|---|
| **Локально** | Установка на вашем ПК | Разработка, симуляция, отладка |
| **Удалённо (сервер)** | Установка на выделенном сервере, подключённом к контроллеру KUKA | Работа с реальным роботом |
При удалённом варианте вы управляете сервером через **SSH-соединение** со своего ПК.
---
## Программы для SSH-подключения
Выберите любую из программ:
- [**Termius**](https://termius.com/) — кроссплатформенный SSH-клиент с удобным GUI
- [**MobaXterm**](https://mobaxterm.mobatek.net/) — многофункциональный терминал для Windows
- [**PuTTY**](https://putty.software/) — классический SSH-клиент для Windows
- **Встроенный терминал / командная строка** — описано ниже
Инструкции по настройке Termius, MobaXterm и PuTTY смотрите в их официальной документации.
---
## Данные для подключения
```
IP-адрес: 192.168.21.1
Имя пользователя: cobot
Пароль: 12345678
```
!!! warning "Требование к сети"
Ваш ПК должен находиться в **одной сети/подсети с роботом** (например, в сети КнАГУ).
Без этого соединение установить не удастся.
---
## Подключение через встроенный терминал
=== "Linux"
Подойдёт любой дистрибутив. Откройте терминал и выполните:
```bash
ssh cobot@192.168.21.1
```
=== "Windows"
Требуется **Windows 10** или новее (встроенный SSH-клиент).
Откройте **Командную строку** или **PowerShell** и выполните:
```powershell
ssh cobot@192.168.21.1
```
После выполнения команды появится запрос пароля:
```
cobot@192.168.21.1's password:
```
Введите пароль `12345678` — символы не отображаются во время набора, это нормальное поведение из соображений безопасности. Нажмите ++enter++.
При успешном подключении вы увидите приглашение командной строки сервера:
```
cobot@server:~$
```
---
**Следующий шаг:** [Установка проекта](installation.md)
doc/lwc-doc/docs/getting-started/sunrise-setup.md
+88
View File
@@ -0,0 +1,88 @@
# Настройка SunriseWorkbench
!!! info "Только для физического робота"
Этот раздел актуален только при работе с реальным роботом KUKA LBR IIWA 7.
Для симуляции переходите к [Установке проекта](installation.md).
---
## Настройка физического оборудования
### Подключение Ethernet
Подключите кабель Ethernet от вашего ПК (или сервера управления) к одному из сетевых портов контроллера KUKA:
- **KLI** (KUKA Line Interface) — основной порт, используется для управления и программирования
- **KONI** (KUKA Optional Network Interface) — дополнительный порт, используется для FRI
Вы можете подключить оба порта одновременно — при конфигурации сервера будет выбор, какой интерфейс использовать.
![Подключение KONI и KLI](assets/koni-kli-connection.png)
---
## Синхронизация проекта в SunriseWorkbench
### Проверка наличия ServerFriRos2
Убедитесь, что в вашем Sunrise-проекте присутствует файл `ServerFriRos2.java`.
Если файл отсутствует — скачайте его из репозитория. Он находится по пути `src/iiwa_sunrise/ServerFriRos2.java`.
=== "curl"
```bash
curl -fsSL https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/src/iiwa_sunrise/ServerFriRos2.java \
-o ServerFriRos2.java
```
=== "wget"
```bash
wget -O ServerFriRos2.java \
https://gitverse.ru/api/repos/daniel-robotics/lightweight-cobot/raw/branch/master/src/iiwa_sunrise/ServerFriRos2.java
```
После скачивания добавьте файл в Sunrise-проект и выполните синхронизацию с контроллером.
### Синхронизация с контроллером
Откройте **SunriseWorkbench** и нажмите кнопку синхронизации проекта:
![Кнопка синхронизации проекта](assets/sync-button.png)
Перед синхронизацией убедитесь, что ПК и контроллер KUKA находятся в одной сети. Текущие сетевые параметры контроллера можно быстро проверить прямо в SunriseWorkbench:
![Быстрый просмотр параметров сети](assets/network-params.png)
---
## Настройка ServerFriRos2
Откройте файл `ServerFriRos2.java` в SunriseWorkbench и измените следующие параметры в соответствии с вашей сетевой конфигурацией:
```java
// IP-адрес интерфейса KONI
KONI_IP = "192.170.10.10";
// IP-адрес интерфейса KLI
KLI_IP = "192.168.21.31";
// Нулевая позиция (все суставы в 0°)
ZERO_POSITION = {0, 0, 0, 0, 0, 0, 0};
// Рабочая позиция для мониторинга
MONITOR_WORKING_POSITION = {0, 0, 0, -1.57, 0, 1.57, 0};
// Инструмент, используемый по умолчанию
@Named("tool1")
```
!!! warning "Важно"
IP-адреса должны совпадать с реальными адресами интерфейсов вашего контроллера.
Неверный IP приведёт к тому, что FRI-соединение не установится.
После внесения изменений повторно выполните синхронизацию проекта с контроллером.
---
**Следующий шаг:** [Подключение к серверу управления](remote-access.md)
doc/lwc-doc/docs/index.md
+17 -13
View File
@@ -1,19 +1,23 @@
# Welcome to MkDocs # Lightweight Cobot — Документация
Тест, того что все работает, и что документация собирается. **Lightweight Cobot (LWC)** — открытая система управления коллаборативным роботом **KUKA LBR IIWA 7 R800** на базе **ROS 2 Jazzy**. Поддерживает работу как с физическим роботом (через FRI), так и в виртуальной среде (симулятор Webots). В состав проекта входят CLI-инструмент `cobot`, аппаратный интерфейс ROS 2 Control, планировщик движений MoveIt 2 и REST/MCP API для интеграции с AI-агентами.
For full documentation visit [mkdocs.org](https://www.mkdocs.org). ---
## Commands ## Репозитории
* `mkdocs new [dir-name]` - Create a new project. | Платформа | Ссылка | Статус |
* `mkdocs serve` - Start the live-reloading docs server. |---|---|---|
* `mkdocs build` - Build the documentation site. | **GitVerse** (предпочтительный) | [daniel-robotics/lightweight-cobot](https://gitverse.ru/daniel-robotics/lightweight-cobot) | основной |
* `mkdocs -h` - Print help message and exit. | GitHub | [Daniel-Robotic/lightweight-cobot](https://github.com/Daniel-Robotic/lightweight-cobot) | зеркало |
## Project layout ## Онлайн документация
mkdocs.yml # The configuration file. - [GitVerse Pages](https://daniel-robotics.gitverse.site/lightweight-cobot) — основная
docs/ - [GitHub Pages](https://daniel-robotic.github.io/lightweight-cobot/) — зеркало
index.md # The documentation homepage.
... # Other markdown pages, images and other files. ---
## С чего начать
Перейдите в раздел [**Быстрый старт → Обзор**](getting-started/overview.md), чтобы пройти полный путь от подключения робота до первого запуска.
doc/lwc-doc/mkdocs.yml
+9
View File
@@ -43,6 +43,15 @@ nav:
- Быстрый старт: - Быстрый старт:
- Обзор: getting-started/overview.md - Обзор: getting-started/overview.md
- Настройка SunriseWorkbench: getting-started/sunrise-setup.md
- Подключение к серверу: getting-started/remote-access.md
- Установка проекта: getting-started/installation.md
- CLI-команды cobot: getting-started/cli-reference.md
- Конфигурация системы: getting-started/configuration.md
- Управление:
- ROS2 (Bash): getting-started/control/ros2-control.md
- Foxglove Studio: getting-started/control/foxglove.md
- REST API: getting-started/control/rest-api.md
- Sunrise Workbench: - Sunrise Workbench:
- Обзор: sunrise/overview.md - Обзор: sunrise/overview.md