Основы интеграции

Общие правила для всех устройств DzenTech. Особенности конкретного устройства — на его странице.

BLE

Типовая последовательность:

1. запустить BLE scan;
2. выбрать устройство по имени и стабильному идентификатору;
3. установить GATT-соединение;
4. найти требуемые service и characteristic;
5. включить notifications, если устройство возвращает ответы асинхронно;
6. отправить liveness/status query;
7. считать устройство готовым только после корректного протокольного ответа;
8. сериализовать все операции записи для одного устройства;
9. при отключении прекратить новые команды, отменить ожидания и закрыть GATT objects.

Все контроллеры используют:

• service UUID: 0000FFE0-0000-1000-8000-00805F9B34FB;
• characteristic UUID: 0000FFE1-0000-1000-8000-00805F9B34FB.

Это GATT-UUID, а не фильтры сканирования

UUID выше — то, что вы обнаруживаете после подключения. То, что устройство рекламирует, может отличаться: MixUp Backlight v2 рекламирует E0FF, а FFE0 / FFE1 отдаёт только по GATT. Отфильтруете сканирование по FFE0 — это устройство не найдётся вообще.

Сканируйте по имени, принимая все известные alias, и проверяйте service уже после подключения.

Один callback, произвольное число кадров

Граница notification — не граница кадра, причём в обе стороны. Callback может принести неполный ответ, а может — сразу несколько: эхо вместе со статусом или один и тот же ответ дважды.

Поэтому клиент должен накапливать данные до terminator, а затем извлекать из буфера все завершённые кадры, а не только первый, и не рассчитывать, что одна запись даёт один notification. Второй кадр — это данные, а не мусор в хвосте.

USB

Общие параметры последовательного порта:

• 8 data bits;
• no parity;
• 1 stop bit;
• flow control отключён.

Baud rate зависит от устройства:

• GlamBot: 115200;
• Spinner360: 9600.

ASCII-команды заканчиваются байтом 0D (\r). LF не добавляется.

Драйвер CP210x

USB-порт наших устройств выведен через мост USB-to-UART Silabs CP210x. В Windows порту может потребоваться драйвер CP210x VCP, прежде чем он определится как COM-порт: Скачать драйверы CP210x. Камеры и принтеры используют свои драйверы и это не затрагивает.

Состояние соединения

Открытый BLE или COM transport ещё не означает, что устройство готово. Рекомендуется различать:

• transportConnected — канал открыт;
• protocolReady — получен корректный ответ устройства;
• desiredState — запрошенное состояние;
• actualState — состояние, подтверждённое ответом.

Успешная GATT/COM запись подтверждает передачу данных в transport, но не выполнение команды устройством.

Этот зазор не теоретический — это самая частая причина команд, которые «отправились, но ничего не сделали». На железе он проявляется в двух видах:

• Сразу после подписки. Запросы, отправленные тут же после включения notifications или плотным burst, могут потеряться до того, как парсер заработал. Распределяйте начальные запросы во времени — на Spinner360 примерно по 400–500 мс — и повторяйте тот, ответ на который не пришёл.
• Между повторяющимися командами. Относительным шаговым командам нужен реальный интервал: MixUp Pixel v1 теряет шаги при паузе меньше 120 мс, хотя каждая запись была подтверждена.

Цифры по устройствам — на их страницах. Если сомневаетесь, привязывайте отправку следующей команды к ответу, а не к подтверждению записи.

Retry и reconnect

Рекомендуемая базовая политика:

1. не более трёх попыток идемпотентной команды;
2. интервал 300–500 ms;
3. после исчерпания попыток закрыть transport;
4. подключиться заново;
5. повторно прочитать status;
6. не повторять non-idempotent команды без проверки actual state.

Диагностика

Устройство вообще не появляется в сканировании

• не фильтруйте сканирование по service UUID — рекламируемый и GATT-UUID различаются (см. BLE);
• сверяйте все известные alias имени, а не только основную маску: MixUp Backlight v2 встречается и как SPStellar;
• молчание Spinner360 на V? не означает несовместимость контроллера — не подтверждены только версия и поддержка ускорения. Базовые команды проверяйте отдельно.

BLE подключён, characteristic не найдена

Проверить:

1. выбран ли правильный device identifier;
2. совпадают ли service и characteristic UUID;
3. завершён ли service discovery;
4. не закрыт ли GATT object параллельной операцией;
5. не используется ли устаревший GATT cache;
6. включены ли notifications до команды с быстрым ответом.

Write успешен, устройство не изменилось

• проверить режим characteristic write with/without response;
• сериализовать writes;
• разносить по времени повторяющиеся команды — подтверждённая запись не значит применённая;
• прочитать status после команды;
• MixUp Pixel v1: всегда читать power перед toggle; держать ≥ 120 мс между шагами скорости; ожидать внеочередной status после toggle и дубль, если следом сделать запрос;
• MixUp Backlight v2: перед value повторно выбрать RGB/white mode; скорость эффекта — шкала 0…10, прошивка ограничивает значения выше 0A;
• Spinner360: проверить decimal/hex интерпретацию — set-команды принимают decimal, а ответы приходят в hexadecimal с префиксом P (скорость) или C (ускорение);
• MixUp White: проверить преобразование процентов в 0..255.

USB не отвечает

Проверить:

• правильный COM port;
• baud rate;
• 8N1;
• отключённый flow control;
• terminator 0D;
• отсутствие другого процесса, удерживающего порт.

Быстрое отключение

При disconnect:

1. запретить новые команды;
2. отменить текущие ожидания;
3. завершить notification subscription;
4. закрыть characteristic, service и device;
5. не использовать старые GATT objects после reconnect.

Операции close/unsubscribe не должны выполняться синхронным blocking wait в UI/STA thread.