Руководство по прошивкам AzDeck

English version

В этом репозитории — руководства и примеры прошивок для приложения AzDeck (JSON по WebSocket, BLE, Classic Bluetooth SPP и Pybricks).

Связанные репозитории:

• Приложение: AzDeck в Google Play
• Библиотека Arduino: azdeck-lib
• Библиотека Pybricks: azdeck-pybricks

С чего начать

1. Прочитайте спецификацию протокола: транспорты, JSON-команды, телеметрия и настройки устройства.
2. Загрузите короткий JSON-пример esp32_websocket_minimal.
3. Переходите к специализированным примерам только после проверки связи.
4. Для компактного Arduino API удобнее azdeck-lib, чем копировать большой скетч.

Выбор прошивки

Прошивка	Плата	Связь	Назначение
esp32_websocket_minimal	ESP32	WebSocket	Минимальный JSON-пример: команды, telemetry, ping/pong и fail-safe
esp32_mecanum_websocket	ESP32	WebSocket	Полный пример: четыре mecanum-мотора, два серво и страница настроек на плате
esp32_cam_websocket_test	ESP32-CAM	WebSocket	Проверка команд, телеметрии и встроенной вспышки
esp8266_websocket_test	ESP8266	WebSocket	Простой тест команд и телеметрии
esp32_ble_azdeck_test	ESP32	BLE	Проверка BLE-команд и уведомлений с телеметрией
esp32_classic_bt_test	ESP32	Bluetooth SPP	Проверка Classic Bluetooth с JSON/строками

Для хабов LEGO с прошивкой Pybricks используйте azdeck-pybricks, а не эти ESP-скетчи.

Дополнительная документация:

• точная спецификация протокола на русском;
• protocol specification in English;
• подробное руководство на русском;
• подробное руководство на английском.

Подготовка Arduino IDE

1. Установите Arduino IDE.
2. Через Boards Manager установите пакет:
   • esp32 от Espressif Systems для плат ESP32;
   • esp8266 от ESP8266 Community для плат ESP8266.
3. Через Library Manager установите библиотеки, необходимые выбранному скетчу:
   • WebSockets от Markus Sattler;
   • ArduinoJson от Benoit Blanchon;
   • ESP32Servo для mecanum-прошивки с сервоприводами.
4. Откройте .ino из каталога выбранной прошивки.
5. Выберите плату и последовательный порт.
6. Загрузите скетч.

Preferences и WebServer, используемые mecanum-прошивкой, входят в пакет ESP32.

WebSocket

WebSocket-прошивки по умолчанию создают точку доступа:

Wi-Fi:       AzDeck-Test
Пароль:      azdeck123
WebSocket:   ws://192.168.4.1:81
Настройки:   http://192.168.4.1/settings   (пример mecanum)

Порядок подключения:

1. Загрузите скетч на плату.
2. Подключите Android-устройство к сети AzDeck-Test.
3. В профиле AzDeck выберите транспорт WebSocket.
4. Укажите адрес ws://192.168.4.1:81.
5. Подключитесь к контроллеру.

AzDeck отправляет снимки каналов в JSON. Совместимые скетчи могут понимать простые строки KEY:value для отладки через Serial — это не опция профиля в приложении.

Если прошивка отвечает на HEAD /settings с заголовком X-AzDeck-Settings: 1, приложение включает кнопку Settings и открывает страницу в Custom Tabs. См. протокол.

BLE

Скетч esp32_ble_azdeck_test объявляет устройство AzDeck BLE.

Service: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
Write:   6E400002-B5A3-F393-E0A9-E50E24DCCA9E
Notify:  6E400003-B5A3-F393-E0A9-E50E24DCCA9E

В профиле AzDeck:

1. Выберите транспорт BLE.
2. Выберите устройство AzDeck BLE.
3. Укажите приведённые выше GATT-характеристики Write и Notify.

Classic Bluetooth / SPP

Скетч esp32_classic_bt_test объявляет устройство AzDeck Classic.

Стандартный SPP UUID:

00001101-0000-1000-8000-00805F9B34FB

Порядок подключения:

1. Выполните сопряжение с AzDeck Classic в настройках Android.
2. В профиле AzDeck выберите транспорт SPP.
3. Выберите сопряжённое устройство.
4. Оставьте стандартный SPP UUID.

SPP-прошивка передаёт пакеты UTF-8, разделённые переводом строки.

Pybricks

AzDeck подключается к хабам Pybricks по BLE. Сохраните программу с azdeck.py, остановите Pybricks Code, затем нажмите «Подключить» в AzDeck — программа на хабе запустится. Имена каналов в профиле должны совпадать с Python (x1, y1, b1… по умолчанию).

Кратко о протоколе

Имена каналов в профиле должны совпадать с ключами в прошивке. Они чувствительны к регистру. Короткие имена по умолчанию в новых макетах AzDeck: b1, x1/y1, u1/r1/d1/l1, sp1. Свои имена тоже допустимы:

{"x1":0.75,"y1":-0.25,"b1":1}

Контроллер может вернуть telemetry отдельным сообщением:

{"type":"telemetry","battery":87,"speed":42}

WebSocket-команды AzDeck приходят как binary frames. Полные правила framing, тайминги, ping/pong и настройки устройства — в спецификации протокола.

Безопасность

• Сначала проверяйте входящие команды через Serial Monitor без подключённых двигателей.
• При загрузке прошивки отключайте питание силовой части.
• Проверяйте распиновку, напряжение логики и общий GND.
• Не питайте двигатели и мощные сервоприводы напрямую от платы ESP.
• Используйте отдельный источник питания, рассчитанный на нагрузку.
• Обязательно останавливайте двигатели по тайм-ауту связи.
• Перед применением настроек проверяйте допустимость и отсутствие дублирования GPIO.
• Добавьте физическую аварийную остановку для опасных или мощных механизмов.

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