Веб-управление Joy-Con для Robosuite

Браузерная система дистанционного управления Nintendo Switch Joy-Con. Через WebSocket она в реальном времени связывает контроллер с симуляцией Robosuite и поддерживает управление одной или двумя руками, несколькими роботами и удалённое управление по локальной сети.

🌟 Основные особенности

• ✅ Браузер как пульт: ввод с Joy-Con читается через Gamepad API, интерфейс опрашивает его с частотой 60 Гц.
• ✅ Двусторонняя связь в реальном времени: данные по WebSocket с низкой задержкой передаются в серверную часть на Python.
• ✅ Полная поддержка Robosuite: используется официальный интерфейс Device, поддерживаются контроллеры OSC и Whole Body.
• ✅ Один или два Joy-Con: по умолчанию одна рука, но можно управлять двумя руками — левым и правым контроллером.
• ✅ Графический мониторинг: в реальном времени показываются кнопки, стики и состояние соединения.
• ✅ Кроссплатформенность: Linux, Windows (включая WSL2) и macOS; для подключения Joy-Con достаточно Bluetooth.

🧠 Архитектура системы

┌─────────────┐          WebSocket          ┌──────────────┐
│   Браузер   │ ←────────────────────────→ │ Сервер Python │
│ (интерфейс) │   данные геймпада 60 Гц    │  (Robosuite)  │
└─────────────┘                             └──────────────┘
      ↑                                            ↓
      │                                            │
  Gamepad API                               Симуляция Robosuite
   (Joy-Con)                                (управление роботом)

⚡ Быстрый старт за 5 минут

Нужны Python ≥ 3.8, Bun или Node.js и Joy-Con с Bluetooth. (Рекомендуется.)

1. Получите код и установите зависимости

   cd /home/user/17robo/robosuite-joycon-web
   bun install
   pip install -r requirements.txt
   
   # Установите robosuite (нужно при первом запуске)
   cd /home/user/17robo/robosuite-joycon
   pip install -e .
   cd /home/user/17robo/robosuite-joycon-web
   

2. Запустите самопроверку без рендеринга (подходит для WSL и серверов)

   python test_server_no_render.py
   

   Сообщение ✅ 所有测试通过! («все тесты пройдены») означает, что логика серверной части работает.

3. Подключите Joy-Con по Bluetooth

   • Долго удерживайте кнопку синхронизации на боковой стороне Joy-Con, пока индикатор быстро мигает.
   • В настройках Bluetooth системы выберите Joy-Con (R) или Joy-Con (L).

4. Запустите сервер и интерфейс

   # Терминал 1: одиночный контроллер, среда по умолчанию (Lift + Panda)
   ./start_single.sh
   
   # Терминал 2: интерфейс React
   bun run dev
   

   Откройте в браузере адрес из подсказки (по умолчанию http://localhost:5173).

5. Начните управление

   • На веб-странице нажмите «Подключиться к серверу».
   • Нажмите любую кнопку на Joy-Con, чтобы активировать геймпад.
   • Управляйте роботом в реальном времени.

Без монитора / в WSL: если рендеринг неудобен, можно установить в server.py параметр has_renderer = False.

🚀 Подробности запуска

1. Серверная часть

2. Интерфейс

cd /home/user/17robo/robosuite-joycon-web
bun run dev

Откройте в браузере адрес из терминала (по умолчанию http://localhost:5173): интерфейс в реальном времени показывает состояние соединения и показания кнопок и стиков.

🎮 Назначение кнопок (раскладка Joy-Con по умолчанию)

Все входы в JoyconWebController проходят подавление дребезга и нормализацию; выход сервера остаётся 6+1-мерным вектором действий, полностью совместимым с официальными контроллерами Robosuite.

ℹ️ По умолчанию браузер читает кнопки и стики только через Gamepad API, поэтому для регулировки ориентации используйте правый стик и SL/SR. Если включить экспериментальную функцию WebHID ниже, можно будет управлять ориентацией захвата, поворачивая сам Joy-Con, как в нативном контроллере.

Экспериментальная поддержка IMU через WebHID

• В Chrome или Edge (нужен HTTPS или localhost) нажмите кнопку «Подключить IMU Joy-Con» — датчики Joy-Con станут доступны через WebHID.
• После подключения страница в реальном времени показывает Roll / Pitch / Yaw и передаёт их на сервер, так что ориентацией захвата можно управлять поворотом Joy-Con.
• Сейчас в одном сеансе браузера поддерживается только один Joy-Con; чтобы переключиться, обновите страницу и подключитесь заново.
• В браузерах без WebHID сохраняется режим управления ориентацией стиками и SL/SR.

🧪 Чек-лист тестирования

Рекомендуется пройти весь список после выпуска или крупных изменений; отмечайте пройденные пункты.

Базовое окружение

• Python-зависимости установлены
• Зависимости фронтенда Bun установлены
• Соединение Joy-Con по Bluetooth стабильно

Основные функции

• python test_server_no_render.py проходит
• Режим с одним контроллером запускается и выполняет действия
• Режим с двумя контроллерами управляет левой и правой рукой раздельно
• Переключение захвата работает без задержки
• Цикл управления стабильно работает на 20 Гц

Интерфейс и связь

• Браузер распознаёт Joy-Con (кнопки подсвечиваются)
• Статус WebSocket показывает «подключено»
• После отключения и повторного подключения управление восстанавливается

Производительность

• Задержка управления < 100 мс
• Нет заметного дрейфа при работе более 30 минут

Подробные шаги см. в выводе test_server_no_render.py и в истории тестов.

🛠️ Частые проблемы и диагностика

Совет новичкам: сначала запустите python test_server_no_render.py, убедитесь, что базовое управление работает, и только потом подключайте рендеринг и интерфейс.

📊 Состояние проекта

• Дата выпуска: 2025-10-05
• Версия: v1.0.0
• Готовность: ✅ все функции работают
• Охват: Gamepad API, WebSocket-сервис, один и два Joy-Con, мониторинг интерфейса, запуск скриптами, автоматические тесты
• Показатели производительности:
  • частота управления ~20 Гц
  • опрос геймпада 60 Гц
  • задержка WebSocket < 5 мс (локально)
  • загрузка CPU без рендеринга < 30%

🔍 Техническая реализация и исправления

• Полностью повторяет логику robosuite.devices.Device: input2action, get_arm_action, конечный автомат и преобразование систем координат остаются прежними.
• Выходной вектор действий фиксированной размерности: 6 (поза захвата) + 1 (захват); совместим с контроллерами OSC и Whole Body IK.
• Для устранения дребезга кнопок используется определение фронта нажатия; переключение захвата ZR/ZL.
• test_server_no_render.py проверяет вектор действий, возврат награды и непрерывное управление.
• Скрипты запуска start_single.sh и start_bimanual.sh объединяют частые параметры для удобного развёртывания.

📂 Каталоги и скрипты

🧭 Что можно сделать дальше?

• 🚗 Подключить мобильную базу или собственного робота и расширить таблицу действий в server.py.
• 🌐 Развернуть на сервере в локальной сети и настроить удалённое управление через HTTPS / WebRTC.
• 🧪 Подключить CI: запускать python test_server_no_render.py в конвейере.
• 🧩 При необходимости дополнительных датчиков (IMU, камеры) расширить формат сообщений WebSocket.

Если нужно добавить или изменить документацию, обновляйте этот README, чтобы вся информация оставалась актуальной. Удачного управления! 🎉