SplitOverlay/README.md

SplitOverlay

Русский · English below

Название репозитория — SplitOverlay. В коде, в имени exe, установщика и в папке настроек приложение называется KeyOverlay.

Полупрозрачный оверлей для Windows, который поверх всех окон показывает раскладку программируемой (Vial / QMK) split-клавиатуры, например Silakka54. Нужен, чтобы учить слои: смотришь на экран и видишь, что где лежит.

Возможности

• Рисует плату по файлу раскладки Vial (.vil): все слои, MO/TG/LT/mod-tap, Shift+цифра и т.д.
• Прозрачные клавиши слоя (KC_TRNS) показываются приглушённо с нижнего слоя, как в QMK.
• Автоопределение слоя с платы (нужна прошивка с командой из firmware/); без неё слой переключается вручную.
• Символы по языку ввода: буквы на клавишах меняются вместе с раскладкой Windows (RU, EN и любая другая). Нужные символы выдаёт сама Windows.
• Разделение половинок: каждая половина отдельным окном, двигаются независимо.
• Подсветка нажатых клавиш, регулировка прозрачности и размера, значок в трее.
• Оверлей прозрачен для мыши и не забирает фокус.

Слой 1	Разделение половинок	Язык ввода

Установка

Скачай со страницы Releases установщик KeyOverlay-<версия>-setup.exe или портативный KeyOverlay-<версия>-portable.zip. Установка идёт без прав администратора. Exe не подписан, поэтому SmartScreen может предупредить («Подробнее» → «Выполнить в любом случае»).

Раскладку сохрани в Vial: File → Save current layout (.vil). При первом запуске приложение попросит выбрать этот файл; можно также передать путь аргументом: KeyOverlay.exe "путь\к\раскладке.vil".

Управление

Действие	Как
Следующий / предыдущий слой	Ctrl+Alt+PgDn / Ctrl+Alt+PgUp (отключает автоопределение)
Показать / скрыть	Ctrl+Alt+K или двойной клик по значку в трее
Прозрачность, размер, слой, язык, разделение, перечитать файл	меню значка в трее
Переместить оверлей	трей → «Режим перемещения», тащить мышью, колесо меняет размер

Прошивка (для автоопределения слоя)

Обычная клавиатура не сообщает ПК, какой слой активен, и в протоколе Vial такой команды нет. Поэтому в firmware/ лежит небольшое дополнение для QMK/Vial: команда HID 0xE0, которая возвращает активный слой. Подробности, сборка и инструкция по прошивке: firmware/README.md. Готовые .uf2 для Silakka54 (LED, v1.4led) лежат в Releases.

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

Нужен .NET 8 SDK под Windows.

git clone https://gittea.khad1997pav.ru/khadzhibekovpa/SplitOverlay.git
cd SplitOverlay
dotnet test tests/KeyOverlay.Core.Tests
dotnet run --project src/KeyOverlay -- "путь\к\раскладке.vil"

Установщик и портативная сборка (Inno Setup берётся из NuGet, в систему ничего не ставится):

dotnet publish src/KeyOverlay -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -o dist/app
dotnet restore installer/tools.csproj
installer/packages/tools.innosetup/6.4.3/tools/ISCC.exe /DAppVersion=1.0.0 installer/KeyOverlay.iss

Установщик кладёт в пакет файлы прошивки из firmware/*.uf2: соберите их (см. firmware/README.md) или скачайте из Releases и положите в firmware/.

Устройство проекта

src/KeyOverlay.Core   парсер .vil, подписи кейкодов, геометрия платы, протокол слоя (без зависимости от Windows)
src/KeyOverlay        WPF-оверлей: окна, хук клавиатуры, опрос платы по HID, язык ввода, трей
tests/                тесты Core (xUnit)
firmware/             команда слоя для QMK/Vial и сборка прошивки в Docker
installer/            скрипт Inno Setup

Как это работает

Core (src/KeyOverlay.Core, .NET 8, без зависимости от Windows, покрыт тестами):

• Keymap читает .vil (JSON): поле layout — слои × 10 строк матрицы × 6 колонок. Строки 0–4 — левая половина, 5–9 — правая, -1 — клавиши нет. Прозрачные клавиши (KC_TRNS) проваливаются на нижний слой, как в QMK.
• Keycodes превращает кейкоды Vial/QMK в подписи (KC_BSPACE → «Bksp», LSFT(KC_1) → «!», MO(2) → «MO 2»).
• BoardGeometry — положение клавиш Silakka54: 4×6 с шагом по колонкам и 3 больших пальца на половину.
• ScanCodes и PressedKeys — разбор скан-кодов (физическая клавиша не зависит от языка) и учёт нажатых.
• LayerProtocol — формат команды слоя для прошивки; KeyLocalizer — замена подписей по языку ввода.

Приложение (src/KeyOverlay, WPF):

• Окно прозрачное, без рамки, поверх всех окон; стили WS_EX_TRANSPARENT | WS_EX_NOACTIVATE | WS_EX_TOOLWINDOW делают его прозрачным для мыши, без фокуса и без значка в панели задач.
• KeyboardHook — глобальный low-level hook: подсветка нажатых клавиш и горячие клавиши. События всегда передаются дальше.
• LayerPoller — раз в ~80 мс спрашивает плату по Raw HID (usage page 0xFF60, usage 0x61, библиотека HidSharp), реконнект при отключении.
• InputLanguage — язык берётся у окна на переднем плане (GetKeyboardLayout), символы клавиш вычисляет Windows (ToUnicodeEx).
• OverlayController связывает окна, хук, опрос платы, трей и настройки; режим разделения создаёт второе окно для правой половины.

Поддерживаемые кейкоды

Что	Примеры
Буквы, цифры, знаки, F1–F24	KC_A, KC_1, KC_SCOLON, KC_F12
Навигация и служебные	KC_ENTER, KC_BSPACE, KC_DELETE, стрелки, KC_PGUP, KC_HOME, KC_PSCREEN
Модификаторы	KC_LSHIFT, KC_RCTRL, KC_LALT, KC_LGUI
Медиа	KC_MPLY, KC_VOLU, KC_BRIU
Обёртки с модификаторами	LSFT(KC_1), LCTL(KC_C) (а также S, C, A, G, правые варианты)
Слои	MO(n), TG(n), TO(n), TT(n), OSL(n), DF(n), LT(n, kc)
Mod-tap	LCTL_T(kc), MT(MOD_LSFT, kc)
Прозрачная / пустая	KC_TRNS, KC_NO

Всё остальное (макросы, tap dance, QK_BOOT и т.п.) показывается сокращённым именем кейкода без расшифровки. Сейчас геометрия рассчитана на Silakka54 (матрица 10×6, 54 клавиши); для других плат нужна своя геометрия.

Настройки

Файл %APPDATA%\KeyOverlay\settings.json создаётся автоматически и меняется через меню трея.

Поле	Значение
VilPath	путь к файлу раскладки .vil
Opacity	прозрачность 0.2–1.0
Scale	размер 0.5–2.0
Left, Top	позиция окна (левой половины в режиме разделения)
RightLeft, RightTop	позиция правой половины в режиме разделения
Layer	последний выбранный вручную слой
AutoLayer	определять слой по данным платы
HighlightPressed	подсвечивать нажатые клавиши
LocalizeKeys	показывать символы выбранного языка ввода
SplitHalves	показывать половинки отдельными окнами

Чтобы сбросить настройки, закрой приложение и удали этот файл.

Если что-то не работает

• В подписи «плата не отвечает». Авто-определение слоя работает только с прошивкой из firmware/. Проверь, что прошиты обе половины, кабель подключён к главной (для файла LEFT — левой), а Vial закрыт. Пока слой можно выбрать вручную (Ctrl+Alt+PgUp/PgDn).
• Оверлея не видно. Нажми Ctrl+Alt+K или двойной клик по значку в трее. Если окно осталось за пределами экрана, удали settings.json.
• SmartScreen / антивирус ругается. Exe не подписан, а приложение использует глобальный перехват клавиш (нужен для подсветки). Исходники открыты, собрать можно самому.
• Поверх игры оверлея нет. Окно показывается поверх оконных и borderless-приложений, но не поверх эксклюзивного полноэкранного режима.
• Буквы не меняются при смене языка. Проверь пункт «Символы по языку ввода» в меню трея. Язык берётся у окна, в которое ты печатаешь.

Идеи и планы

• Геометрия других плат (описание в JSON), имена слоёв.
• Подпись exe и автообновление.
• Автоматическое отслеживание изменений файла .vil.

Участие

Issues и pull request приветствуются. Перед отправкой запусти dotnet test tests/KeyOverlay.Core.Tests; CI делает то же самое и собирает приложение.

Приватность

Перехват клавиш (low-level hook) нужен только для подсветки нажатых клавиш и горячих клавиш. Нажатия нигде не сохраняются и не отправляются, события всегда передаются дальше без изменений. Приложение ничего не отправляет в сеть. Настройки лежат в %APPDATA%\KeyOverlay\settings.json.

Ограничения

• Только Windows (WPF), x64.
• Определение слоя с платы работает через Raw HID и требует прошивки с командой 0xE0; половина, подключённая к ПК, должна быть главной.
• Caps Lock на подписях не отражается; мёртвые клавиши показываются знаком акцента.
• Vial GUI и оверлей не стоит держать открытыми одновременно: оба общаются с одним HID-интерфейсом.

Лицензия

Приложение: MIT. Дополнение для прошивки (firmware/keyoverlay_hid.c) собирается внутрь QMK/Vial и распространяется под GPL-2.0-or-later. Исходники плат и Vial принадлежат их авторам: vial-qmk, Squalius-cephalus/silakka54.

---

English

KeyOverlay is a semi-transparent, click-through Windows overlay that shows the keymap of a programmable (Vial / QMK) split keyboard such as the Silakka54, always on top, to help you learn your layers.

Features: draws the board from a Vial .vil layout (all layers, MO/TG/LT/mod-tap, transparent keys falling through to lower layers); detects the active layer from the keyboard via a small QMK/Vial firmware command (firmware/); shows the characters of the active Windows input language; can split the two halves into separate windows; highlights pressed keys; tray icon with opacity/size options.

Install: download the setup or portable zip from Releases; save your layout in Vial via File → Save current layout and pick that .vil on first run. Build: .NET 8 SDK, dotnet test tests/KeyOverlay.Core.Tests, dotnet run --project src/KeyOverlay. Windows only (x64). Key hook is used only for highlighting and hotkeys; nothing is stored or sent.

License: MIT for the app; the firmware add-on is GPL-2.0-or-later (it is compiled into QMK/Vial).