Документация: ROS2 пакет robohead_interfaces

Общее описание

Пакет robohead_interfaces содержит пользовательские типы сообщений (messages) и сервисов (services), используемые нодами робоголовы. Пакет не содержит исполняемого кода — только определения интерфейсов.

---

Структура файлов

robohead_interfaces/
├── CMakeLists.txt
├── msg
│   ├── AudioData.msg
│   ├── ColorArray.msg
│   ├── Color.msg
│   └── TouchEvent.msg
├── package.xml
├── README.md
└── srv
    ├── ColorPalette.srv
    ├── Color.srv
    ├── Move.srv
    ├── PlayMedia.srv
    ├── SimpleCommand.srv
    └── Speak.srv

---

Сообщения (Messages)

AudioData.msg

Сырые аудиоданные одного канала (один фрейм / чанк).

int16[] data

Поле	Тип	Описание
data	int16[]	Массив аудиосемплов (16-бит, знаковые). Длина определяется параметром frames_per_buffer

Используется в: respeaker_driver, speech_recognizer

---

Color.msg

Цвет в формате RGB.

uint8 red
uint8 green
uint8 blue

Поле	Тип	Диапазон	Описание
red	uint8	0–255	Красный канал
green	uint8	0–255	Зелёный канал
blue	uint8	0–255	Синий канал

Используется в: respeaker_driver (LED-управление), ColorArray.msg, Color.srv, ColorPalette.srv

---

ColorArray.msg

Массив цветов (для управления каждым светодиодом индивидуально).

Color[] colors

Поле	Тип	Описание
colors	Color[]	Массив цветов. Для ReSpeaker ожидается ровно 12 элементов

Используется в: respeaker_driver (топик set_color_manual)

---

TouchEvent.msg

Данные о касании с тачскрина.

int32 slot
int32 tracking_id
int32 x
int32 y
string state  # "down", "move", "up"

Поле	Тип	Описание
slot	int32	Номер текущего касания (от 0 до 9 одновременных касаний)
tracking_id	int32	Уникальный ID-касания. Остается неизменным, пока палец касается тачскрина, после отрыва и повторного касания увеличивается на 1
x	int32	Координата X касания. Лежит в диапазоне разрешения тачскрина (может не совпадать с разрешением дисплея)
y	int32	Координата Y касания. Лежит в диапазоне разрешения тачскрина (может не совпадать с разрешением дисплея)
state	string	Текущее состояние касания (см. подробнее таблицу состояний)

Состояние	Описание
down	Палец коснулся тачскрина
move	Палец перемещается по тачскрину (публикация при изменении кординаты)
up	Палец оторвался от тачскрина

Гарантируется, что в рамках одного tracking_id обязательно будет в самом начале down и в самом конце up. Если между касанием и отрывом произошло перемещение пальца, то между down и up обязательно будут сообщения move.

Используется в: media_driver

---

Сервисы (Services)

SimpleCommand.srv

Универсальный сервис для передачи одного целочисленного значения. Используется для команд типа «установить режим», «установить яркость», «получить громкость», «проверить idle».

int16 data
---
int16 data

Запрос

Поле	Тип	Описание
data	int16	Команда / значение (смысл зависит от конкретного сервиса)

Ответ

Поле	Тип	Описание
data	int16	Результат / статус (смысл зависит от конкретного сервиса)

Используется в:

Нода	Сервис	Запрос data	Ответ data
ears_driver	is_idle	игнорируется	1 — idle, 0 — движется
neck_driver	is_idle	игнорируется	1 — idle, 0 — движется
media_driver	set_volume	громкость 0–100	установленная громкость или -1
media_driver	get_volume	игнорируется	текущая громкость 0–100
media_driver	is_idle/audio	игнорируется	1 — idle, 0 — играет
media_driver	is_idle/display	игнорируется	1 — idle, 0 — играет
respeaker_driver	set_mode	режим LED 0–5	0 — успех, -1 — ошибка
respeaker_driver	set_brightness	яркость	0 — успех, -1 — ошибка
speech_recognizer (KWS)	set_mode	0 (off) / 1 (on)	установленный режим
speech_recognizer (ASR)	set_mode	0 (off) / 1 (grammar) / 2 (free)	установленный режим

---

Move.srv

Команда перемещения двух осей с заданной длительностью (плавное движение).

int16 angle_a
int16 angle_b
float64 duration
---
int16 data

Запрос

Поле	Тип	Описание
angle_a	int16	Целевой угол первой оси (градусы)
angle_b	int16	Целевой угол второй оси (градусы)
duration	float64	Время движения (секунды). 0.0 — мгновенное перемещение

Ответ

Поле	Тип	Описание
data	int16	Код результата

Коды ответа

Код	Значение
0	Успех
-1	angle_a вне допустимого диапазона
-2	angle_b вне допустимого диапазона
-3	duration отрицательный

Используется в:

Нода	angle_a	angle_b
ears_driver	Левое ухо	Правое ухо
neck_driver	Вертикальный угол (наклон)	Горизонтальный угол (поворот)

---

PlayMedia.srv

Команда воспроизведения медиаконтента (видео/изображение + аудио).

string path_to_video_file
string path_to_audio_file
bool loop
---
int16 data

Запрос

Поле	Тип	Описание
path_to_video_file	string	Путь к видео/изображению, URL или стоп-команда. Пустая строка — не трогать видеоплеер
path_to_audio_file	string	Путь к аудио, URL или стоп-команда. Пустая строка — не трогать аудиоплеер
loop	bool	true — зацикленное воспроизведение, false — однократное

Ответ

Поле	Тип	Описание
data	int16	0 — успех, -1 — ошибка

Используется в: media_driver

---

Color.srv

Установка RGB-цвета (например, для всех светодиодов).

uint8 red
uint8 green
uint8 blue
---
int16 data

Запрос

Поле	Тип	Диапазон	Описание
red	uint8	0–255	Красный
green	uint8	0–255	Зелёный
blue	uint8	0–255	Синий

Ответ

Поле	Тип	Описание
data	int16	0 — успех, -1 — ошибка

Используется в: respeaker_driver (сервис set_color_all)

---

ColorPalette.srv

Установка двухцветной палитры для анимационных LED-режимов.

Color color_a
Color color_b
---
int16 data

Запрос

Поле	Тип	Описание
color_a	Color	Первый цвет палитры
color_b	Color	Второй цвет палитры

Ответ

Поле	Тип	Описание
data	int16	0 — успех, -1 — ошибка

Используется в: respeaker_driver (сервис set_color_palette)

---

Speak.srv

Синтез и озвучка речи по тексту.

string text
int16 voice
string path_to_save
bool put_accent
bool put_yo
bool play
---
int16 data

Запрос

Поле	Тип	Описание
text	string	Текст для озвучки
voice	int16	Выбор голоса
path_to_save	string	Путь для сохранения файла с синтезированной речью
put_accent	bool	Да/Нет расставить ударения автоматически
put_yo	bool	Да/Нет расставить е/ё автоматически
play	bool	Да/Нет расставить воспроизвести (через media_driver) синтезированное аудио автоматически

Ответ

Поле	Тип	Описание
data	int16	Код результата

Коды ответа

Код	Значение
0	Успех
-1	Пустой текст
-2	Недопустимый индекс голоса (вне диапазона 0–4)
-3	Ошибка синтеза (исключение в Silero)
-4	Синтез вернул None (ошибка записи файла или создания директории)
-5	play=true, но параметр srv_play_media не настроен
-6	Ошибка воспроизведения через media_driver

Используется в: silero_tts

---

Сводная таблица

Сообщения

Имя	Поля	Назначение
AudioData	int16[] data	Аудиосемплы одного канала
Color	uint8 red, green, blue	RGB-цвет
ColorArray	Color[] colors	Массив цветов (12 LED)
TouchEvent	int32 slot, int32 tracking_id, int32 x, int32 y, string state	Касания тачскрина

Сервисы

Имя	Запрос	Ответ	Назначение
SimpleCommand	int16 data	int16 data	Универсальная команда
Move	int16 angle_a, angle_b + float64 duration	int16 data	Перемещение сервоприводов
PlayMedia	string video, audio + bool loop	int16 data	Воспроизведение медиа
Color	uint8 r, g, b	int16 data	Установка цвета
ColorPalette	Color a, b	int16 data	Установка палитры
Speak	string text, int16 voice, string path_to_save, bool put_accent, bool put_yo, bool play	int16 data	Синтез речи

---

Сборка

colcon build --symlink-install --packages-select robohead_interfaces

Важно: robohead_interfaces должен быть собран перед всеми пакетами, которые его используют. При использовании colcon build без --packages-select зависимости разрешаются автоматически.