How to Set Up Kanata on NixOS: A Step-by-Step Guide

Published at

12/18/2024

Prerequisites

NixOS Installed: Make sure you have NixOS up and running on your system.
Kanata Knowledge: Familiarity with Kanata and its use cases will be helpful. If you’re new to Kanata, check out my previous blog on setting it up on Linux.

Configuration

Add the following configuration to your NixOS configuration file:

{
  config,
  lib,
  pkgs,
  ...
}:

{
  # Enable the uinput module
  boot.kernelModules = [ "uinput" ];

  # Enable uinput
  hardware.uinput.enable = true;

  # Set up udev rules for uinput
  services.udev.extraRules = ''
    KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"
  '';

  # Ensure the uinput group exists
  users.groups.uinput = { };

  # Add the Kanata service user to necessary groups
  systemd.services.kanata-internalKeyboard.serviceConfig = {
    SupplementaryGroups = [
      "input"
      "uinput"
    ];
  };

  services.kanata = {
    enable = true;
    keyboards = {
      internalKeyboard = {
        devices = [
          # Replace the paths below with the appropriate device paths for your setup.
          # Use `ls /dev/input/by-path/` to find your keyboard devices.
          "/dev/input/by-path/platform-i8042-serio-0-event-kbd"
          "/dev/input/by-path/pci-0000:00:14.0-usb-0:3:1.0-event-kbd"
        ];
        extraDefCfg = "process-unmapped-keys yes";
        config = ''
          (defsrc
           caps tab d h j k l
          )
          (defvar
           tap-time 200
           hold-time 200
          )
          (defalias
           caps (tap-hold 200 200 esc lctl)
           tab (tap-hold $tap-time $hold-time tab (layer-toggle arrow))
           del del  ;; Alias for the true delete key action
          )
          (deflayer base
           @caps @tab d h j k l
          )
          (deflayer arrow
           _ _ @del left down up right
          )
        '';
      };
    };
  };
}

Explanation

uinput Module: Ensures the kernel module is loaded for user input devices.
Udev Rules: Configures permissions for the uinput device.
Kanata Service: Defines Kanata keyboard mappings and layers with specific devices.

Testing the Configuration

Rebuild your system configuration:

   sudo nixos-rebuild switch

Identify your keyboard devices:

   ls /dev/input/by-path/

Replace the devices paths in the configuration with the relevant paths for your setup.

Verify that the uinput group exists:

   getent group uinput

Ensure Kanata is running and working as expected with your keyboard mappings.

Conclusion

That's it! You now have Kanata set up and running on NixOS. If you encounter any issues or have suggestions for improvement, feel free to leave a comment or reach out.