jtroo/kanata v1.10.0-prerelease-2

on GitHub

• fixed: a tap-hold that has been released but is pending is now able to tap
• fixed: output chord before or after an action using the same key now activates the key
• fixed: vkey press-release events on sequence completion are prioritized in the event queue
• fixed: more graceful handling of fast socket disconnection
• fixed: deflocalkeys no longer tries to parse other variants
• fixed: vkey actions no longer interfere with tap-hold tap repress
• fixed: XX action now works with switch action's input logic
• fixed(Windows): avoid double action activation on first wake after long idle time
• fixed(macOS): devices with empty names no longer cause a crash
• fixed(macOS): emit correct code for compose key
• added: reset-timeout-on-press as an option to tap-hold-release-timeout
• added: U+<hex_code> syntax for unicode action
• added: on-physical-idle action
• added: TCP commands for live reload of configuration
• added: --list flag to list devices for all platforms
• added: --cfg-stdin flag to read config from stdin instead of a file
• added: tap-hold-release-tap-keys-release which has a similar behaviour to QMK "chordal hold"
• added(Windows): non-Interception support for mouse buttons and scroll
• added(macOS): key mappings for EjectKey, IntlRo

NOTE: All Windows binaries are compiled 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_legacy_output.exe variant has the same input defsrc handling as the standard kanata.exe file. It uses the same output mechanism as the standard kanata.exe variant in version 1.6.1 and earlier. In other words the formerly experimental_scancode variant is now the default binary. The non-legacy variants contain changes for an issue; the fix is omitted from this legacy variant. The legacy variant is included in case issues are found with the new output mechanism.

NOTE: All Linux 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.

WARNING: feature support on macOS is limited.

Instructions for macOS 11 and newer

You must use the Karabiner driver version v6.2.0.

Please read through this issue comment:

#1264 (comment)

Also have a read through this discussion:

#1537

Old instructions for macOS 11 and newer

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

sudo '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon'

Install Karabiner driver for macOS 10 and older:

• Install the Karabiner kernel extension.

After installing the appropriate driver for your OS (both macOS <=10 and >=11)

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>`

Add permissions

If Kanata is not behaving correctly, you may need to add permissions. Please see this issue: link to macOS permissions issue.

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.

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 release 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.

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

The Windows kanata_passthru.dll file allows using Kanata as a library within AutoHotkey to avoid conflicts between keyboard hooks installed by both. You can channel keyboard input events received by AutoHotkey into Kanata's keyboard engine and get the transformed keyboard output events (per your Kanata config) that AutoHotkey can then send to the OS.

To make use of this, download kanata_passthru.dll, then the simulated_passthru_ahk folder with a brief example, place the dll there, open kanata_passthru.ahk to read what the example does and then double-click to launch it.

1cc0349bf59e7c07c324baff0a45c9c3ad921f5fe26a5054da7198c4a3fb29d6  kanata
b322ab3457d5b8fb59bb84217c1c9b0870f7f3a79322829b2121aee7ffc7b78e  kanata.exe
87fbe84cc768a0becc3f3a304bdd205b427732ecd58724a59cc626f97f08906e  kanata.kbd
24953555f12bf6a1ad3b98c85fe8d2a97e7c46e2b0c2276cfc5b5357bb40bf12  kanata_cmd_allowed
40ed8bc69e8d7d13d97826b886edfb98263e5750569c9e05936d6b99937cae8c  kanata_cmd_allowed.exe
1ca6235b4a91edb9c81427ba887b4ab71102ca5074349c440cbc7c5964a7e55a  kanata_gui.exe
fdcca94647e7eba8706605a62ee6727380a1b5df2779bda05da8bbe68108552d  kanata_gui_cmd_allowed.exe
9ec1e0abeab7049f44c5f512f51749c5195bad1501824c6f4b3375a3159c448f  kanata_gui_wintercept.exe
0fb42e8481a25cf9669b306ea6ffe91d5058deb68b75e7463493b88d645ecf34  kanata_gui_wintercept_cmd_allowed.exe
5ac2183a949eb0b539dcdf800d0e9c30b0b49b16dede14bfbdad5ec20fd9d7f0  kanata_legacy_output.exe
1e5133c8d0fb4314919dd2dc925874e23f1cf5ec14873d80e609eca2180f3a43  kanata_macos_arm64
502bcb5222ef8ba24b43050fb952927fe0d0486cc47ab36981d9d5b32eb22c4e  kanata_macos_cmd_allowed_arm64
5be68de6729f36afaf944dbb8bff178b896a2eceb7e81372c5e5713a9a82986f  kanata_macos_cmd_allowed_x86_64
9fa20ab5a12bdcd35d5a25a996001bea5d043a6a2dd0be687b9ac6864c1c7ba2  kanata_macos_x86_64
795f31a70137171d217d16f42a41b86a65ce26c5b6509a155289032eed92aa09  kanata_passthru.dll
b25cab4ea586fce9e6906f9109a8b8aa8a4f5eecf328e3c28d56fe9d64eca174  kanata_winIOv2.exe
49ec4b221087784f86d18fc4bf3f079f654e8b9e96936dcbd72494e7a0d0cd1a  kanata_wintercept.exe
795cb45b608625d579ae75fdbd29f1dc103aec7117af6b4923bb2d60306db966  kanata_wintercept_cmd_allowed.exe