Часть 06 (резервная версия): развёртывание OpenClaw, перехват кнопок и управление платой

После этой главы читатель должен уметь выполнить на MagicBox четыре действия. Первое: проверить, что magicclaw.service и magicclaw-buttons.service работают нормально. Второе: понимать, что означают три физические кнопки — левую, среднюю и правую — и какие действия им можно назначить. Третье: знать, какие команды magicboxctl относятся к чисто локальному управлению железом, а какие требуют предварительного запуска голосовой цепочки ROS. Четвёртое: понимать, за что отвечают встроенный бэкенд OpenClaw и облегчённый фронтенд Lite из этого учебника и как правильно открыть веб-интерфейс.

1. Критерии приёмки после выполнения главы

Глава не ограничивается тем, что страница открылась в браузере. Должны одновременно выполняться следующие условия.

• magicclaw.service находится в состоянии active (running), а curl http://127.0.0.1:18789/health возвращает признак работоспособности.
• magicclaw-buttons.service находится в состоянии active (running), и три физические кнопки уже переданы для переназначения стороне MagicClaw.
• Команды magicboxctl buttons show, magicboxctl voice ... и magicboxctl servo ... понятны: читатель не считает, что команды, требующие предварительно запущенной службы, можно выполнять «в любой момент».
• Читатель знает, что у OpenClaw есть бэкенд, связанный с управлением браузером, но стабильным веб-входом для этой платы остаётся фронтенд Lite из учебника.

2. Какой режим работы выбрать

После подключения MagicBox к OpenClaw возможны два разных режима работы.

Первый режим — оригинальный, то есть magicbox-start. В нём обработкой кнопок занимается /userdata/magicbox/launch/start.py. Левая кнопка всегда запускает бинокулярный режим, средняя — режим жестов, правая — голосовой режим. Этот режим ближе к заводской демонстрации: подсветка, звуки подтверждения и вход через кнопки сохраняют заводское поведение. Однако он не подходит для сценария, в котором назначение кнопок меняется прямо из окна чата во фронтенде.

Второй режим — тот, который использует эта глава: кнопками управляет MagicClaw. В этом режиме magicclaw-buttons.service слушает три физические кнопки, magicboxctl buttons set ... записывает назначения, а magicboxctl buttons invoke ... запускает действие. Такой подход лучше подходит для учебных демонстраций, управления через фронтенд и оркестрации возможностей платы.

Эти два режима нельзя использовать одновременно как вход для кнопок. Причина простая: оригинальный magicbox-start сам слушает кнопки, и если одновременно включить magicclaw-buttons.service, одно нажатие будет запускать две логики сразу. Поэтому в этой главе по умолчанию используется режим с перехватом кнопок MagicClaw, а magicbox-start не включён как постоянный вход для кнопок.

3. Что проверить до начала работы

Все команды этой главы по умолчанию выполняются в терминале платы, если явно не сказано, что шаг выполняется на Windows-компьютере. Перед началом должны быть выполнены следующие условия.

• Плата подключена сетевым кабелем, её IP-адрес по-прежнему 192.168.127.10.
• Вход по SSH выполняется командой ssh sunrise@192.168.127.10.
• Пакет OpenClaw / MagicClaw установлен в /userdata/magicclaw.
• Плата работает в режиме перехвата кнопок MagicClaw, а не в оригинальном режиме.

Сначала выполните в терминале платы следующую проверку:

ls -ld /userdata/magicclaw
ls -l /userdata/magicclaw/runtime/bin/magicboxctl
ls -l /etc/systemd/system/magicclaw.service
ls -l /etc/systemd/system/magicclaw-buttons.service

Если все эти пути существуют, установка на плате выполнена полностью. Все последующие команды главы опираются на эти пути.

4. Проверка состояния служб перед работой

Эту группу команд можно выполнять из любого каталога. Для неё не нужно загружать окружение ROS, так как проверяются сами службы systemd.

sudo systemctl status magicclaw.service --no-pager
sudo systemctl status magicclaw-buttons.service --no-pager
curl http://127.0.0.1:18789/health

Признаки того, что можно переходить к подключению браузера и управлению кнопками:

• magicclaw.service показывает active (running);
• magicclaw-buttons.service показывает active (running);
• проверка состояния возвращает ответ наподобие {"ok":true,"status":"live"}.

Если этот шаг не пройден, открывать браузер не нужно. Старая панель управления и облегчённая страница Lite — это лишь интерфейсы управления. Если сам шлюз не запущен, веб-страница работать не будет.

5. Три физические кнопки: что означает каждая

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

• left — левая кнопка, если смотреть на устройство спереди, со стороны пользователя.
• middle — средняя кнопка.
• right — правая кнопка, если смотреть на устройство спереди, со стороны пользователя.

Демон кнопок слушает следующие линии GPIO:

Текущее соответствие кнопок и действий можно посмотреть командой:

sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons show

Успешный вызов возвращает JSON, например:

{
  "left": "stereo",
  "middle": "gesture",
  "right": "voice_chat"
}

Это означает, что каждая из трёх физических кнопок сейчас привязана к определённому действию.

6. Семь действий, которые можно назначить кнопкам

Сейчас в назначения кнопок можно записать семь действий: stereo, gesture, voice_chat, voice_asr, yolo, stop_all, off. Это не абстрактные имена: каждому из них в magicboxctl соответствует реализованная ветка выполнения.

1. stereo

stereo запускает демонстрацию бинокулярного зрения. При нажатии выполняется бинокулярная цепочка, подсветка становится красной, а активным режимом записывается stereo. Повторное нажатие той же кнопки, уже находящейся в активном состоянии stereo, закрывает бинокулярный режим.

2. gesture

gesture запускает демонстрацию жестов. При нажатии подсветка становится зелёной, а активным режимом записывается gesture. Повторное нажатие той же кнопки, уже находящейся в состоянии gesture, закрывает режим жестов.

3. voice_chat

voice_chat запускает полную локальную голосовую цепочку диалога. В текущей реализации поведение выровнено с оригинальным голосовым режимом правой кнопки: сначала обеспечивается наличие базы audio_io, затем отдельно запускается qwen_llm, а второй экземпляр audio_io больше не поднимается. При нажатии подсветка становится синей, а активным режимом записывается voice_chat. Повторное нажатие этой же кнопки в состоянии voice_chat закрывает голосовой диалог.

4. voice_asr

voice_asr запускает только базу распознавания и озвучивания, то есть цепочку audio_io, но не поднимает полный локальный LLM-диалог. Подсветка становится бирюзовой, активным режимом записывается voice_asr. В этой главе не утверждается, что повторное нажатие той же кнопки обязательно закроет режим. Если нужно точно остановить режим, надёжнее выполнить magicboxctl voice asr stop.

5. yolo

yolo запускает демонстрацию YOLO. При нажатии подсветка становится пурпурной, активным режимом записывается yolo. Повторное нажатие той же кнопки закрывает режим по обычной логике переключения.

6. stop_all

stop_all останавливает все активные режимы. Состояние активности очищается, подсветка по возможности гаснет. Это действие удобно назначить отдельной кнопке как «аварийную остановку» или возврат в состояние ожидания.

7. off

off означает не «выключение питания», а «оставить кнопку, но при нажатии не запускать никакой режим». Если кнопке временно не нужна функция, её можно назначить на off.

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

7. Как просматривать, менять и запускать назначения кнопок

Команды этого раздела можно выполнять из любого каталога, зависимость от окружения ROS отсутствует.

Сначала посмотрите текущие назначения:

sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons show

Затем запишите набор назначений, близкий к заводскому поведению:

sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons set left stereo
sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons set middle gesture
sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons set right voice_chat

Успешное выполнение обычно выводит:

• left mapped to stereo
• middle mapped to gesture
• right mapped to voice_chat

Чтобы сымитировать действие кнопки без её физического нажатия, выполните:

sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons invoke right

Если right сейчас назначена на voice_chat, ожидаемый результат:

right triggered voice_chat

Проверить, работает ли демон кнопок, можно командой:

sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons daemon status

Этот раздел считается пройденным не тогда, когда команда просто что-то вывела, а когда вы можете ответить на два вопроса: какое действие сейчас привязано к каждой из трёх физических кнопок и даёт ли имитация нажатия результат, соответствующий назначению.

8. Какие команды чисто локальные, а какие требуют запущенной цепочки

Команды magicboxctl относятся к разным классам.

Первый класс — чисто локальные команды управления железом, например led pixel, led pattern, servo set и servo greet. Они напрямую вызывают локальные скрипты работы с железом, не зависят от подписчиков ROS-топиков и не требуют предварительного запуска голосовой цепочки.

Второй класс — команды, для которых нужна уже существующая локальная цепочка ROS, например voice say и voice prompt. Эти команды на самом деле не «проигрывают фразу напрямую», а публикуют одно сообщение std_msgs/String в конкретный ROS-топик:

• voice say публикует в /tts_text;
• voice prompt публикует в /prompt_text.

Если подписчика для топика нет, команда будет ждать и выведет такое сообщение:

Waiting for at least 1 matching subscription(s)...

Это не зависание. Просто ни один процесс сейчас не слушает эти топики.

Третий класс — команды переключения режимов, например buttons set, buttons invoke, voice asr start и voice chat start. Они поднимают или останавливают определённую цепочку и меняют текущее активное состояние платы.

9. Как запускать голосовую цепочку и почему voice say может зависнуть

Если цель — только перевести плату в состояние базы распознавания и озвучивания, выполните:

sudo /userdata/magicclaw/runtime/bin/magicboxctl voice asr start

Затем проверьте состояние:

sudo /userdata/magicclaw/runtime/bin/magicboxctl voice status

В идеальном случае вы увидите как минимум:

voice_asr: running

Если нужна полная голосовая цепочка, а не только audio_io, выполните:

sudo /userdata/magicclaw/runtime/bin/magicboxctl voice chat start

И снова проверьте состояние:

sudo /userdata/magicclaw/runtime/bin/magicboxctl voice status

Ожидаемый результат:

voice_asr: running
voice_chat: running

Команда magicboxctl voice chat start выровнена с оригинальным режимом правой кнопки: сначала поднимается audio_io, затем запускается qwen_llm, и используется та же конфигурация ROS-middleware, что и у узлов платы. Поэтому она работает стабильнее, чем повторный запуск второго экземпляра audio_io в одной команде, и не создаёт конфликтов за аудиоустройство.

Команды внедрения текста имеют смысл только тогда, когда описанное выше состояние уже установлено:

sudo /userdata/magicclaw/runtime/bin/magicboxctl voice say "你好，这是板端朗读测试。"  # «Здравствуйте, это тест озвучивания на плате»
sudo /userdata/magicclaw/runtime/bin/magicboxctl voice prompt "请只回答：测试通过。"  # «Ответьте только: тест пройден»

Перевод первой фразы: «Здравствуйте, это тест озвучивания на плате». Перевод второй: «Отвечайте только: тест пройден».

Обе команды уже проверены на реальной плате. Команда voice prompt передаёт текст в локальный qwen_llm, а ответ из /tts_text поступает в audio_io для воспроизведения.

10. Как работают команды сервопривода и как понимать «левый» и «правый»

Этот раздел также можно выполнять из любого каталога, загрузка окружения ROS не нужна. Управление сервоприводами работает через локальный PWM-скрипт, а не через ROS-узел.

В учебнике «левый» и «правый» означают левую и правую опорные стойки, если смотреть на устройство спереди со стороны пользователя. В текущем скрипте левая стойка использует вывод PWM 32, правая — вывод PWM 33. Безопасный диапазон углов — 0–90, рекомендуемое среднее положение — 30.

Для первого теста выполните такой набор команд:

sudo /userdata/magicclaw/runtime/bin/magicboxctl servo set left 15
sudo /userdata/magicclaw/runtime/bin/magicboxctl servo set right 45
sudo /userdata/magicclaw/runtime/bin/magicboxctl servo greet 1

Если всё прошло успешно, на плате должны сработать обе опорные стойки, а команда servo greet 1 выполнит короткое приветственное движение. Текущая реализация исправлена по официальному примеру управления сервоприводом /userdata/magicbox/basic_function_demo/servo.py: используется схема запуска PWM и время удержания, близкие к официальному примеру, поэтому работа подтверждена на реальной плате.

Здесь важно зафиксировать границу реализации. Команда servo set не выполняет «постоянного удержания угла», а подаёт один импульс движения, держит его короткое время и затем освобождает GPIO. Внутри скрипта после завершения движения вызывается GPIO.cleanup(). Поэтому если читатель ожидает, что после команды стойка будет зафиксирована под заданным углом, это не соответствует текущей реализации. Нужно понимать это заранее, чтобы не принять отсутствие постоянного удержания за то, что команда «не сработала».

Если команда не даёт никакого эффекта, порядок проверки такой: сначала права доступа, затем занятость GPIO и только потом физическое подключение. Сначала не нужно проверять ROS, так как сервоприводы от него не зависят.

11. Как открыть веб-фронтенд

В этом разделе важно прояснить одну путаницу. OpenClaw поставляется со встроенным бэкендом, связанным с управлением браузером, но это не означает, что в текущем окружении обязательно существует официальный фронтенд, который можно открыть удалённо.

На текущей плате подтверждены два сетевых входа, связанных с веб-управлением:

• ws://0.0.0.0:18789 — WebSocket-шлюз, открытый для локальной сети;
• http://127.0.0.1:18791 — интерфейс бэкенда управления браузером, слушающий только localhost платы и требующий аутентификацию Bearer Token.

Это значит, что у OpenClaw действительно есть бэкенд, относящийся к веб-управлению, но на этой конкретной плате он не предоставляет официальный фронтенд, который стабильно открывается по сети. Особенно адрес 18791 — это backend-интерфейс, а не веб-страница, которую можно открыть в браузере. Если открыть его напрямую и увидеть Unauthorized, это нормальное поведение бэкенда.

Отсюда следуют выводы этого учебника:

• Если нужно просто изучить встроенный бэкенд OpenClaw, смотрите на 18789 и 18791.
• Если нужен стабильный веб-вход, пригодный для скриншотов курса, управления через чат и отладки в локальной сети, используйте облегчённый фронтенд Lite из этого учебника.

12. Почему старая панель не подходит как основной вход

Старая панель обычно открывается по адресу:

http://192.168.127.10:18789/chat?session=main

В некоторых окружениях она работает, но в таких условиях, как у вас:

• прямое подключение сетевым кабелем;
• небезопасный контекст HTTP;
• доступ не с localhost платы, а с адреса в локальной сети;
• браузер открывает страницу напрямую по IP локальной сети,

она легко выдаёт ошибку:

device identity required

Это не означает, что плата не запущена или порт не проброшен. Точнее: старая страница управления использует рукопожатие с проверкой идентичности устройства, а текущая среда доступа не удовлетворяет его требованиям.

Поэтому в учебнике старая страница 18789/chat больше не указана как основной вход. Её можно сохранить как исторический интерфейс и объект для диагностики, но для повседневной работы она не рекомендуется.

13. Почему Lite — текущий рекомендованный вход

Работающий веб-вход в этом учебнике — фронтенд Lite. Он создан специально для первичного запуска MagicBox в локальной сети, для скриншотов в учебнике и отладки управления. Он обходит нестабильность проверки идентичности устройства, которая есть в старом веб-пакете OpenClaw.

Lite удобен для следующих задач:

• прямое подключение к шлюзу платы из локальной сети;
• диалоговое управление вместе с magicboxctl и диагностика;
• демонстрации, скриншоты и воспроизведение экспериментов читателями.

Поэтому рекомендации здесь такие:

• для стабильного, прямого и воспроизводимого веб-управления используйте Lite;
• для изучения встроенного бэкенда OpenClaw смотрите 18789 и 18791 по отдельности;
• не используйте старую страницу 18789/chat как основной вход.

14. Типичные неисправности и их устранение

1. Waiting for at least 1 matching subscription(s)...

Обычно появляется при voice say или voice prompt. Причина не в синтаксисе команды, а в том, что никто не слушает /tts_text или /prompt_text. Решение — сначала запустить цепочку:

sudo /userdata/magicclaw/runtime/bin/magicboxctl voice asr start

или:

sudo /userdata/magicclaw/runtime/bin/magicboxctl voice chat start

После этого повторите команду внедрения текста.

2. device identity required

Если эта ошибка появляется в старой панели, не спешите винить плату или службы. Сначала выполните:

curl http://127.0.0.1:18789/health

Если проверка здоровья проходит, проблема в рукопожатии идентичности устройства старой панели, а не в том, что шлюз не запущен. В этом случае переключитесь на фронтенд Lite и продолжайте управление через него.

3. Кнопку переназначили, но нажатие ничего не делает

Сначала проверьте службу:

sudo systemctl status magicclaw-buttons.service --no-pager

Затем назначения:

sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons show

И наконец имитацию нажатия:

sudo /userdata/magicclaw/runtime/bin/magicboxctl buttons invoke left

Если invoke работает, а физическая кнопка не реагирует, неисправность скорее всего в слое прослушивания кнопок, а не в слое назначений.

4. Сервопривод не двигается после команды

Убедитесь, что выполняется именно команда:

sudo /userdata/magicclaw/runtime/bin/magicboxctl servo set left 15

или:

sudo /userdata/magicclaw/runtime/bin/magicboxctl servo set right 45

Если движения нет, сначала проверьте права доступа и занятость GPIO, затем подключение. Не проверяйте ROS: команды сервоприводов от него не зависят.

15. Контрольный список главы

Закончив главу, читатель может проверить себя по следующему списку.

• Я понимаю, что в учебнике используется режим перехвата кнопок MagicClaw, а не оригинальный режим.
• Я могу объяснить, что означают семь действий stereo, gesture, voice_chat, voice_asr, yolo, stop_all, off.
• Я умею смотреть назначения командой buttons show и менять назначения левой, средней и правой кнопок командой buttons set.
• Я знаю, что voice say и voice prompt — это не отдельные локальные команды проигрывания, а команды внедрения сообщений, которые зависят от ROS-подписчиков.
• Я знаю, что servo set — чисто локальное действие через PWM, не зависящее от ROS, и что текущая реализация не удерживает угол постоянно.
• Я знаю, что у OpenClaw есть бэкенд для веб-управления, но стабильный веб-вход на этой плате — фронтенд Lite, а не старая страница 18789/chat.