Foreground Android preview

Keyboard Helper Companion

Приложение для телефона: просмотр раскладок, данные подключения и совместимая read-only Live-телеметрия. Инструкция отделяет опубликованный APK от более новых изменений в репозитории.

Опубликованный артефакт

Signed v0.6.4 preview for API 31+ arm64 devices. Публичная physical-device baseline: Android 12 / API 31+ на arm64-v8a.

Открыть релиз v0.6.4

1. Скачать, проверить, установить

Откройте опубликованный релиз и скачайте Keyboard-Helper-Companion_<version>_android-arm64_preview.apk вместе с соседним .sha256.
Сравните SHA-256 APK со значением в sidecar-файле.
Откройте APK и разрешите unknown-app install только для приложения, из которого открываете файл.
Запустите Keyboard Helper Companion. При подключении выдайте Nearby devices.

Если Android отклоняет обновление поверх debug APK, подписи разные. Удалите debug app и установите подписанный preview. Приватные imports и permission state могут сброситься.

2. Pair и connect

Разбудите клавиатуру и выберите свободный ZMK Bluetooth profile.
Сначала спарьте клавиатуру в Android Settings.
В v0.6.4 нажмите Connect, выберите bonded keyboard и дождитесь Connection: connected.
Battery Service и Device Information появятся только если клавиатура их отдаёт.

3. Browse workspace

Browse показывает раскладки со stock или enhanced ZMK firmware. Companion работает в foreground: выбранная клавиатура, highlights и Live session не сохраняются как фоновый сервис.

Есть в репозитории, но не в v0.6.4. Новый adaptive workspace переносит device actions в Settings > Connection, custom definitions в Settings > Layouts, а Live diagnostics в Settings > Status.

4. Свои раскладки

Companion импортирует один JSON-документ Keyboard Helper. После проверки он атомарно копирует definition и inline image bytes в private app storage. Source URI не сохраняется.

Text-only layouts поддерживаются.
Раскладки с изображениями используют keyboard-helper-layout version 1, таблицу embeddedAssets и ссылки вида asset:<id>.
Изображения: PNG, JPEG или WebP без анимации. Лимиты: 128 KiB на картинку, 512 KiB decoded bytes суммарно, 16 assets, 256 x 256 px, 1 MiB на JSON.
External paths, remote URLs, data URLs, SVG, битый base64 и неиспользуемые assets отклоняются.
Удаление custom layout удаляет его приватные изображения. Desktop и Android не синхронизируют раскладки через облако.

5. Read-only Live

Stock firmware подходит для Browse и connection overview. Live требует совместимое enhanced firmware extension и читает layer, key, combo и diagnostic telemetry. Телефон не пишет remote layer.

Используйте Live control в v0.6.4. Путь Settings > Status относится к более новой unpublished workspace.

6. Граница поддержки

Public preview

Физическая BLE-проверка и downloadable preview baseline: Android 12 / API 31+ и arm64-v8a.

Android 11 evidence

Есть deterministic UI/runtime evidence для Browse startup на Android 11 / API 30 с WebView 91. Это не обещание physical BLE support.

Package minimum

Declared minimum SDK может позволять установку ниже baseline, но это не обещает поддержку всех BLE-сценариев.

7. Диагностика

Нет Bluetooth, permission или scan пустой

Выдайте Nearby devices, включите Bluetooth, разбудите клавиатуру, проверьте Android pairing и повторите подключение.

PIN, security, capacity или reconnect exhaustion

Удалите pairing в Android, очистите выбранный ZMK Bluetooth profile, перезапустите обе стороны, спарьте заново и подключитесь.

Live waiting, unsupported protocol или sequence gap

Stock firmware честно сообщает, что Live недоступен. На enhanced firmware нажмите клавишу или смените физический слой. Если waiting остаётся, reconnect.

Layout mismatch или invalid stored layout

Выберите раскладку, где есть reported layer. Если JSON отклонён, проверьте version, asset references, bitmap type, base64, dimensions, byte limits и duplicate name.

Короткие ответы есть в FAQ. Для desktop-оверлея откройте настройку desktop.