Настройка клавиатуры в ZMK keymap-editor

Содержание

Keymap-editor — это мощный инструмент для настройки клавиатуры на ZMK, позволяющий удобно и быстро воплотить идею в готовую раскладку. В статье описана процедура подключения keymap-editor и основные возможности с точки зрения как нового пользователя, только начинающего погружение в мир сплит-клавиатур, так и уже знакомого с сплит-клавиатурами и настройкой раскладки в Vial.

Начало работы с keymap-editor

Keymap-editor является веб-приложением, он доступен из браузера по адресу https://nickcoutsos.github.io/keymap-editor/. Чтобы им воспользоваться, требуется выполнить несколько условий:

Пользователь должен быть зарегистрирован на https://github.com/
Пользователю нужен форк репозитория https://github.com/ergohaven/ergohaven-zmk-config

В форке надо включить GitHub Actions для автоматической сборки прошивки после внесения изменений в раскладку, переходим на вкладку Actions и нажимаем кнопку I understand my workflows, go ahead and enable Actions.
Переходим на страницу https://nickcoutsos.github.io/keymap-editor/, на открывшейся странице выбираем GitHub, авторизуемся и предоставляем доступ к созданному форку для Keymap Editor. Для предоставления доступа отмечаем опцию Only select repositories, и выбраем Ваш форк репозитория /ergohaven/ergohaven-zmk-config. Далее нажимаем Save для сохранения настроек доступа.

Когда описанные выше шаги выполнены, раскладка готова к внесению изменений, ура! Переходим на страницу https://nickcoutsos.github.io/keymap-editor/ и видим раскладку по умолчанию.

Переназначение клавиш

Чтобы переназначить какую-то клавишу, кликаем на нее, и откроется окно выбора нового Поведения этой клавиши.

В окне надо выбрать Behavior (далее Поведение) для этой клавиши. Поведение — это сущность в ZMK, определяющая какое именно действие будет произведено при нажатии клавиши, например &kp (Key Press) просто отправляет в ОС нажатие клавиши. Каждый &kp имеет параметр Key Code, в котором мы указываем какая конкретно клавиша будет нажата, на скриншоте выше в этом параметре указана клавиша Q. Если мы хотим назначить вместо Q, например, Z, то надо кликнуть на поле Key Code.

Окно разворачивается и в правой части отображается список доступных для назначения кей-кодов. В поисковую строку доступных кей-кодов вводим Z, выбираем Z среди отфильтрованных кодов, нажимаем Okay и готово, клавиша заменена!

Над списком кейкодов есть чекбоксы с модификаторами Shift, Alt, Ctrl и Gui, с префиксами “L” и “R”, обозначающими левый или правый модификатор. Если отметить один из чекбоксов модификаторов, то в ОС отправится сочетание клавиш с отмеченным модификатором. Например, если бы в окне выше мы отметили чекбокс LCtrl, то при нажатии на клавишу сразу отправилось бы сочетание LCtrl + Z. Удобно, нажатием одной клавиши сразу делаем сочетание клавиш!

Далее внесенные изменения надо сохранить, нажимаем Save в левом верхнем углу, при желании можно дать название внесенному изменению, или оставить поле пустым и нажать Commit.

Прошивка автоматически начала собираться, обычно этот процесс занимает около двух минут. Нажмём на синюю кнопку с статусом сборки.

На открывшейся странице отображены статусы всех этапов сборки. После выполнения всех этапов появится раздел Artifacts, содержащий архив firmware, кликаем на него для скачивания.

После скачивания архива firmware прошиваем файлами из него клавиатуру по шагам, описанным в первых шагах с клавиатурой на ZMK (см. раздел «Прошивка клавиатуры»).

Изменения в раскладку внесены!

Слои

В сплит-клавиатурах используются слои, это своего рода дополнительные модификаторы, как Shift или Control, и переключив клавиатуру на другой слой, нажатия клавиш будут регистрировать уже другие символы или функции, назначенные на эту клавишу на этом слое.
Звучит сложно, надо рассмотреть на примере:
Если нажать и не отпускать красную клавишу на левой половинке, то клавиатура переключится на 1 слой, и нажав, например, клавишу W, в ОС отправится нажатие клавиши 2, т.к. в раскладке по умолчанию она назначена на позицию W на 1-м слое.

Переименование слоёв

Слоям можно изменять названия, это может облегчить конфигурирование раскладки, для этого наводим курсор на название слоя и нажимаем кнопку Edit с иконкой карандаша.

Переключение слоёв

В ZMK для переключения слоев есть несколько Поведений:

&mo

&mo — активирует указанный слой при удержании клавиши нажатой. Именно это Поведение используется в стандартной раскладке, на красной клавише назначено &mo 1, и при удержании её зажатой активируется 1-й слой.

&lt

&lt — гибридное Поведение стандартного нажатия на клавишу (&kp) и активации слоя при удержании клавиши нажатой (&mo). Например, на красную клавишу, на которой в стандартной раскладке &mo 1, назначим &lt, передав в параметры: 1-й слой и кей-код Space, и тогда при нажатии на нее будет печататься пробел, а при удержании будет происходить изменение слоя, чистая магия!

Стоит заметить, что таким образом мы сократили количество занятых клавиш на 0-м слое, ведь изначально &kp Space и &mo 1 были на двух отдельных клавишах, нажимаемых большим пальцем, а теперь мы объединили их в одну, и теперь можно расположить на месте &kp Space какое-нибудь другое Поведение.

&tog

&tog — при нажатии переключает состояние слоя, то есть включает указанный слой, если он выключен, и наоборот, выключает его, если он включен. (аналог TG() из Vial)
При использовании этого Поведения стоит помнить что активным на данный момент является включенный слой с самым большим номером, то есть, включив слой нажатием &tog 2, невозможно переключиться на 1-й слой нажатием &mo или &tog, ведь он имеет меньший номер, и несмотря на то что нажатие &tog 1 включит 1 слой, активным всё равно останется 2-й слой т.к. он имеет больший номер. Чтобы переключиться на слои с номером ниже на 2-м слое надо расположить клавишу &tog 2.
Для закрепления пошагово разберем сценарий работы с &tog:

Находясь на 0-м слое нажат &tog 2 — слой 2 включен, переключиться на 1-й слой нажатием &tog 1 или &mo 1 не получится;
Находясь на 2-м слое нажат &tog 2 — слой 2 выключен, клавиатура вернулась на 0-й слой, и мы можем переключаться на 1-й слой.

&to

&to — при нажатии включает слой, указанный в параметре, и выключает все остальные активные слои.
Это Поведение очень удобно для переключения на слой по нажатию, ведь в отличие от &tog, Поведение &to выключает все активные слои, и нет необходимости отдельно выключать текущий активный слой.
Пример: находясь на 0-м слое нажат &to 2 — слой 2 включается, мы можем переключиться на 1-й слой нажатием &to 1, ведь это поведение помимо включения слоя 1, выключает все остальные активные слои, в данном случае 2-й.

&sl

&sl — при нажатии включает слой, указанный в параметре, но лишь на одно нажатие. (аналог OSL() из Vial)
Удобно использовать это Поведение для переключения на слой с функциональными клавишами, ведь чаще всего их требуется нажать 1 раз. Нажали &sl 3 (на этом слое в раскладке по умолчанию F1-12 клавиши), слой включился, нажали клавишу F1, и слой сразу же автоматически выключился.

Также важно упомянуть, что если после переключения на слой через &sl в течение 1 секунды не произойдет нажатия, то слой автоматически выключится. Этот таймаут конфигурируется в разделе Behaviors -> Reconfiguration, подробнее в разделе Behaviors.

Перемещение слоёв

Иногда при настройке раскладки возникает необходимость перемещения целого слоя на другую позицию, в keymap-editor это реализовано очень удобно, достаточно просто перетащить слой на нужную позицию.

При перемещении слоя таким образом, keymap-editor автоматически подстраивает параметры всех Поведений, ранее активировавших этот слой, например, в раскладке есть &mo 2, если переместить 2-й слой на позицию 1-го слоя, то назначенная клавиша &mo 2 автоматически изменится на &mo 1.

Копирование слоёв

Еще одной полезной возможностью управления слоями является их копирование.
Чтобы сделать копию надо нажать на кнопку … рядом с названием слоя и выбрать Duplicate Layer. После нажатия будет создана полная копия слоя.

Быстрое назначение клавиш

На любом слое можно быстро переназначить клавиши, нажав на кнопку … рядом с названием слоя и выбрав Quick &kp Assignment.

В открывшемся окне удобно назначать нажатия цифр, букв, и функциональных клавиш

Несколько полезных Behaviors

`&mt`

Поведение Mod/Tap позволяет назначить определённое Поведение на короткое нажатие (TAP) клавиши, и другое Поведение на зажатие (HOLD) клавиши. (Аналог клавиш LShift_T, LCtrl_T и т.д. с вкладки Quantum из Vial)
По умолчанию коротким нажатием считается нажатие, длящееся менее 200 миллисекунд, если зажали дольше, то регистрируется зажатие.

Если настроить Поведение как на скриншоте выше, то при коротком нажатии клавиши напечатается буква D, а при зажатии — будет зажат левый Shift.

`&sk`

При нажатии Sticky Key задерживает клавишу нажатой, и отпускает её после следующего нажатия любой другой клавиши. (Аналог OSM из Vial)
Удобно использовать с модификаторами, назначив &sk LShift, не надо зажимать клавишу Shift, чтобы напечатать заглавную букву, а просто один раз нажать &sk LShift и сразу отпустить, следующая буква уже будет заглавной

Вкладка Behaviors

На вкладке Behaviors можно создать свои кастомные Поведения и настроить стандартные. Начнем с настройки стандартных.

Reconfigurations

Здесь мы можем изменить свойства стандартных Поведений, например тех, которые были описаны в разделе Слои.
Нажмём кнопку Add Behavior Reconfiguration, в открывшемся меню выберем, например &sl.

В открывшемся окне Reconfigure &sl видим ряд стандартных свойств, которые мы можем изменить. Давайте увеличим таймаут для &sl, чтобы слой оставался активным не 1 секунду, а 3, для этого в строке свойства release-after-ms кликаем кнопку Override и в появившемся поле вводим 3000 (единицы измерения в поле — миллисекунды), и нажимаем Okay.

В разделе Reconfigure появилась запись &sl с переопределёнными свойствами. Для просмотра свойств надо нажать кнопку Edit. Чтобы полностью вернуть свойствам стандартные значения нажмите кнопку Delete.
Подробная информация о всех свойствах Поведений в документации ZMK.

Custom Behaviors

В этом разделе мы можем создать своё кастомное Поведение, основанное на стандартных. Создадим Поведение, с которым будет удобно реализовать Home Row Mods (далее HRM), популярный подход к дизайну раскладки, основная идея которого состоит в том, что на клавиши домашнего ряда (A, S, D, F и J, K, L, ;), при удержании нажатыми, активируют модификаторы Shift, Ctrl, Gui или Alt.
Нажмём Add New Behavior, в открывшемся окне выберем Hold or Tap behavior.

В этом окне надо описать шаблон того, какие Поведения будут выполнены при нажатии и удержании, а также несколько свойств. Заполним свойства:

Bind: “hrm”. Название поведения, именно по нему мы можем найти Поведение при назначении на клавишу;
bindings — HOLD: &kp. При удержании клавиши нажатой будет нажиматься клавиша с модификатором, для этого подойдет обычный &kp;
bindings — TAP: &kp. Действие при кратковременном нажатии, для того чтобы нажать клавишу с буквой также подойдет &kp;
tapping-term-ms: 200. Если клавиша будет нажата менее чем 200 миллисекунд, то клавиатура зарегистрирует TAP и нажмётся клавиша, например D, если клавиша будет удержана нажатой более чем 200 миллисекунд, то зарегистрируется HOLD и нажмётся указанный в параметрах модификатор, например Ctrl.;
flavor: balanced. Есть несколько алгоритмов, позволяющих пользоваться HRM не завязываясь строго на тайминг из tapping-term-ms, balanced это как раз один из них, он подразумевает, что если HRM клавиша была нажата менее чем 200 миллисекунд, но за время нажатия HRM клавиши была нажата и отпущена другая клавиша, то надо зарегистрировать действие HOLD.

В документации ZMK есть пример создания HRM, не зависящего от таймингов полностью, не мешая технике печати и перекатам по клавишам. Идея состоит в том, что модификаторы строго нажимаются на одной половинке, а клавиша с буквой на другой половинке. В примере описаны свойства в виде кода, но в keymap-editor все свойства имеют такие же наименования и их легко адаптировать.

После заполнения свойств нажимаем Okay, и видим что наше кастомное Поведение было успешно создано.

Далее перейдём на вкладку Layers, и назначим созданное поведение на клавишу D. В окне назначения Поведения нам надо найти и выбрать созданный &hrm.

Заполним параметры:

В Parameters — HOLD надо указать кей-код желаемого модификатора, укажем Ctrl.
В Parameters — TAP надо указать кей-код клавиши, отправляемой по тапу, выберем D.

Интересной идеей может быть назначение HRM модификатора Ctrl на клавишу S, ведь тогда нажимать очень часто используемые сочетания Ctrl + C и Ctrl + V очень удобно одной рукой, попробуйте!

После заполнения параметров жмём Okay и наш первый Home Row Mod назначен!
Аналогичным образом назначаем HRM модификаторы на все остальные клавиши, и все модификаторы уже лежат под пальцами, чтобы их достать больше не надо смещать руку.

Совет: можно создать несколько Поведений с разным Tapping Term для разных пальцев. Например, для мизинца (который слабее указательного) стоит задать большее значение Tapping Term, чтобы случайные нажатия не регистрировались как HOLD.

Полезные кастомные Behaviors

Для создания клавиш с перечисленными ниже Поведениями надо создать новое кастомное Поведение с соответствующим типом.

`&td`

Tap Dance назначает разное Поведение в зависимости от того, сколько раз подряд клавиша была нажата.

Если назначить Tap Dance со скриншота на клавишу, то при однократном нажатии напечатается буква Q, а при двукратном нажмётся Esc.
С помощью комбинации этого поведения и &mt возможно сделать клавишу, аналогичную Tap Dance из Vial.

`&mod-morph`

Mod Morph позволяет добавить свою кастомную обработку нажатия клавиши, если она нажата с активными модификаторами Shift, Ctrl, Alt или Gui.

Если назначить Mod Morph со скриншота на клавишу, то при нажатии без модификаторов нажмётся Q, а при зажатом модификаторе Alt — Esc. Вместо Esc может быть любое Поведение, например изменение слоя, или макрос!
Это поведение является более гибким аналогом Key Overrides из Vial.

Комбо

Комбо позволяет назначить Поведение на одновременное нажатие нескольких клавиш. Например, можно назначить на одновременное нажатие клавиш C и V переключение раскладки клавиатуры, или какой-нибудь макрос, часто это удобнее назначения клавиши в слое.

Для создания Комбо перейдем на вкладку Combos и нажмём Add New Combo.

Рассмотрим пример с Комбо клавиш C и V для изменения языка раскладки. В открывшемся окне нам надо выбрать позиции клавиш, нажатие на которые приведет к активации комбо, для этого просто кликаем на позиции, которых находятся клавиши C и V.

Заполняем название комбо (на скриншоте “lang”), и выбираем Поведение при активации комбо, для изменения языка раскладки подойдет &kp, нажимающий Space с зажатым модификатором GUI.

Нажимаем на кнопку Create и комбо готово к использованию!

Нажав на кнопку с гаечным ключом мы можем внести дополнительные настройки для Комбо, например изменить таймаут срабатывания, или указать на каких конкретно слоях Комбо будет работать (по умолчанию комбо работают на всех слоях). Подробнее о этих настройках можно почитать в документации ZMK.

Макросы

С помощью Макросов можно сохранить какую-то часто используемую последовательность сочетаний клавиш и вызывать эту последовательность нажатием всего одной клавиши, например сделать Макрос, печатающий различные шаблоны, вроде такого:

```
```

в конце макрос может еще и переместить курсор в середину этого шаблона, экономит очень много нажатий!

Создание такого Макроса и разберем для примера.
Переходим на вкладку Macros, и нажимаем Add New Macro. В открывшемся окне вводим название Макроса, для примера введём “template” и нажмём Create.

Далее нам надо составить действия, которые выполнит Макрос. Чтобы макрос трижды напечатал символ `, трижды используем Поведение &kp. При создании макроса ячейка под одно Поведение сразу добавляется, добавим еще 2, дважды нажав кнопку Add Key Binding, и во всех трёх ячейках назначим &kp `.

Далее нам надо дважды сделать перенос на новую строку, снова трижды написать символ ` и последним шагом нажать клавишу ↑, чтобы перенести курсор в центр шаблона.

Итого получается 9 нажатий, целых 9 нажатий сокращается до всего 1!
По умолчанию ZMK будет нажимать каждую клавишу 30 мс, и между каждым нажатием будет происходить пауза 15 мс, чтобы ОС успевала обрабатывать каждое нажатие. Чтобы действия точно сработали (во всяких тормозных корпоративных мессенджерах, удалённых рабочих столах и джирах), а также чтобы совершаемые Макросом действия были немного читаемее, разделим их на группы добавив дополнительную паузу в 10 мс, для этого нажмём Add Control Binding и перенесём появившийся &macro_press после первых трёх нажатий `. Теперь надо не забыть поменять &macro_press на &macro_wait_time, для этого кликнем на него и выберем &macro_wait_time, в параметре Raw Value укажем 10, это количество миллисекунд, которое подождет макрос.

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

Выглядит уже читаемее, добавим такие же &macro_wait_time после двух нажатий Enter и после второй группы нажатий `.

Красота, теперь наглядно понятно, что Макрос делает.
Нам осталось только назначить Макрос на клавишу или Комбо, и можно использовать!

Макрос является Поведением, и выбирать его надо именно в поле Behavior.

Цикл выполнения макроса

Макросы в ZMK выполняются в 2 шага:

Действия при нажатии макроса,
Действия при отпускании макроса.

Изначально это не заметно, ведь без определённого Control Binding все действия выполняются сразу при нажатии. Чтобы научиться разграничивать эти 2 шага нам пригодятся следующие Control Bindings:

&macro_press — для последующих нажатий устанавливает режим, при котором указанная клавиша будет нажата, но не будет отпущена;
&macro_release — для последующих нажатий устанавливает режим, при котором указанная клавиша будет отпущена;
&macro_tap — для последующих нажатий устанавливает режим, при котором указанная клавиша будет нажата, и по прошествии времени, указанном в tap_time, будет отпущена (режим по умолчанию);
&macro_tap_time — задаёт время между нажатием и отпусканием каждой клавиши в макросе (по умолчанию 30 мс);
&macro_pause_for_release — на этом месте Макрос остановит своё выполнение до момента, когда клавиша Макроса будет отпущена.

Применив перечисленные Control Bindings можно составить макрос, который при нажатии переключает слой, нажимает определенный модификатор, затем ожидает отпускания макроса, и после этого уже возвращает слой обратно и отпускает модификатор. Получается клавиша, объединяющая &mo и &kp, два в одном!

Параметризованные макросы

У Макросов в ZMK есть интересная особенность, их можно сделать параметризованными. Для использования параметров надо применить один или несколько из перечисленных Control Bindings:

&macro_param_1to1 — следующему Поведению в макросе, в качестве параметра 1 будет передано значение из параметра 1 Макроса;
&macro_param_1to2 — следующему Поведению в макросе, в качестве параметра 2 будет передано значение из параметра 1 Макроса;
&macro_param_2to1 — следующему Поведению в макросе, в качестве параметра 1 будет передано значение из параметра 2 Макроса;
&macro_param_2to2 — следующему Поведению в макросе, в качестве параметра 2 будет передано значение из параметра 2 Макроса.

Рассмотрим на примере, реализовав Макрос, который при нажатии активирует переданный в параметре слой, нажимает переданный в параметре модификатор, ждёт отпускания клавиши, а затем выключает переданный слой и отпускает переданный в параметре модификатор.
Назовём Макрос &ml (mod-layer), он будет выглядеть вот так:

Выбраны &macro_param_1to1 и &macro_param_2to1 так как используемые Поведения &mo и &kp имеют по одному входному параметру.

Стоит обратить внимание на то, как Макрос назначается в раскладке. В списке Behavior находим созданный Макрос &ml, выбрав его нам необходимо заполнить параметры:

Layer — это слой, который передастся в качестве параметра для &mo, выберем 2;
Key Code — это клавиша, передаваемая в &kp, она будет нажата одновременно с &mo, мы планировали использовать модификатор, так что выберем LShift.

Всё, макрос готов к использованию! Прелесть такого макроса в том, что его можно использовать в нескольких местах раскладки, указывая любой слой, на который надо переключиться, и любой модификатор.

При создании кастомного Hold or Tap behavior, в bindings — HOLD и TAP можно указать любые Поведения, даже параметризованные макросы — это очень гибко, ведь при удержании клавиши выполнятся любые действия, какие только в голову придут, например в документации ZMK есть вот такая идея: параметризованный макрос, в котором при активации слоя одновременно меняется и цвет RGB-подсветки на заданный в параметре, то есть, вероятно, после переезда K:03 и Imperial на рельсы ZMK будет доступен выбор цвета светодиода для разных слоев! А ведь можно скомбинировать это не только со слоями, а с чем угодно, даже с модификаторами!