SensorFinder for Razer Huntsman

English: A browser tool for Razer Huntsman analog (optical) keyboards (V2 Analog, Mini Analog, V3 Pro line incl. 8KHz). It shows which keys the sensors register, how deep they go, and whether each press actually crossed the actuation point. It can also set per-key actuation and release points, including keys Synapse hides, such as the Windows key. Open the page in desktop Chrome/Edge: https://ohy1.github.io/SensorFinder-for-Razer-Huntsman/ The page follows your browser language (Korean / English) and has a language button at the top right. Safety policy and recovery steps: SAFETY.md.

Razer Huntsman 아날로그(광학) 키보드에서 어느 키의 센서가 얼마나 눌린 것으로 감지되는지를 실시간으로 보여 주는 진단 도구입니다. 호환 키캡을 끼운 뒤 키보드가 미세한 입력을 잡을 때 원인 키를 찾는 용도로 만들었습니다. Synapse가 설정 대상에서 빼놓은 키(윈도우 키 등)의 입력 지점(액추에이션)을 직접 읽고 바꾸는 기능도 들어 있습니다.

화면은 브라우저 언어에 맞춰 한국어 또는 영어로 나오고, 오른쪽 위 버튼으로 바꿀 수 있습니다.

빠른 실행: 데스크톱 Chrome / Edge로 https://ohy1.github.io/SensorFinder-for-Razer-Huntsman/를 엽니다. 저장소를 내려받아 web/index.html을 열어도 됩니다.

비공식 도구입니다. Razer와 관계없고, 리버스 엔지니어링으로 공개된 프로토콜을 사용합니다. 사용에 따른 책임은 사용자에게 있습니다.

지원 모델

모델	PID	깊이 스트림	입력 지점 읽기/쓰기
Huntsman V2 Analog	0266	리포트 07, 1바이트	02:92 / 02:12
Huntsman Mini Analog	0282	리포트 07, 1바이트	02:92 / 02:12
Huntsman V3 Pro / V3 Pro 8KHz / V3 Pro TKL / TKL 8KHz / V3 Pro Mini / V3 TKL 8KHz / Signature Edition / V3 Pro Low-profile TKL 8KHz	02A6 / 02CF / 02A7 / 02D0 / 02B0 / 02E5 / 02D8 / 02E6	리포트 0B, u16 BE	02:92 / 02:12 (임계값 = u16의 상위 바이트)

1. 센서 모니터: 어느 키가 걸리는지 찾기

실행

1. Razer Synapse를 실행해 둡니다 (트레이에 있어도 됩니다). Synapse가 켜져 있으면 키보드가 "드라이버 모드"로 동작하며 키별 깊이 데이터를 PC로 보냅니다. 이 도구는 그 데이터를 함께 읽습니다.
2. 데스크톱 Chrome 또는 Edge에서 web/index.html을 엽니다. 파일을 더블클릭해도 되고, 기본 브라우저가 다르면 Chrome 창으로 끌어다 놓으면 됩니다. https://ohy1.github.io/SensorFinder-for-Razer-Huntsman/를 열어도 됩니다.
3. 키보드 연결을 누르고 목록에서 키보드를 선택합니다.
4. 입력/해제 지점 → 키보드에서 불러오기를 한 번 누릅니다. 각 키에 설정된 입력 지점과 해제 지점을 읽어 옵니다(약 3초).
   • 그 뒤로는 눌림마다 실제로 입력됐는지 / 감지만 됐는지를 판정해 줍니다.
   • 불러온 값은 브라우저에 저장되어 다음에 열 때 다시 쓰입니다. Synapse에서 설정을 바꿨다면 다시 불러오세요. RAM에 쓴 값은 재연결하면 돌아가므로 저장하지 않습니다.
   • Synapse가 켜진 상태에서 실패하면 Synapse를 잠시 종료하고 불러온 뒤 다시 켜면 됩니다.

화면 보는 법

• 키 깊이 맵: 파랑은 감지 중(입력 지점 전), 초록은 입력 중입니다.
  • 테두리 주황은 감지만 되고 한 번도 입력되지 않은 키(미세 접촉), 초록은 입력된 적이 있는 키입니다.
  • 감지된 키 안의 실선은 입력 지점, 점선은 해제 지점입니다.
• 키 깊이 그래프: 최근 감지된 키(또는 클릭한 키)의 최근 5초 깊이 변화입니다.
  • 입력 지점(실선)과 해제 지점(점선)이 함께 그려지고, 입력 중이었던 구간은 초록 배경으로 표시됩니다.
  • 마우스를 올리면 그 시점의 깊이가 보입니다.
• 감지 기록의 판정 칸
  • 입력됨 +121 ms, 162 ms 유지: 처음 감지된 뒤 121 ms 만에 입력 지점에 닿았고, 해제 지점으로 돌아올 때까지 162 ms 동안 입력 상태였다는 뜻입니다.
  • 미입력 1.20 mm 모자람: 입력 지점까지 1.2 mm가 남아 입력되지 않았다는 뜻입니다.
• 판정은 읽어 온 입력·해제 지점으로 계산한 추정입니다. Rapid Trigger는 반영하지 않습니다.

원인 키 찾는 순서

1. 키보드에서 손을 떼고 30초쯤 둡니다. 이때 주황 테두리가 생기는 키는 아무도 누르지 않았는데 센서가 눌림을 감지한 키입니다. 키캡이 스템을 미리 누르고 있거나 하우징에 닿아 있을 가능성이 큽니다.
2. 키캡 가장자리를 하나씩 살짝 건드려 봅니다. 눌러야 할 키 말고 옆 키까지 같이 감지되면 그 키캡이 간섭하는 것입니다.
3. 감지된 키 순위 표에서 감지 / 입력 횟수, 최대 깊이, 여유(입력 지점 − 최대 깊이)를 확인합니다. 여유가 거의 없는 키는 그 키만 입력 지점을 더 깊게 잡으면 됩니다. 전체 감도를 낮출 필요가 없습니다.
4. 필요하면 CSV 내보내기로 기록을 저장합니다.

깊이 값 읽는 법

• V3 계열: 원시값 0–65535이며 1638 = 0.1 mm입니다. 펌웨어는 0.1 mm보다 얕은 눌림을 보고하지 않으므로, 여기에 뜨는 키는 실제로 0.1 mm 이상 눌린 상태입니다.
• V2 계열: 원시값 0–255이며, 임계값과 같은 1.5–3.6 mm 눈금입니다.
• 노이즈는 보통 ±1–2 단위입니다. 너무 자주 깜빡이는 키가 있으면 노이즈 무시 값을 올려 보세요.

2. 윈도우 키 입력 지점 바꾸기 (Synapse에서 안 되는 키)

V3 펌웨어의 센서 매트릭스에는 윈도우 키(fwID 127)가 다른 키와 똑같이 아날로그 키로 들어 있습니다. Synapse 화면에서만 빠져 있을 뿐, 키별 설정 명령 02:92(읽기) / 02:12(쓰기)로 다른 키처럼 값을 넣을 수 있습니다.

1. Synapse를 완전히 종료합니다 (트레이 아이콘 → 종료). Synapse가 실행 중이면 같은 통로로 키보드와 통신하고, 모드를 바꾸거나 설정을 다시 쓰면서 RAM(프로필 0) 값을 덮어쓸 수 있습니다. 활성 프로필 번호도 읽히지 않습니다.
2. web/index.html → 키 입력 지점 (윈도우 키) 탭에서 키(기본값 Win)를 고르고 현재 값 읽기를 누릅니다.
3. 새 입력 지점(mm)과 해제 지점(mm)을 넣고 적용합니다.
   • 해제 지점은 입력 지점보다 약 0.1 mm 이상 얕아야 합니다(최소 간격: V2 0.08 mm는 펌웨어 기준, V3 0.09 mm는 Synapse 기본 간격을 따른 이 도구의 기준). 추천값 버튼을 누르면 입력 지점보다 0.2 mm 얕은 값이 들어갑니다. V2 계열은 해제 지점을 1.54 mm보다 얕게 둘 수 없습니다(펌웨어 하한).
   • 도구는 현재 값을 다시 읽고, 두 지점만 바꿔 쓴 다음, 한 번 더 읽어서 값이 들어갔는지 확인합니다. 키 기능(fnId)은 그대로 둡니다.
   • 프로필 0 (RAM): 바로 적용되지만 키보드를 다시 꽂거나 Synapse가 모드를 바꾸면 원래대로 돌아갑니다. 먼저 이걸로 시험해 보세요.
   • 활성 프로필 슬롯 (플래시): 키보드에 저장됩니다. Huntsman V3 Pro 8KHz 실기기에서 윈도우 키를 2.7 mm로 저장한 뒤 Synapse를 켰을 때도 2.7 mm 근처에서 입력되는 것을 확인했습니다.
   • Synapse에서 프로필을 바꾸거나 Synapse가 설정을 다시 쓸 때 값이 덮어써질 수 있습니다. 가끔 현재 값 읽기로 확인하세요.

알아 둘 점

• 실기기 확인: V3 Pro Mini(easyrazer #45), V3 Pro 8KHz(이 저장소).
• 다른 모델은 RAM부터 시험하세요.
• 윈도우 키 실수 입력만 막으면 된다면 Synapse의 게임 모드(윈도우 키 비활성화)도 방법입니다.
• 오른쪽 윈도우 키 자리는 Razer 보드에서 Fn 키(fwID 59)입니다. Fn은 레이어 전환용이라 조절 대상이 아닙니다.

3. 명령줄 도구 (브라우저로 안 될 때)

pip install hidapi

python python/sensorfinder.py list

python python/sensorfinder.py monitor --csv touches.csv

python python/sensorfinder.py get-key --key Win

python python/sensorfinder.py set-key --key Win --mm 3.0

python python/sensorfinder.py set-key --key Win --mm 2.7 --release-mm 2.5 --profile active

• monitor: 깊이 스트림을 보여 줍니다(Synapse 실행 필요). Ctrl+C로 끝내면 감지 횟수 순으로 요약해 줍니다.
• get-key / set-key: Synapse를 종료한 상태에서 씁니다. --profile 기본값은 0(RAM)이고, 1–6은 그 플래시 슬롯, active는 활성 슬롯입니다.
• set-key는 어떤 질문보다 먼저 원래 값과 그대로 되돌리는 명령을 출력합니다. 그 명령으로 되돌릴 수 없는 값(Synapse의 0/0 등)이면 미리 묻고, 질문에 답하는 사이 값이 바뀌면 쓰지 않습니다. 같은 모델 키보드가 두 대 이상 연결돼 있으면 쓰지 않고, 서로 다른 모델이 함께 연결돼 있으면 --pid(예: --pid 02CF)로 고르게 합니다. 취소하거나 확인에 실패하면 0이 아닌 종료 코드로 끝납니다.

This is the beginning of the README. Read the rest at the original. Read the full README ↗