Skip to content

v1.7.0

Latest
Latest
Compare
Choose a tag to compare
@jtroo jtroo released this 27 Oct 07:42
· 73 commits to main since this release
v1.7.0
74a5c1c

Configuration guide

Link to the appropriate configuration guide version: guide link.

Known issue(s)

  • Windows: keypad Enter (kprt) and potentially other keys in the extended scancode range do not output correctly with the default kanata.exe binary. Use winiov2 instead.

Changelog (since v1.6.1)

BREAKING FIX: On Linux, mouse device auto-grabbing will happen only if mouse buttons are mapped in defsrc. This is breaking if all of the following apply:

  • you rely on auto-grabbing
  • you use a mouse with keyboard actions for kanata-relevant actions
  • your mouse isn't identified as also being a keyboard
  • you do not have any mouse button defined in defsrc

BEHAVIOUR CHANGE: include no longer errors on missing files.

Change log

Added: O-(...) for any-order overlapping keys in sequences.
Added: conditional configuration using environment variables via (environment (name val) ...)
Added: allow double-quotes within strings by adding Rust-style strings r#"<content>"#. Potentially breaking, but seems doubtful that anyone has a good reason to be doing this
Added: --log-layer-changes flag to override false configuration temporarily for testing
Added: parse numbers as a delay (unit milliseconds) for cmd-output-keys
Added: unmod can accept a modifier list as the first parameter to selectively undo only some modifiers
Added: option to eagerly release override output to help with some use cases
Added: cmd-log
Added: reverse-release-order within multi
Added: base-layer for switch logic
Added: alias-to-trigger-on-load for defcfg
Added: allow-hardware-repeat for defcfg
Added: --quiet CLI argument to suppress warning and info logs
Added(Windows): capability to use Kanata as a library for AHK
Added(Windows): GUI tray app (gui variants of the executable)
Added(Windows): JIS key mappings
Added(Windows-Interception): add device exclusion (include by default) in defcfg
Added(Linux): linux-use-trackpoint-property for middle mouse scrolling on ThinkPads
Added(Linux): linux-output-device-bus-type for defcfg
Added(Linux): linux-device-detect-mode for defcfg
Added(macOS): unicode action is now implemented
Added(macOS): mouse actions are now implemented (some bugs still exist)
Fixed: chordsv2 now eagerly activates tap-hold-press|release
Fixed: chordsv2 preserves event release order
Fixed: chordsv2 configuration errors point to precise location
Fixed: chordsv2 configuration causes error on duplicate input keys where before it would silently overwrite earlier configurations
Fixed: one-shot activations from within chordsv2 are preserved
Fixed: keep other macros around when another macro completes
Fixed: swap incorrect unmod with custom mod keys for alt/meta
Fixed: block-unmapped-keys now only blocks unspecified actions, where before it would block explicitly transparent keys as well

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

The gui variants only use the winiov2 I/O mechanism.

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.

Linux

Instructions

NOTE: All Linux binaries are compiled for x86-64 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 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

kanata_passthru.dll

Explanation and instructions

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.

sha256 checksums

Sums 
03f2dc888fc7831d50f55fc1ff5dcb1fc1015616a85529cbb936c3bbc4af1326  kanata
6639b9429e54b0aa581e5db1dadd2799b6382b28b3451511b851cf28d4134aa4  kanata.exe
0f8126baafb313f2a9c3909539ef6e1f3f5ad97375a22895f1052168bd87bc4b  kanata.kbd
1c2bdfcb2a40a0228ca5d9cfcf0cfab84b17cf1aa8b39dcd22bdebdfc72a6660  kanata_cmd_allowed
89546cea5cd79b555e2665ba94b0ed46b5d271516313da935486830c0a18d571  kanata_cmd_allowed.exe
7c0e43f2cf31deb58dad246818c411944a75ec62473f5d606c29a64ed13486ec  kanata_gui.exe
d538af412c508076a33def8a014c60125eaabdb4586b83e3b0b85f7aac0a1f0c  kanata_gui_cmd_allowed.exe
ee758d57cf8119c489dda4d55884beb4287834c7c1ffd1d3e948acc73019ec79  kanata_gui_wintercept.exe
e94f2033a4cad9c058c0700d9ee58067c27e2bf993eb3379cf56e80adb557f49  kanata_gui_wintercept_cmd_allowed.exe
0d61ed5642e642679daf1fde999f600617cf8657b9bc4db408018c4d4fd254ec  kanata_legacy_output.exe
83ad80fbaf8c7b0ec0e17052a02ca0b3057cbbeaf8a023a61541f1514a936b43  kanata_macos_arm64
d91b8191280db7b82b5df0d374485b55055fcd641af01bb2945f549470dea175  kanata_macos_cmd_allowed_arm64
70630dae178b2b0be3ed0057a932df6a55978929d8844e3c7dee971faf26813b  kanata_macos_cmd_allowed_x86_64
e3f0d99e512a84c5cae1f63e71c07ecdbff66dc89b053aba0abb4f9dee0cadc0  kanata_macos_x86_64
13f68516b63dfb9426df69fa9af35a16ab517d5166d2a033363d8668392b19c3  kanata_passthru.dll
6f674287269f6ef1961e18f574e5d1aca59e8d5768f4e3c988e315197ed755a6  kanata_winIOv2.exe
bdce7ba5fa5b48b24b5f4356e46d1739d428b6a7798e279f6403a4c100e77dfc  kanata_wintercept.exe
d2c03f0649d42ebbbf3b58e904dd9be9749a0ccd2ecd7bc98a893a1fb7ffef67  kanata_wintercept_cmd_allowed.exe
Assets 21
Loading