ПР02. Терминал, пакет и запуск turtlesim

НЕДЕЛЯ 02понять→собрать→сломать→доказать→проверить себя

Рассчитывайте на одну лабораторную пару и примерно 2 часа самостоятельной доработки. На паре вместе проходим пустой пакет, его сборку и первый launch-файл. Самостоятельно повторяем опыт, оформляем наблюдения и настраиваем CI.

Входные данные

Среда ПР01, личный Git-репозиторий и course kit текущей недели с манифестом PR02. Нужны turtlesim, colcon, Python 3, launch и launch_ros из вашей установки ROS. Python и Git считаем знакомыми; новые команды Linux разбираем на файлах этой работы.

Создадим пакет turtle_bringup: сначала пустой, затем с описанием запуска готовой ноды turtlesim. Собственная нода с callback появится в ПР03. Завершите граф из ПР01; повторно сдавать тот же опыт здесь не нужно.

Цель

Собрать пакет, запустить установленный launch-файл и через CLI проверить, что команда доходит до нужного подписчика. Объяснить различие между файлом на диске, запущенной нодой и сообщением в графе.

Критерии зачтено

Стадия	Что требуется
1 · Собрать	turtle_bringup собирается; ros2 launch turtle_bringup sim.launch.py запускает turtlesim; CLI-команда вызывает движение
2 · Сломать	Тот же Twist отправляется в /cmd_vel: издатель виден, подписчика turtlesim у него нет
3 · Доказать	Исправлено только полное имя; повтор команды снова даёт движение; различие обнаружения и доставки объяснено
Автопроверка	check_practice.py PR02 проверяет исходники пакета, лог сборки, commands.md, types.md и заявления отчёта

Что сделать

1. Найдите корень работы и подготовьте терминал

Откройте Bash внутри личного репозитория, в той Ubuntu/WSL2 или контейнере, где установлен ROS. Корень репозитория будет корнем workspace:

source /opt/ros/lyrical/setup.bash  # для Ubuntu 24.04: /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=16           # подставьте выделенный вам домен
cd "$(git rev-parse --show-toplevel)"
pwd
ls -a
mkdir -p src evidence/pr02
printenv ROS_DISTRO ROS_DOMAIN_ID
ros2 pkg prefix turtlesim

Путь ros2 pkg prefix относится к установленному пакету. Путь pwd — к вашему текущему каталогу; это разные вещи.

Добавьте в .gitignore каталоги build/, install/, log/ и .course-kit/, если их ещё нет. Исходники src/ и результаты evidence/ сохраняются в Git.

Команды и операторы	Зачем нужны в этой работе
pwd, cd, ls -a	Проверить расположение репозитория, перейти в src, увидеть скрытые файлы
mkdir -p	Создать каталоги, в том числе вложенные
cat, less, grep	Прочитать файл, просмотреть длинный лог, найти строку; из less выйти клавишей q
source, printenv, export	Подключить среду, прочитать и задать настройки текущего терминала
>, 2>&1	Записать stdout в файл и направить туда же stderr; прежнее содержимое файла заменяется
|, tee	Передать stdout следующей команде; одновременно показать и сохранить вывод

В evidence/pr02/commands.md разберите три команды Linux, которые здесь использовали: точная команда, назначение, ваш результат. Отдельно объясните, чем > отличается от |, а source — от запуска новой программы. Не нужно выбирать десять случайных команд или публиковать всю .bashrc.

2. Создайте и соберите пустой пакет

Из корня workspace:

cd src
ros2 pkg create --build-type ament_python --license Apache-2.0 \
  turtle_bringup --dependencies launch launch_ros turtlesim
cd ..
ls src/turtle_bringup
cat src/turtle_bringup/package.xml

Если пакет уже существует, продолжайте с ним, не запускайте генератор поверх файлов. Имя turtle_bringup используем одинаковое в командах и метаданных. Обновите описание и сведения о сопровождающем в package.xml и setup.py.

В каркасе есть:

• package.xml — имя, версия, зависимости;
• setup.py, setup.cfg — правила установки Python-пакета и ресурсов;
• resource/turtle_bringup — маркер для индекса пакетов;
• turtle_bringup/__init__.py — Python-пакет; своей ноды в нём пока нет.

Соберите его из корня workspace в терминале, где подключена только базовая ROS:

set -o pipefail
colcon build --symlink-install --packages-select turtle_bringup \
  2>&1 | tee evidence/pr02/build-empty.txt

pipefail сохраняет ненулевой статус конвейера при ошибке colcon, даже если tee успешно записал лог. При ошибке сначала прочитайте лог и исправьте её. В новом терминале запуска подключите свою ROS, перейдите в корень репозитория:

source /opt/ros/lyrical/setup.bash  # либо jazzy
source install/setup.bash
ros2 pkg prefix turtle_bringup

Путь должен вести в install вашего workspace. Пустой пакет найден, но нода не появилась: сборка и source не запускают процессы.

3. Добавьте первый launch-файл

Создайте каталог src/turtle_bringup/launch и файл sim.launch.py в нём. Минимальное описание запуска:

from launch import LaunchDescription
from launch_ros.actions import Node


def generate_launch_description():
    return LaunchDescription([
        Node(
            package='turtlesim',
            executable='turtlesim_node',
            output='screen',
        ),
    ])

generate_launch_description() возвращает список действий. Node здесь — действие запуска процесса, а не реализация callback. package и executable соответствуют двум аргументам знакомой команды ros2 run.

В setup.py добавьте from glob import glob, а в существующий список data_files — запись для launch. Сохраните имеющиеся записи маркера и XML:

# Фрагмент setup.py: импорт вверху файла
from glob import glob

# Значение аргумента data_files внутри существующего setup(...)
data_files=[
    ('share/ament_index/resource_index/packages', ['resource/' + package_name]),
    ('share/' + package_name, ['package.xml']),
    ('share/' + package_name + '/launch', glob('launch/*.launch.py')),
],

Это фрагмент существующего вызова setup(...), а не отдельный второй вызов. Проверьте, что package.xml сохраняет зависимости launch, launch_ros, turtlesim. Файл только в src ещё не является установленным ресурсом.

В свежем терминале сборки подключите базовую ROS, перейдите в корень репозитория и пересоберите пакет:

set -o pipefail
colcon build --symlink-install --packages-select turtle_bringup \
  2>&1 | tee evidence/pr02/build.txt

В терминале A, из корня workspace:

source /opt/ros/lyrical/setup.bash  # либо jazzy
source install/setup.bash
export ROS_DOMAIN_ID=16
ros2 pkg prefix turtle_bringup
ls "$(ros2 pkg prefix turtle_bringup)/share/turtle_bringup/launch"
ros2 launch turtle_bringup sim.launch.py

Остановите старые экземпляры turtlesim перед запуском: иначе несколько нод могут принимать одну команду. Должно открыться одно окно. В другом терминале проверьте ros2 node list --no-daemon --spin-time 2. Затем завершите launch через Ctrl+C: запущенный им turtlesim должен завершиться. Повторите запуск для опыта ниже. Зафиксируйте в commands.md запуск, проверку графа и остановку.

4. Свяжите команду с движением

Оставьте launch в A. В B/C подключите ту же ROS и домен. Teleop должен быть остановлен. В C получите тип позы и начальные координаты:

ros2 interface show geometry_msgs/msg/Twist
ros2 topic type /turtle1/pose
ros2 topic echo /turtle1/pose --once

В B отправьте одну команду, затем в C повторно получите позу:

ros2 topic pub --once /turtle1/cmd_vel geometry_msgs/msg/Twist \
  '{linear: {x: 1.0}, angular: {z: 0.5}}'

Одна публикация не задаёт бесконечное движение: без новых команд turtlesim останавливается. Запишите ожидаемое направление и фактическую позу до/после.

5. Ошибитесь в имени и докажите исправление

В B запустите издателя с другим именем топика:

ros2 topic pub --rate 1 --wait-matching-subscriptions 0 \
  /cmd_vel geometry_msgs/msg/Twist \
  '{linear: {x: 1.0}, angular: {z: 0.5}}'

--wait-matching-subscriptions 0 позволяет публиковать и без подписчиков. При --rate ноль уже используется по умолчанию; здесь он указан явно. При --once по умолчанию ожидается один подписчик: в ошибочном топике такая команда будет ждать, поэтому для опыта используем непрерывную публикацию. Пока издатель работает, в C выполните:

ros2 topic info /cmd_vel --verbose
ros2 topic info /turtle1/cmd_vel --verbose

Сравните число и имена конечных точек. Остановите издателя через Ctrl+C, исправьте только /cmd_vel на /turtle1/cmd_vel и повторите запуск и проверку. После наблюдения движения остановите издателя и дождитесь остановки черепахи. Не меняйте одновременно имя, скорость и домен.

В commands.md сохраните команды, вывод и сравнение «до / сбой / после». Объясните, почему правильного типа сообщения недостаточно. В types.md запишите имена двух основных топиков, их типы и назначение полей Twist. Тип позы: turtlesim/msg/Pose для Jazzy или turtlesim_msgs/msg/Pose для Lyrical; выбирайте по выводу своей команды.

Проверка

Обязательные файлы сдачи

• В корне репозитория — AI_USAGE.md, с отдельной записью для PR02: модель, инструмент, характер помощи и способ проверки. Если ИИ не использовался, напишите это явно и поставьте ai_used: false в отчёте; файл всё равно нужен. Предыдущие записи сохраняйте. Правила и пример.
• В evidence/pr02/report.json поле commit — SHA уже созданного коммита реализации. Отчёт фиксируется следующим коммитом; его SHA указывается при сдаче вместе со ссылкой на CI. Пошаговый пример двух коммитов.

В Git должны попасть:

src/turtle_bringup/                 # весь исходный пакет, включая resource и setup.cfg
└── launch/sim.launch.py
evidence/pr02/
├── build-empty.txt                 # первоначальная сборка без launch
├── build.txt                       # итоговая сборка
├── commands.md                     # Linux, launch, CLI, сравнение сбоя и исправления
├── types.md                        # типы и поля сообщений
└── report.json                     # по общему шаблону course kit

Первый коммит фиксирует пакет, README и CI, следующий — evidence. В report.commit укажите SHA первого. В tests перечислите выполненные проверки сборки, обнаружения пакета, запуска/остановки launch и доставки команды. Проверка ROS-поведения выполняется локально; checker проверяет комплектность.

python3 -m py_compile src/turtle_bringup/launch/sim.launch.py
python3 .course-kit/v1/tools/check_practice.py PR02 --submission .

В CI добавьте сборку turtle_bringup и проверку наличия установленного sim.launch.py по инструкции. GUI в CI этой работы не нужен. Функциональные тесты своей ноды появятся в ПР03.

Как работаем на лабораторной

Вместе проходим навигацию по workspace, сборку пустого пакета и установку launch-файла. Затем каждый проверяет один и тот же сбой имени и показывает вывод CLI до/после. В оставшееся время оформляем отчёт или исправляем запуск.

Дополнительно, если основная часть готова

• Запустите второй turtlesim в другом namespace через тот же launch. Предскажите полные имена, затем проверьте их. Не добавляйте teleop в launch: для клавиатурного ввода ему нужен отдельный терминал.
• В паре попробуйте перенести издателя на другой компьютер. Сначала сравните RMW/ROS, домен, настройки discovery и сетевые интерфейсы. Один успешный ping не доказывает работу DDS; учитывайте firewall, Wi-Fi isolation и контейнерную сеть. Если сеть аудитории не подходит, объяснения схемы из лекции достаточно.

Эти расширения не входят в критерии зачёта. Управление тремя окнами через mimic, собственные msg/srv и ноды остаются следующими шагами курса.

Создание пакета · Установка launch-файлов · Linux-терминал

Общий порядок: runbook · troubleshooting. Декларация AI_USAGE.md оформляется по правилам курса, в том числе без ИИ.