keymapper

RDP 세션(XFCE + xrdp)에서 동작하는 X11 키 리매핑 스크립트. xmodmap + xcape 를 Python-xlib 단일 스크립트로 대체한다.

---

동작

입력	출력
캡스락 단독 탭	Shift+Space (fcitx 한영전환)
캡스락 홀드 + 다른 키	Hyper 조합 (mod3)
우Shift 더블탭	CapsLock 토글

---

구조

RDP 키 입력
    ↓
X11 서버
    ↓
Python-xlib record (이벤트 감지)
    ├── 캡스락 탭   → xtest.fake_input(Shift+Space)
    ├── 캡스락 홀드 → xmodmap Hyper_L(mod3) 그대로 전달
    └── 우Shift 더블탭 → xtest.fake_input(Caps_Lock 가상 키코드)

---

설치

1. 의존성 설치

sudo apt install python3-xlib

2. 스크립트 배치

mkdir -p ~/.local/bin
cp keymapper.py ~/.local/bin/keymapper.py
chmod +x ~/.local/bin/keymapper.py

~/.local/bin이 PATH에 없다면 ~/.bashrc 또는 ~/.profile에 추가한다.

export PATH="$HOME/.local/bin:$PATH"

3. 동작 확인 (수동 실행)

python3 ~/.local/bin/keymapper.py

터미널에 [keymapper] 실행 중. 이 뜨면 정상. 캡스락 탭 → 한영전환, 우Shift 더블탭 → CapsLock 토글 확인.

4. autostart 등록 (RDP 접속 시 자동 실행)

mkdir -p ~/.config/autostart

cat > ~/.config/autostart/keymapper.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=KeyMapper
Exec=bash -c "sleep 2 && pkill -f keymapper.py; sleep 0.5 && python3 /home/$USER/.local/bin/keymapper.py"
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
EOF

sleep 2 : XFCE 세션이 키보드 설정을 초기화하는 타이밍을 피하기 위함. pkill -f keymapper.py : 재접속 시 이전 프로세스 중복 방지.

---

설정 변경

keymapper.py 상단 설정 블록을 수정한다.

CAPSLOCK_KEYCODE   = 66    # 캡스락 키코드 (xev로 확인)
RSHIFT_KEYCODE     = 62    # 우Shift 키코드 (xev로 확인)
VIRTUAL_CAPS_CODE  = 135   # CapsLock 토글용 가상 키코드 (빈 키코드)
TAP_TIMEOUT        = 0.20  # 탭 인식 최대 시간(초), 너무 민감하면 늘리기
DOUBLE_TAP_TIMEOUT = 0.30  # 더블탭 인식 최대 간격(초), 두 번째 탭까지의 여유 시간

키코드 확인 방법

xev | grep keycode

뜨는 창에서 키를 눌러 keycode 값 확인.

TAP_TIMEOUT 조정

• 탭인데 홀드로 인식 → 값 늘리기 (0.25, 0.30)
• 홀드인데 탭으로 인식 → 값 줄이기 (0.15)

DOUBLE_TAP_TIMEOUT 조정

• 더블탭인데 반응 없음 → 값 늘리기 (0.40, 0.50)
• 일반 Shift 사용 중 의도치 않게 토글됨 → 값 줄이기 (0.20)

---

문제 해결

스크립트가 동작하지 않을 때

# 실행 중인지 확인
pgrep -a python3 | grep keymapper

# xmodmap 적용 확인 (mod3에 Hyper_L이 있어야 함)
xmodmap -pm

# 직접 재실행
pkill -f keymapper.py
python3 ~/.local/bin/keymapper.py

한영전환이 안 될 때

fcitx 단축키 확인:

# fcitx5
cat ~/.config/fcitx5/config | grep -i trigger

Shift+Space 가 트리거로 등록되어 있어야 한다.

RDP 재접속 시 자동 실행이 안 될 때

# autostart 파일 확인
cat ~/.config/autostart/keymapper.desktop

# 수동 실행으로 정상 동작 확인 후
python3 ~/.local/bin/keymapper.py

---

왜 xmodmap + xcape 대신 Python-xlib를 쓰나?

	xmodmap + xcape	Python-xlib
더블탭 지원	❌	✅
복잡한 조건 분기	❌	✅
프로세스 수	3개 (xmodmap, xcape, 별도 스크립트)	1개
중복 실행 문제	발생 가능	pkill 하나로 해결
RDP 동작	✅	✅

---

파일 구성

~/.local/bin/
└── keymapper.py                        # 메인 스크립트

~/.config/autostart/
└── keymapper.desktop                   # XFCE autostart 등록