Skip to content

v1.6.0
Compare
Choose a tag to compare
@jtroo jtroo released this 24 Apr 07:34
· 64 commits to main since this release
v1.6.0
84e357b

Configuration guide

Link to the appropriate configuration guide version: guide link.

Known issues

  • Some major issues with defchordsv2-experimental usability
    • Fixed in main and in v1.6.1-prerelease-1
  • Key repeat stopped working for transparent/unmapped-but-processed keys in Windows and Linux TTY (macOS unknown if affected)
    • Fixed in main and in v1.6.1-prerelease-1

Changelog (since v1.5.0)

BREAKING FIX: dynamic-macro now records and simulates delays by default to reproduce tap-hold effects correctly. It can be turned off via an undocumented defcfg entry.

BREAKING FIX: TCP server messages now emit newline terminators for easier message differentiation.

BREAKING FIX: Add concat keyword for defvar that enables appending strings together. This will only break you if you happened to use concat as the very first string in a list value in defvar, which seems unlikely.

BREAKING FIX: Input chord release behaviour has been improved but might affect existing workflows

BREAKING FIX: TCP server now only listens to localhost by default. This can be opted out of by specifying the server address (originally it was 0.0.0.0) as part of the -p command line argument.

BREAKING CHANGE: Transparent key behaviour now checks all active layers by default, as opposed to the old behaviour where it would only go to the base layer. This change can be opted out of by adding transparent-key-resolution to-base-layer to defcfg.

Change log
  • Added: deflayermap - an alternate way to define layers that may be more preferable to some
  • Added: concurrent-tap-hold to defcfg, allowing tap-hold actions to time out in parallel
  • Added: --check argument to verify config file without starting kanata
  • Added: lrld-num action, allowing live reloading a specific config argument position
  • Added: block-unmapped-keys to defcfg
  • Added: rapid-event-delay as a mitigation around desktop environments incorrectly handling some rapid events
  • Added: template definition and expansion for reducing boilerplate
  • Added: more switch logic (not, key-timing, input, input-history)
  • Added: lrld-file action
  • Added: improved wording + syntax of fake key operations, changing name from fake to virtual
  • Added: more TCP client requests and server events
  • Added: platform top-level configuration item to conditionally use configurations depending on the running platform
  • Added: experimental V2 of chords, which is a global configuration and is a separate system from existing actions
  • Added: maximum layers is increased from 25 to 60000
  • Added: special nopX keys that can be used for sequences, fork, and switch
  • Added (Windows): binary now has a manifest that can be manipulated to allow LLHOOK-based binaries to operate in administrator-privileged windows
  • Added (Windows winIOv2): added deflocalkeys-winiov2 variant
  • Added (Windows Interception): windows-interception-keyboard-hwids to specify specific keyboards to intercept
  • Added (Windows Interception): windows-interception-mouse-hwids to specify multiple mice to intercept
  • Added (macOS): kext support for macOS version 10
  • Fixed: input chord key association for presses/releases
  • Fixed: input chords resulting in multiple tap-holds can now activate both holds
  • Fixed: permit optional UTF8 BOM at the beginning of a configuration file
  • Fixed: allow all symbols to be overridden in deflocalkeys
  • Fixed: right-hand modifiers are released properly for visible-backspaced sequences
  • Fixed: mouse buttons and wheel actions are now forwarded correctly with process-unmapped-keys yes, without explicit definition of mouse buttons, while grabbing the mouse
  • Fixed (Linux): exit on SIGTSTP to prevent locking out users from using the keyboard
  • Fixed (Windows LLHOOK): reduced blast radius of lsft workaround (properly this time)
  • Fixed (Windows LLHOOK): handling of locking via Win+L works correctly

Sample configuration file

The attached kanata.kbd file is tested to work with the current version. The one in the main branch of the repository may have extra features that are not supported in this release.

Windows

Instructions

NOTE: All binaries are for x86-64 architectures only.

Download kanata.exe. Optionally, download kanata.kbd. With the two files in the same directory, you can double-click the exe to start kanata. Kanata does not start a background process, so the window needs to stay open after startup. See this discussion for tips to run kanata in the background.

You need to run kanata.exe via cmd or powershell to use a different configuration file:

kanata.exe --cfg <cfg_file>

NOTE: The kanata_winIOv2.exe variant contains an experimental breaking change that fixes an issue where the Windows LLHOOK+SendInput version of kanata does not handle defsrc consistently compared to other versions and other operating systems. This variant will be of interest to you for any of the following reasons:

  • you are a new user
  • you are a cross-platform user
  • you use multiple language layouts within Windows and want kanata to handle the key positions consistently

This variant contains the same output change as in the scancode variant below, and also changes the input to also operate on scancodes.

NOTE: The kanata_scancode_experimental.exe variant has the same input defsrc handling as the standard kanata.exe file but contains a change for an issue where kanata outputs are not handled correctly by some applications. This has not yet been extensively tested but the hope is that it is a strict improvement in scenarios where kanata operates correctly.

Linux

Instructions

NOTE: All Windows binaries are compiled for x86 architectures only.

Download kanata.

Run it in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup. See this discussion for how to set up kanata with systemd.

chmod +x kanata   # may be downloaded without executable permissions
sudo ./kanata --cfg <cfg_file>`

To avoid requiring sudo, follow the instructions here.

macOS

Instructions

WARNING: feature support on macOS is limited.

For macOS 11 and newer:

To activate it:

/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

For macOS 10 and older:

After installing the appropriate driver for your OS

Download a kanata_macos variant.

Run it in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup.

Example

chmod +x kanata_macos_arm64   # may be downloaded without executable permissions
sudo ./kanata_macos_arm64 --cfg <cfg_file>`

cmd_allowed variants

Explanation

The binaries with the name cmd_allowed are conditionally compiled with the cmd action enabled.

Using the regular binaries, there is no way to get the cmd action to work. This action is restricted behind conditional compilation because I consider the action to be a security risk that should be explicitly opted into and completely forbidden by default.

wintercept variants

Explanation and instructions

Warning: known issue

This issue in the Interception driver exists: oblitum/Interception#25. This will affect you if you put your PC to sleep instead of shutting it down, or if you frequently plug/unplug USB devices.

Description

These variants use the Interception driver instead of Windows hooks. You will need to install the driver using the assets from the linked website or from the copy in this repo. The benefit of using this driver is that it is a lower-level mechanism than Windows hooks. This means kanata will work in more applications, including administrator-privileged apps.

Steps to install the driver

  • extract the .zip
  • run a shell with administrator privilege
  • run the script "command line installer/install-interception.exe"
  • reboot

Additional installation steps

The above steps are those recommended by the interception driver author. However, I have found that those steps work inconsistently and sometimes the dll stops being able to be loaded. I think it has something to do with being installed in the privileged location of system32\drivers.

To help with the dll issue, you can copy the following file in the zip archive to the directory that kanata starts from: Interception\library\x64\interception.dll.

E.g. if you start kanata from your Documents folder, put the file there:

C:\Users\my_user\Documents\
    kanata_wintercept.exe
    kanata.kbd
    interception.dll

sha256 checksums

Sums 
f61c39c709adf5fd584c9646dfcadfa91bd235aad744dbf60c5815a61132c642  kanata
d51561b5701dc18971b4cb794694796577579513195a1354e3d7dd2a46f5b2e5  kanata.exe
75619c377a5609f4d1426d9f316fde1cd6a3f48b9950269823485401f833f22e  kanata.kbd
45c05d384a85c93dee4efc915ab06028f3390509af29c1c11fc39357c9a6c38e  kanata_cmd_allowed
e2f148fe7d4dfdba0ee26aa0dba8f70cbe69e1b89e1155b4eccfc63cd1ece641  kanata_cmd_allowed.exe
b0949f2a4374b40893fd75e17a319b2b79ab2fc52fbac3ade4aaf4e73393baec  kanata_macos_arm64
f21db1463ca057890a9c4dd49800eb4534e8d12c5f459465ffc6143ff46cd94d  kanata_macos_cmd_allowed_arm64
0cdb499ab6f7ef2fe3415642ddd58b12fbf037e77c745b8408a4595b50f68be3  kanata_macos_cmd_allowed_x86_64
5814d2e39fc96d8cbbaed9d26f46848ac0bd835b58b2c586da664b05f9ab4be8  kanata_macos_x86_64
19f8bda8fd184faf1892f0ac7e348673edf0ded07f356b702cc7a75ffd6930f8  kanata_scancode_experimental.exe
feeea20798767c449c89ade654ab5bc59b45a840034a2f57b98ee10be8b2ea0b  kanata_winIOv2.exe
6757a094a5b1b1f4be0dc1fbb9740be35ee15b38e3372e10ef9ff89bca48f19c  kanata_wintercept.exe
5830eeea31733fc5c01769fbec91e4b5c54228fd87de900be0b736aefef7ed23  kanata_wintercept_cmd_allowed.exe
Assets 16