v1.6.0-prerelease-1
版本发布时间: 2024-02-11 16:50:30
jtroo/kanata最新发布版本:v1.7.0(2024-10-27 15:42:03)
Configuration guide
Link to the appropriate configuration guide version: guide link.
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.
Change log
- 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 (Windows Interception):
windows-interception-keyboard-hwids
to specify specific keyboards to intercept - Added (macOS): kext support for macOS version 10
- Fixed (Linux): exit on
SIGTSTP
to prevent locking out users from using the keyboard
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
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_scancode_experimental.exe
file contains a change for this issue where kanata does not operate correctly in 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. Testing would be helpful!
Linux
Instructions
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:
- Install the Karabiner VirtualHiDDevice Driver.
To activate it:
/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate
For macOS 10 and older:
- Install the Karabiner kernel extension.
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: https://github.com/oblitum/Interception/issues/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
8d67e60b7a56dd1c2b67db1b7c100b01cdf3b0fd176be279809687d546ceeaac kanata
e608f1930df2b6c7824b15bdb34fb0a9c14ebff964d179ca3fa5393b2a41f5b6 kanata.exe
6db41e5c10a7bda8956ea91662ce954612a0e980db88f51d778c476ef54d355c kanata.kbd
0b04ee496b179a3799d348976c301a8d5682695ad5f5baeb235c2803285a6de7 kanata_cmd_allowed
ffdbaf8634378494b5a2a51de4477578fee2bdfd7c66713a622916089ed21718 kanata_cmd_allowed.exe
3f13241b5a5e13f7888085c8a1c1adccb1ef8c0009b3c4f794ceeedb53e93bf1 kanata_macos
8131d583e48dd2af0328a2e65a018c56848a289e40f078d97bbdcf10b2689de5 kanata_macos_cmd_allowed
a77ba4cc9d48b0fe0b670a01ad82d089cad7a97509001c25fb4d3cda858b1be7 kanata_scancode_experimental.exe
85a03298b21c588192d95458be1f2e098405618425788510f94f53caceb5032c kanata_wintercept.exe
b188c600ff238559354d1245fc0eb682a9337b5a43eb3cc877013bb8c3b9ccb5 kanata_wintercept_cmd_allowed.exe
1、 kanata 1.44MB
2、 kanata.exe 969KB
3、 kanata.kbd 43.68KB
4、 kanata_cmd_allowed 1.46MB
5、 kanata_cmd_allowed.exe 1.02MB
6、 kanata_macos 2.59MB
7、 kanata_macos_cmd_allowed 2.64MB
8、 kanata_scancode_experimental.exe 969KB
9、 kanata_wintercept.exe 989.5KB
10、 kanata_wintercept_cmd_allowed.exe 1.04MB
11、 sha256sums 858B