Narzędzie xev – testowanie klawiszy i zdarzeń w systemie Linux

W systemie Linux narzędzie xev to kluczowe wsparcie do diagnostyki zdarzeń klawiatury i myszy – monitoruje komunikaty X11 i ujawnia keycode, scancode oraz keysym generowane przez naciśnięcia klawiszy lub ruchy kursora. Dzięki temu precyzyjnie zdiagnozujesz problemy z mapowaniem klawiszy w środowiskach opartych na serwerze Xorg.

Czym jest xev i jak działa?

xev (skrót od „X Event Viewer”) to lekki program z pakietu xorg-x11-utils, który nasłuchuje zdarzeń w systemie X11 i wyświetla szczegółowe informacje o każdej interakcji użytkownika. Po uruchomieniu w trybie graficznym otwiera małe okno „Event Tester” z obszarem testowym; należy ustawić na nim fokus i wykonywać testy – naciskać klawisze lub poruszać myszą. Narzędzie rejestruje zdarzenia takie jak KeyPress, KeyRelease, ButtonPress czy MotionNotify, podając m.in.:

• keycode – numer kodowy klawisza w serwerze X (np. 38 dla litery „a”);
• keysym – symboliczny odpowiednik (np. 0x61 dla „a”);
• stan modyfikatorów – bieżący stan klawiszy takich jak Shift, Alt, Control.

Przykładowe wyjście po naciśnięciu klawisza:

KeyPress event, serial 37, synthetic NO, window 0x4a00001, root 0x1d6, subw 0x0, time 12345678, (-100,-100), root:(101,101), state 0x0, keycode 38 (keysym 0x61, a), same_screen YES, XLookupString gives 1 bytes: (97) "a"

Tutaj keycode 38 odpowiada klawiszowi „a”, z keysym 0x61.

Aby usprawnić odczyt i wyświetlać tylko najważniejsze informacje, możesz użyć filtrów w terminalu:

xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'

Alternatywnie skorzystaj z poniższego polecenia:

xev | awk -F'[ )]+' '/^KeyPress/ { a[NR+2] } NR in a { printf "%-3s %s\n", $5, $8 }'

Te polecenia wyświetlają tylko keycode i keysym, co znacząco ułatwia analizę.

Zastosowania praktyczne xev

Debugowanie w sesjach zdalnych (np. NoMachine)

W środowiskach takich jak NoMachine xev pomaga diagnozować problemy z mapowaniem klawiszy. Postępuj według poniższych kroków:

1. Połącz się z pulpitem zdalnym.
2. Odtwórz problem (np. niewłaściwe mapowanie konkretnego klawisza).
3. Uruchom xev > xev.out w terminalu.
4. Ustaw fokus na oknie xev i powtórz problematyczną akcję.
5. Zamknij okno i przeanalizuj plik xev.out.

To podejście jest niezbędne, gdy problem występuje wyłącznie w sesji zdalnej.

Testowanie klawiatur multimedialnych i niestandardowych

Dla klawiatur takich jak Logitech Media Keyboard Elite xev ujawnia kody klawiszy multimedialnych oraz potencjalnie problematycznych klawiszy. Na podstawie danych z xev można przygotować konfigurację w /etc/X11/xorg.conf.d/:

Section "InputClass"
Identifier "Logitech Media Keyboard Elite"
MatchIsKeyboard "on"
MatchDevicePath "/dev/input/event*"
Driver "evdev"
Option "XkbModel" "logimel"
Option "XkbLayout" "pl"
Option "XkbOptions" "lv3:ralt_switch,compose:rctrl,terminate:ctrl_alt_bksp"
EndSection

W tym scenariuszu keycode z xev pomaga dobrać właściwy model i opcje.

W przypadku klawiatur z kropką na bloku numerycznym rezultat może wyglądać następująco:

state 0x10, keycode 91 (keysym 0xffae, KP_Decimal), same_screen YES,
XKeysymToKeycode returns keycode: 129
XLookupString gives 1 bytes: (2e) "."

Powyższe pokazuje mapowanie na keycode 91 oraz dodatkowy wynik 129.

Ograniczenia i pułapki xev

xev nie jest idealne – ma znane ograniczenia, które mogą frustrować użytkowników, zwłaszcza przy remapowaniu klawiszy:

Wada	Opis	Rozwiązanie
Offset kodów	Podaje keycode przesunięte o +8 (np. ESC jako 9 zamiast 1; „a” jako 38 zamiast 30). Xserver obsługuje zakres 8–255 (efektywnie 9–255).	Odejmij 8 od raportowanego keycode.
Brak reakcji	Czasem nie rejestruje keycode dla remapowanych lub multimedialnych klawiszy.	Użyj evtest na poziomie jądra (/dev/input/event*).
Limit X11	Należy unikać przypisań do keycode > 0xF7 (patrz /usr/share/X11/xkb/keycodes/evdev).	Sprawdź limity w pliku i mapuj poniżej progu.

Porównanie z innymi narzędziami:

showkey – pokazuje surowe scancode na poziomie konsoli (ESC=1), ale nie działa w X11.

evtest – narzędzie na poziomie jądra; skanuje /dev/input/event*, pokazuje scancode (np. value c022e) i nazwy takie jak KEY_ESC. Świetne do weryfikacji, czy urządzenie faktycznie wysyła zdarzenia.

Przykładowy przebieg pracy z evtest:

# evtest
Select the device event number [0-6]: 0

Wybierz odpowiednie urządzenie (np. Logitech USB Keyboard), a następnie testuj klawisze. W przypadkach remapowania evtest bywa pewniejszy niż xev, bo pokazuje surowe zdarzenia z jądra.

Instalacja i podstawowe kroki użycia

1. Instalacja (Debian/Ubuntu): sudo apt install x11-utils (zawiera xev). Dla Arch Linux: sudo pacman -S xorg-xev; dla Fedory: sudo dnf install xorg-x11-utils.

2. Uruchomienie podstawowe – wpisz xev i testuj w otwartym oknie „Event Tester”.

3. Zapis do pliku – użyj xev > test.log, aby przeanalizować dane później.

4. Fokus i higiena testów – maksymalizuj okno xev i unikaj przełączania aplikacji w trakcie testu.

Dla pełnej diagnostyki połącz z xmodmap -pke (aktualne mapowania) lub xkbprint (eksport układu XKB).

Remapowanie klawiszy na podstawie xev

1. Zidentyfikuj keycode w xev (w razie potrzeby odejmij 8).
2. Użyj xmodmap tymczasowo: xmodmap -e "keycode 10 = F1".
3. Aby wprowadzić zmiany trwale: edytuj plik ~/.Xmodmap lub pliki w /etc/X11/xorg.conf.d/.
4. Dla nowocześniejszego podejścia z udev: ustal scancode w evtest, dodaj regułę KEYBOARD_KEY_scancode=keycode do bazy hwdb, a następnie wykonaj sudo udevadm hwdb --update && sudo udevadm trigger.

W przypadku klawiszy multimedialnych: po identyfikacji w evtest i xev zdefiniuj mapowanie w hwdb i przeładuj reguły.

Zaawansowane wskazówki i alternatywy

Poniżej znajdziesz praktyczne wskazówki, które pomogą w nietypowych scenariuszach i środowiskach:

• integracja z Wayland – xev działa tylko w X11; pod Wayland użyj evtest lub libinput debug-events;
• urządzenia podczerwieni i niestandardowe – rozpocznij od evtest na /dev/input/eventX, a następnie weryfikuj w X11 przez xev;
• debug klawiszy multimedialnych – evtest pokazuje nazwy takie jak KEY_MEDIA_PLAY; mapuj do wolnych keycode < 247;
• wiele urządzeń wejścia – evtest listuje wszystkie węzły (/dev/input/event0–13); wybierz właściwe urządzenie i dopiero potem testuj w xev.