Настройка Keyboard Helper

Установите приложение, выдайте права на глобальный ввод и выберите раскладки. Всё остальное настраивается из меню оверлея.

1. Скачать

Откройте GitHub Releases и выберите сборку для своей платформы: macOS Apple Silicon, macOS Intel, Windows или Linux.

1. Для macOS скачайте архив под свой процессор. M-series - macos-apple-silicon, Intel - macos-intel.
2. На macOS скачайте соседний .sha256, откройте .dmg и перенесите Keyboard Helper.app в Applications.
3. На Windows запустите .msi.
4. На Linux распакуйте архив и запустите binary.

shasum -a 256 -c Keyboard-Helper_*.dmg.sha256

Android Companion

Android Companion устанавливается отдельно. Он показывает раскладки, состояние подключения и совместимый read-only Live. APK публикуется в GitHub Releases, не в Google Play.

Открыть инструкцию по Android Companion

2. Первый запуск

1. На macOS попробуйте открыть установленное приложение.
2. Если Gatekeeper блокирует запуск, откройте System Settings -> Privacy & Security, найдите блок Security, нажмите Open Anyway для Keyboard Helper и подтвердите Open.
3. Выдайте Input Monitoring. Без него приложение не увидит глобальные нажатия.
4. Начните печатать в любом приложении. Оверлей должен показать QWERTY и подсветить клавиши.

Если подсветка пропала после обновления, удалите старые записи Keyboard Helper или Keyboard Layout из Input Monitoring, добавьте /Applications/Keyboard Helper.app и перезапустите приложение.

3. Меню приложения

Главные действия находятся в меню справа сверху. На macOS часть команд также доступна в native menu bar.

4. Конфигурация

Откройте Settings. Там включаются встроенные раскладки, выбирается стартовая раскладка, записывается show/hide shortcut и добавляется внешний JSON-файл.

Файл настроек

Основной файл - ~/.keyri.json. Старый ~/keyri.json всё ещё читается. Если файла нет, включаются все встроенные раскладки, стартовая - QWERTY.

{
  "defaultLayout": "corne",
  "layouts": {
    "corne": true,
    "qwerty": true
  },
  "toggleHotkey": "Shift+Meta+K"
}

Для своей раскладки обычно проще нажать Add layout file... в Settings. За основу можно взять один из JSON-файлов в src/.

5. Mini Mode

Mini Mode оставляет компактное окно с активным слоем и подсветкой клавиш. Меню и лишний chrome скрываются. Режим временный: новый запуск снова открывает полное окно.

6. Keyboard Self-test

Self-test проверяет HID-коды выбранной раскладки и слоя. Вы сами активируете слой на клавиатуре, затем нажимаете подсвеченные позиции.

• Passed - пришёл ожидаемый press-and-release.
• Unexpected - пришёл другой код.
• Skipped - вы пропустили позицию без подходящего события.
• Not testable - позиция пустая, неподдерживаемая или описывает сложное поведение.

7. ZMK BLE layer sync

Если раскладка содержит bleLayerSource, Keyboard Helper слушает активный слой совместимой ZMK-клавиатуры и обновляет оверлей по состоянию firmware.

После сна клавиатуры, смены Bluetooth-разрешений или правки metadata используйте Connection > Reconnect BLE.

8. Синхронизация языка macOS

Внешняя раскладка может связать macOS input-source ID с семействами слоёв ZMK. Приложение выбирает точный input source и корректирует стабильное несовпадение базового слоя через writable BLE characteristic.

defaults read ~/Library/Preferences/com.apple.HIToolbox.plist AppleEnabledInputSources

9. Shift-Space Invaders

Игра открывается отдельным окном и использует focused input. Глобальная подсветка оверлея может продолжать работать отдельно.

10. Сборка из исходников

Нужны Node.js LTS, Rust toolchain и Tauri v2 platform deps.

git clone https://github.com/maxistar/keyboard_helper.git
cd keyboard_helper
npm install
npm run tauri dev
npm run tauri build

Короткие ответы по частым ошибкам есть в FAQ.