Skip to content

platform-known-issues.adoc

Latest commit

 

History

History
95 lines (82 loc) · 4.11 KB

platform-known-issues.adoc

File metadata and controls

95 lines (82 loc) · 4.11 KB

Hardware known issues

At the electric circuit layer of many keyboards, cost-saving measures can lead to key presses not registering when pressing multiple keys simultaneously. Usually this happens with at least 3 key presses. Kanata cannot fix this issue. You can work around it by avoiding the problem key combination, or using a different keyboard.

Platform-dependent known issues

Preface

This document contains a list of known issues which are unique to a given platform. The platform supported by the core maintainer (jtroo) are Windows 11 and Linux. Windows 10 is expected to work fine, but as Windows 10 end-of-support is approaching in 2025, jtroo no longer has any devices with it installed.

On Windows, there are two backing mechanisms that can be used for keyboard input/output and they have different issues. These will be differentiated by the words "LLHOOK" and "Interception", which map to the binaries kanata.exe and kanata_wintercept.exe respectively.

Windows 11 LLHOOK

  • Some input key combinations (e.g. Win+L) cannot be intercepted before running their default action

  • OS-level key remapping behaves differently vs. Linux or Interception

    • Does not affect winiov2 variant

    • #152

  • Certain applications that also use the LLHOOK mechanism may not behave correctly

  • AltGr / ralt / Right Alt can misbehave

  • NumLock state can mess with arrow keys in unexpected ways

  • Without process-unmapped-keys yes, using arrow keys without also having the shift keys in defsrc will break shift highlighting

    • Does not affect winiov2 variant

    • #858

    • Workaround: add shift keys to defsrc or use process-unmapped-keys yes in defcfg

Windows 11 Interception

  • Sleeping your system or unplugging/replugging devices enough times causes inputs to stop working

  • Some less-frequently used keys are not supported or handled correctly

Linux

  • Key repeats can occur when they normally wouldn’t in some cases

  • Unicode support has varying success due to many applications not supporting the ibus input mechanism. Using xkb to map keys to unicode or using clipboard actions are more consistent solutions

  • Key actions can behave incorrectly due to the rapidity of key events

  • Macro keys on certain gaming keyboards might stop being processed

    • Context: search for POTENTIAL PROBLEM - G-keys in the code.

    • Workaround: leave process-unmapped-keys disabled and explicitly map keys in defsrc instead

MacOS

  • Mouse input processing requires Accessibility or Input Monitoring permission in System Settings > Privacy & Security

  • Once the mouse event tap is installed (on startup or via live-reload), it continues running for the lifetime of the process. Removing all mouse keys from defsrc then live-reloading does not stop the tap thread, though it becomes a no-op pass-through.