Skip to content

v1.6.0-prerelease-3

Pre-release
Pre-release
Compare
Choose a tag to compare
@jtroo jtroo released this 29 Mar 16:43
· 176 commits to main since this release
v1.6.0-prerelease-3
a2dd46e

Configuration guide

Link to the appropriate configuration guide version: guide link.

Notable changes since prerelease-2

BREAKING CHANGE: deflayer-custom-map is renamed to deflayermap

Fix: kanata_winIOv2.exe now handles arrow keys and other "extended scancode" keys correctly at the input side.

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 CHANGE: Add web event.code names as usable configuration key names, making them no longer usable in deflocalkeys.

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 (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 (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 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 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 and want kanata to handle the key positions consistently

Known issues:

  • deflocalkeys-win does not work properly for this variant. It needs a different variant (or use the values you would use for deflocalkeys-wintercept.

NOTE: The kanata_scancode_experimental.exe variant has the same 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 binaries are 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

WARNING: the provided binaries are only for x86 devices. If you are using ARM macs, e.g. M1/M2, you must compile kanata yourself

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

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.

chmod +x kanata_macos   # may be downloaded without executable permissions
sudo ./kanata_macos --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 
a26bb1bc8f30c407c16e96dd8010549f11e7fd340f5949ab4ca9f23841c61e3f  kanata
bd862b85a66fbd59c7de3183e16393fed1bd0a76c1cf76621259286248108cda  kanata.exe
989e64c5ba85f2930ba3e4b4bcac54c93412466529b7cc7de5c6bd3f299414f7  kanata.kbd
b78229867c90a05a0c214b018ed65044087b4ea4b702c33700e0afe2c0ee3f2d  kanata_cmd_allowed
aff4b2f1ea4169a2ee1294f99129fe7a09c911e853c88a41acca13c43c68ebe2  kanata_cmd_allowed.exe
3f03620db1480af4aee3035a8daf1f152bf88ada43d2ff3f5b8cd2caf5005b55  kanata_macos_cmd_allowed_x86
2002e97124f10542d3907a37d82ab94acc760c1080e931555e9410c3c8e06fbe  kanata_macos_x86
c053e0c278f90dc0bcf925cf69c9c1c8023ed6d4c6332b6ba8722ad3536132c2  kanata_scancode_experimental.exe
59041479ba1a2e5440ae9dd9904d31bf0097f30f7c4bc190167ea9b8d628dc58  kanata_winIOv2.exe
a2941cf08f6cb885bd96343eb16ec0f62c6c63e2093a62221ef66e660e7b97b8  kanata_wintercept.exe
ef4b3071a54ecab324b5890569adc01a6c4f03aff5f7cb88ad6dd5a8b0a9b9fb  kanata_wintercept_cmd_allowed.exe
Assets 14
Loading