razer-trinity-mapper

Scope: this tool is built specifically for the Razer Naga Trinity and supports that mouse only. For other devices, consider input-remapper.

Fast, native remapper for the 12 side buttons of the Razer Naga Trinity on Linux.

A purpose-built alternative to generic tools like input-remapper: one window, a 3×4 grid mirroring the mouse, click a button, press a key — done. The headless engine works at the kernel level (evdev grab + uinput), so remapping is transparent to Wayland, X11 and games.

┌─────────────────────────────┐
│ Trinity Mapper      [active]│
│                             │
│  ┌────┐ ┌────┐ ┌────┐       │
│  │ 1  │ │ 2  │ │ 3  │      │  click a cell,
│  │ctrl│ │ a  │ │ f  │      │  press a key,
│  │ +1 │ │    │ │    │      │  it's mapped.
│  └────┘ └────┘ └────┘       │
│  … (full 3×4 grid)          │
│                             │
│  [profile: mmo ▾] [recalibrate]│
└─────────────────────────────┘

Features

• 3×4 button grid — click a cell, press a key (modifiers supported: Ctrl+1, Shift+A, …).
• Kernel-level remapping (evdev grab + uinput injection) — works on Wayland, X11 and in games; no proprietary driver, no reverse engineering.
• Guided calibration — press the 12 buttons once, the tool learns what the firmware actually emits (it is quirkier than you'd think).
• Multiple profiles (TOML, per profile), instant toggle.
• Headless daemon + GUI — start the engine at login, the GUI just pilots it over a local socket.
• Layout-aware key capture (via xkbcommon): AZERTY, QWERTZ, BEPO… your A is the real A.
• 6 languages: English, French, German, Spanish, Italian, Portuguese (Brazil).
• Clean dark theme with client-side decorations under Wayland (system decorations on X11).

Installation

Quick install (recommended)

curl -fsSL https://raw.githubusercontent.com/4lador/razer-trinity-mapper/main/install.sh | bash

Downloads prebuilt binaries and installs to ~/.local/bin (add --system to install to /usr/local/bin instead). Then follow the requirements steps below.

With udev rule + systemd service

curl -fsSL https://raw.githubusercontent.com/4lador/razer-trinity-mapper/main/install.sh \
  | bash -s -- --with-udev --with-service

Other install methods

cargo install (Rust users)

cargo install --git https://github.com/4lador/razer-trinity-mapper trinity-daemon trinity-gui

Installs all three binaries (trinity-daemon and trinity-ctl come from the same crate). Requires libxkbcommon development headers and pkg-config to build.

From source

git clone https://github.com/4lador/razer-trinity-mapper
cd razer-trinity-mapper
cargo build --release
install -Dm755 target/release/trinity-daemon ~/.local/bin/trinity-daemon
install -Dm755 target/release/trinity-gui ~/.local/bin/trinity-gui
install -Dm755 target/release/trinity-ctl ~/.local/bin/trinity-ctl

Arch Linux (AUR — when available)

yay -S razer-trinity-mapper

Arch users should prefer this package once available (tracked by pacman, clean upgrades and removal).

Requirements

• Linux with glibc ≥ 2.34 (Ubuntu 22.04+, Debian 12+, Fedora 38+, Arch, openSUSE) for the prebuilt binaries.
• bash, curl and tar for the install script.

After installing the binaries, set up the kernel module and permissions:

1. Load the uinput module (not loaded by default on some distros):

sudo modprobe uinput
echo uinput | sudo tee /etc/modules-load.d/uinput.conf   # at boot

2. Grant access to input devices and /dev/uinput:

sudo groupadd -r uinput 2>/dev/null || true
sudo usermod -aG input,uinput "$USER"

If you used --with-udev, the udev rule is already installed. Otherwise:

sudo cp packaging/60-trinity-mapper.rules /etc/udev/rules.d/
sudo udevadm control --reload && sudo udevadm trigger

3. Log out and back in (group changes require a new session).

4. Start the engine and GUI:

trinity-daemon &
trinity-gui &

Or enable the systemd user service (if installed with --with-service):

systemctl --user enable --now trinity-mapper.service

Troubleshooting

Mouse completely stops responding after enabling remapping

The daemon holds an exclusive grab. Kill it and the mouse returns to native mode:

pkill trinity-daemon

"No such device" or "Permission denied" when starting the daemon

The uinput module is not loaded or you lack permissions:

lsmod | grep uinput           # check module
sudo modprobe uinput           # load it
groups | grep -w input        # check group
groups | grep -w uinput       # check group

Keys are remapped to the wrong characters (AZERTY, QWERTZ…)

The GUI captures keys using your active keyboard layout (via xkbcommon). Make sure your session exports the correct XKB_DEFAULT_LAYOUT or run the recalibration from Settings → Diagnostics.

Usage

1. Start the engine: trinity-daemon (or the systemd unit above).
2. Start the GUI: trinity-gui.
3. First run: launch the guided calibration and press the side buttons 1 → 12 once.
4. Click a grid cell and press the key to assign (hold modifiers to build combos like Ctrl+1). Right-click a cell to clear it.
5. The active toggle enables/disables remapping on the fly.

Profiles live in ~/.config/razer-trinity-mapper/ (one TOML file per profile + calibration.toml).

Uninstall

Via install.sh

Installed with the one-liner (no cloned repo)?

curl -fsSL https://raw.githubusercontent.com/4lador/razer-trinity-mapper/main/install.sh \
  | bash -s -- --uninstall          # remove binaries only

From a clone:

./install.sh --uninstall          # remove binaries only
./install.sh --uninstall --all    # remove everything (udev, systemd, config)

Via pacman (AUR, when available)

sudo pacman -R razer-trinity-mapper

User config (~/.config/razer-trinity-mapper/) is never removed by pacman — delete it manually if you want a full cleanup.

Keyboard shortcuts

Switch profiles from a key combination by binding trinity-ctl in your desktop's shortcut settings:

Desktop	Where to configure
KDE Plasma	System Settings → Shortcuts → Add Command
GNOME	Settings → Keyboard → Custom Shortcuts
sway	bindsym $mod+F1 exec trinity-ctl profile mmo in config
i3	Same syntax as sway
Hyprland	bind = $mod, F1, exec, trinity-ctl profile mmo in hyprland.conf
Xfce	Settings → Keyboard → Application Shortcuts
Any X11 WM	xbindkeys

CLI

The daemon can also be driven from the CLI:

trinity-ctl status              # daemon state
trinity-ctl profiles            # list profiles
trinity-ctl profile mmo         # switch to a profile

Or directly over the Unix socket (JSON lines):

echo '{"type":"get_status"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/trinity-mapper.sock
echo '{"type":"set_enabled","enabled":false}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/trinity-mapper.sock

Architecture

Strict hexagonal architecture — a pure domain, adapters around it:

trinity-gui ──► trinity-app ◄── trinity-infra
trinity-daemon ─►    │
                    ▼
              trinity-core

Crate	Role
trinity-core	Pure domain: buttons, key combos, profiles, calibration — zero I/O
trinity-app	Ports (traits), use cases, shared IPC protocol
trinity-infra	evdev, uinput, TOML and by-id adapters
trinity-gui	Iced GUI (composition root)
trinity-daemon	Headless engine + IPC (composition root)

Development

cargo test                              # unit tests
just test-integration                   # uinput tests (input/uinput groups)
cargo clippy --all-targets -- -D warnings
cargo fmt --check
scripts/check-architecture.sh           # hexagonal dependency rule
just check                              # all of the above

Contributing

Bug reports, translations (one TOML file per language in crates/trinity-gui/locales/) and pull requests are welcome.

Credits

• Icons: Material Design Icons (Apache-2.0)
• Font: Inter (SIL OFL 1.1)
• GUI: Iced (MIT)

License

Copyright (C) 2026 4lador

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE.