VIA가 JSON을 읽는 과정
파일 불러오기부터 키보드 식별·레이아웃 생성·펌웨어 통신까지
- VIA의 JSON은 펌웨어 자체가 아니라 키보드의 구조와 화면 표시 방식을 설명하는 정의 파일입니다.
- VIA는 JSON을 파싱한 뒤 Vendor ID와 Product ID를 이용해 연결된 USB 장치와 정의를 연결합니다.
- 키 배열은 JSON의 행·열 좌표, 크기, 회전값, 레이아웃 옵션을 바탕으로 화면에 생성됩니다.
- JSON을 불러왔다고 키보드 펌웨어가 바뀌는 것은 아니며 실제 키맵 변경은 VIA 프로토콜을 통해 펌웨어로 전달됩니다.
- JSON이 잘못되면 배열이 어긋나거나 장치가 표시되지 않을 수 있지만, 올바른 파일을 다시 불러오면 대부분 해결할 수 있습니다.
VIA에서 키보드용 JSON 파일을 불러오면 몇 초 뒤 화면에 실제 키보드와 비슷한 배열이 나타납니다. 겉으로 보면 VIA가 JSON 파일 안에 저장된 키맵을 그대로 꺼내 보여주는 것처럼 느껴질 수 있습니다. 하지만 실제 동작은 그보다 여러 단계로 나뉩니다.
JSON 파일은 키보드 펌웨어를 담은 파일도 아니고, 현재 사용 중인 키맵 전체를 저장한 백업 파일도 아닙니다. VIA가 해당 키보드를 어떤 장치로 식별해야 하는지, 화면에 몇 개의 키를 어느 위치에 배치해야 하는지, 사용자가 선택할 수 있는 물리 배열은 무엇인지 설명하는 키보드 정의 파일에 가깝습니다.
VIA는 먼저 JSON의 문법을 검사하고 필요한 속성을 읽습니다. 그다음 USB로 연결된 장치의 식별 정보와 JSON의 정보를 비교하고, 레이아웃 데이터를 이용해 키보드 모양을 구성합니다. 이후 사용자가 화면에서 키를 변경하면 JSON에 직접 저장하는 것이 아니라 VIA 프로토콜을 통해 키보드 펌웨어에 명령을 전송합니다.
따라서 VIA의 동작을 제대로 이해하려면 JSON 파일, 웹 애플리케이션, 브라우저의 장치 접근 기능, USB HID 통신, 키보드 펌웨어를 서로 구분해서 볼 필요가 있습니다. 이번 글에서는 사용자가 JSON 파일을 불러온 순간부터 키보드 배열이 화면에 나타나고 실제 키맵 변경 명령이 전달되기 전까지의 과정을 순서대로 살펴보겠습니다.
1. JSON을 불러오면 가장 먼저 무엇이 일어날까?
사용자가 VIA의 Design 탭에서 JSON 파일을 선택하면 가장 먼저 실행되는 작업은 파일 읽기와 JSON 파싱입니다. 파싱은 문자열로 저장된 JSON 내용을 프로그램이 사용할 수 있는 데이터 구조로 변환하는 과정입니다.
JSON 파일은 사람이 읽을 수 있는 텍스트 형태이지만, VIA는 파일 내용을 단순한 문장으로 취급하지 않습니다. 중괄호 안의 객체, 대괄호 안의 배열, 속성 이름과 값의 관계를 분석해 각각을 프로그램 내부의 데이터로 바꿉니다.
예를 들어 JSON 안에 키보드 이름, Vendor ID, Product ID, 키 배열 정보가 들어 있다면 VIA는 이를 각각 별도의 속성으로 분리합니다. 이후 화면 제목에는 키보드 이름을 사용하고, 장치 식별 과정에는 Vendor ID와 Product ID를 사용하며, 키보드 그림을 만들 때는 레이아웃 데이터를 사용합니다.
- 사용자가 로컬 저장장치에서 JSON 파일을 선택합니다.
- 브라우저가 파일의 텍스트 내용을 읽습니다.
- VIA가 JSON 문법에 맞게 작성되었는지 파싱합니다.
- 필수 속성과 지원되는 정의 버전을 확인합니다.
- 키보드 식별 정보와 레이아웃 정보를 내부 데이터로 저장합니다.
- 연결된 장치와 정의를 연결할 준비를 합니다.
이 단계에서 쉼표가 빠졌거나 따옴표가 닫히지 않은 경우처럼 JSON 문법 자체가 잘못되어 있으면 VIA는 내용을 정상적으로 해석할 수 없습니다. 파일은 선택되었지만 아무 변화가 없거나 정의를 불러올 수 없다는 오류가 표시될 수 있습니다.
반대로 문법은 올바르지만 VIA가 요구하는 필수 속성이 빠진 경우도 있습니다. 이때는 일반 JSON 파서에서는 정상 파일로 판정될 수 있지만, VIA 키보드 정의로서는 불완전합니다. 즉 JSON 문법이 맞는 것과 VIA 규격에 맞는 것은 서로 다른 조건입니다.
VIA는 JSON을 읽을 때 모든 내용을 한 번에 같은 용도로 처리하지 않습니다. 장치 식별에 쓰이는 정보, 화면 구성에 쓰이는 정보, 레이아웃 옵션에 쓰이는 정보를 분리해 사용합니다. 따라서 한 부분이 잘못되면 전체가 완전히 멈추기도 하지만, 경우에 따라서는 장치는 잡히고 배열만 어긋나는 부분 오류가 나타날 수도 있습니다.
2. VIA JSON은 펌웨어 파일이 아니다
VIA JSON을 이해할 때 가장 먼저 구분해야 하는 것은 정의 파일과 펌웨어 파일의 차이입니다. JSON을 불러오면 키보드 화면이 바뀌기 때문에 JSON이 키보드 내부 프로그램을 수정한다고 생각하기 쉽지만, 일반적인 VIA 키보드 정의 JSON은 펌웨어를 플래시하지 않습니다.
펌웨어는 키보드 마이크로컨트롤러에서 직접 실행되는 프로그램입니다. 키 매트릭스를 스캔하고, 디바운스를 처리하며, 눌린 키를 키코드로 변환하고, USB HID 보고서를 PC에 전송하는 역할을 담당합니다. VIA 기능을 사용하려면 이러한 펌웨어 안에 VIA 통신 기능이 미리 포함되어 있어야 합니다.
반면 키보드 정의 JSON은 VIA 애플리케이션이 해당 펌웨어와 어떻게 대응해야 하는지 알려줍니다. 화면에 표시할 키보드 이름, USB 장치 식별값, 키의 위치와 크기, 선택 가능한 레이아웃 구성을 설명합니다.
이 차이를 알면 JSON을 잘못 불러왔을 때 왜 키보드가 바로 고장 나지 않는지도 이해할 수 있습니다. VIA가 잘못된 화면 정의를 사용한 것이지, 키보드의 실행 코드를 다시 기록한 것은 아니기 때문입니다.
다만 화면에 표시된 키 위치와 펌웨어의 키 인덱스가 맞지 않는 상태에서 키맵을 변경하면 의도하지 않은 위치의 키가 바뀔 수 있습니다. 따라서 배열이 어긋나 있거나 키 수가 맞지 않을 때는 설정을 계속 저장하기보다 올바른 JSON을 다시 확인하는 것이 안전합니다.
JSON을 불러온 뒤에는 곧바로 키를 변경하지 말고 화면의 키 개수, Enter 키 모양, 스페이스바 길이, 노브 위치가 실제 키보드와 일치하는지 먼저 확인하는 것이 좋습니다. 물리 배열이 맞아야 화면에서 선택한 키와 펌웨어에 전달되는 키 위치도 정확하게 대응합니다.
3. VIA는 Vendor ID와 Product ID로 장치를 찾는다
JSON 파싱이 끝나면 VIA는 이 정의가 어떤 키보드에 해당하는지 확인해야 합니다. 여기서 핵심이 되는 값이 Vendor ID와 Product ID입니다. 보통 VID와 PID라고 줄여 부릅니다.
USB 장치는 컴퓨터에 연결될 때 자신이 어떤 제조사와 제품에 해당하는지 식별 정보를 제공합니다. VIA 키보드 정의 JSON에도 이와 대응하는 Vendor ID와 Product ID가 들어 있습니다. VIA는 JSON 속의 값과 브라우저가 감지한 USB HID 장치의 값을 비교해 서로 맞는 정의를 연결합니다.
예를 들어 JSON의 Vendor ID는 같지만 Product ID가 다른 경우, 같은 제조사에서 만든 다른 모델이거나 동일 제품의 다른 버전일 수 있습니다. VIA는 이름이 비슷하다는 이유만으로 장치를 연결하지 않고, 실제 식별값을 중심으로 정의를 선택합니다.
- JSON에서 Vendor ID와 Product ID를 읽습니다.
- 브라우저가 접근 가능한 HID 장치 목록을 확인합니다.
- 사용자가 장치 연결 권한을 승인합니다.
- 장치가 보고한 VID·PID와 JSON 값을 비교합니다.
- 값이 일치하면 해당 키보드 정의를 장치에 연결합니다.
- 일치하지 않으면 정의는 읽혔어도 Configure 화면에 장치가 나타나지 않을 수 있습니다.
여기서 중요한 것은 JSON을 Design 탭에 불러오는 것과 장치 접근을 승인하는 것이 별개의 과정이라는 점입니다. JSON 파일은 키보드 정의를 VIA에 등록하지만, 브라우저가 자동으로 모든 USB 장치에 접근할 수 있게 하지는 않습니다.
웹 기반 VIA는 브라우저의 장치 접근 기능을 이용하기 때문에 사용자가 직접 연결할 장치를 선택하고 권한을 허용해야 합니다. JSON이 정상인데도 키보드가 나타나지 않는다면 정의 파일뿐 아니라 브라우저 권한과 실제 연결 모드도 함께 확인해야 합니다.
또한 일부 키보드는 유선, 2.4GHz, 부트로더 모드에서 서로 다른 Product ID를 사용할 수 있습니다. 제조사가 연결 방식이나 펌웨어 버전에 따라 별도의 JSON을 제공하는 이유도 이러한 장치 식별값이나 통신 구현이 다를 수 있기 때문입니다.
VIA가 키보드의 제품명만 보고 장치를 찾는다고 생각하기 쉽지만, 제품명은 사용자에게 보여주는 표시 정보에 가깝습니다. 실제 연결에서는 VID와 PID 같은 USB 식별값이 더 중요합니다. 따라서 다른 모델의 이름을 JSON에서 수정한다고 해서 그 JSON이 내 키보드와 호환되는 것은 아닙니다.
4. 키보드 이름과 식별값을 읽은 뒤 레이아웃을 해석한다
장치 식별에 필요한 정보가 확인되면 VIA는 키보드를 화면에 그리기 위한 레이아웃 데이터를 해석합니다. 키보드 정의 JSON에는 각 키의 위치, 너비, 높이, 간격, 회전 같은 시각적 정보가 포함될 수 있습니다.
일반적인 키 하나는 1유닛 크기를 기준으로 배치됩니다. 스페이스바처럼 긴 키는 여러 유닛의 너비를 가지며, ISO Enter처럼 특수한 모양은 너비와 높이 정보가 함께 사용됩니다. 인체공학 배열이나 분리형 키보드는 키 그룹에 회전값을 적용해 실제 배치와 비슷하게 표현할 수도 있습니다.
VIA는 이러한 값을 순서대로 읽어 화면 좌표로 변환합니다. 배열 안에서 앞에 있는 항목부터 키 요소를 만들고, 현재 좌표와 크기를 계산한 뒤 다음 키를 배치합니다. 행이 바뀌면 세로 좌표를 이동하고, 별도의 위치값이 있으면 기본 간격에 그 값을 더해 키를 떨어뜨려 놓습니다.
이 과정에서 VIA가 만드는 것은 단순한 키보드 그림이 아닙니다. 화면에 표시된 각 키에는 펌웨어의 특정 키 위치와 연결되는 정보가 함께 붙습니다. 사용자가 키 하나를 클릭했을 때 어느 레이어의 몇 번째 위치를 읽거나 변경해야 하는지 알 수 있어야 하기 때문입니다.
따라서 시각적 위치만 비슷하게 만든 JSON은 충분하지 않습니다. 화면에서 첫 번째 줄 세 번째 키로 보이는 요소가 실제 펌웨어의 어느 매트릭스 위치 또는 키 인덱스에 해당하는지 정확히 연결되어야 합니다.
5. 화면의 키와 펌웨어의 키 위치는 어떻게 연결될까?
VIA 화면에서 키를 선택하면 해당 키의 색상이 바뀌고 아래쪽에 지정 가능한 키코드 목록이 나타납니다. 이때 VIA는 화면의 픽셀 좌표를 그대로 펌웨어에 보내지 않습니다. JSON을 해석하며 만들어 둔 논리적 키 위치를 기준으로 명령을 구성합니다.
키보드 펌웨어는 보통 키를 행과 열로 구성된 매트릭스로 관리합니다. 하지만 사용자가 보는 물리 배열의 순서와 전기적 매트릭스 배선 순서는 같지 않을 수 있습니다. 화면에서는 왼쪽 위부터 오른쪽으로 키가 배열되어 있어도 PCB에서는 배선 효율 때문에 서로 다른 행과 열에 연결될 수 있습니다.
이 차이를 연결하는 것이 레이아웃 정의입니다. JSON은 사용자에게 보여줄 물리적 배치를 구성하면서 각 키를 펌웨어가 이해하는 위치와 연결합니다. VIA는 이 연결 관계를 사용해 사용자가 선택한 화면상의 키가 펌웨어의 어느 위치에 해당하는지 판단합니다.
- 사용자가 VIA 화면에서 특정 키를 클릭합니다.
- VIA가 해당 화면 요소에 연결된 키 위치를 확인합니다.
- 현재 선택된 레이어 번호를 확인합니다.
- 펌웨어에 해당 위치의 현재 키코드를 요청하거나 변경 명령을 준비합니다.
- 펌웨어가 응답한 키코드를 VIA 화면의 이름과 아이콘으로 변환합니다.
JSON의 키 순서와 펌웨어가 기대하는 키 순서가 다르면 화면에서 A 위치를 바꿨는데 실제로는 다른 키가 변경되는 현상이 발생할 수 있습니다. 배열은 비슷하게 보이지만 특정 키만 엉뚱하게 바뀌는 오류라면 단순한 시각적 크기보다 키 위치 매핑이 잘못되었을 가능성을 확인해야 합니다.
특히 노브, 분할 스페이스바, 추가 매크로 키, 특수 배열을 지원하는 제품은 일반적인 ANSI 배열보다 정의가 복잡합니다. 같은 PCB가 여러 물리 배열을 지원하는 경우에는 현재 선택된 레이아웃 옵션에 따라 표시할 키와 숨길 키도 달라져야 합니다.
새 JSON을 적용한 뒤에는 자주 쓰는 키 하나만 바꾸기보다 VIA의 키 테스트 기능으로 전체 배열을 먼저 확인하는 것이 좋습니다. 화면에서 눌린 위치와 실제 키 위치가 일치하는지 확인하면 잘못된 매핑 상태에서 여러 키를 수정하는 실수를 줄일 수 있습니다.
6. 레이아웃 옵션은 어떻게 선택적으로 표시될까?
하나의 키보드 PCB가 항상 하나의 물리 배열만 지원하는 것은 아닙니다. 같은 PCB에서 ANSI Enter와 ISO Enter를 선택할 수 있거나, 일반 스페이스바와 분할 스페이스바 중 하나를 조립할 수 있습니다. 왼쪽 Shift의 길이, Backspace 분할 여부, 하단 열 배열이 달라지는 제품도 있습니다.
이런 키보드의 모든 가능한 키를 화면에 동시에 표시하면 실제 조립 상태와 맞지 않는 키가 겹쳐 보이게 됩니다. VIA는 JSON에 정의된 레이아웃 옵션을 읽어 사용자가 선택한 구성에 해당하는 키만 표시합니다.
레이아웃 옵션은 특정 영역이 몇 가지 구성 중 하나로 바뀔 수 있다는 뜻입니다. 예를 들어 옵션 0의 선택값 0은 ANSI Enter, 선택값 1은 ISO Enter를 나타낼 수 있습니다. JSON의 각 키에는 자신이 어떤 옵션과 선택값에서 표시되어야 하는지 구분하는 정보가 포함될 수 있습니다.
사용자가 VIA에서 레이아웃 옵션을 바꾸면 전체 JSON을 다시 읽는 것이 아니라 이미 파싱된 정의를 기준으로 표시 조건을 다시 계산합니다. 선택한 조건에 맞지 않는 키 요소는 숨기고, 맞는 키 요소를 활성화해 화면 배열을 다시 구성합니다.
레이아웃 옵션은 단순히 보기 좋은 화면을 만들기 위한 기능이 아닙니다. 실제로 존재하지 않는 키 위치를 사용자가 수정하지 않도록 제한하고, 펌웨어가 지원하는 물리 구성과 VIA 화면을 일치시키는 역할을 합니다.
다만 JSON에서 지원한다고 표시된 물리 배열이 펌웨어에서도 반드시 올바르게 구현되어 있다는 의미는 아닙니다. 정의 파일은 화면 구성을 설명하고, 실제 키 위치와 기능 지원은 펌웨어 구현에 달려 있습니다. 두 부분이 같은 기준으로 만들어져야 정상적으로 작동합니다.
VIA JSON은 화면 디자인 파일처럼 보이지만 실제로는 사용자 인터페이스와 펌웨어 사이의 번역표 역할까지 담당합니다. 키의 크기와 위치만 정확해서는 부족하며, 레이아웃 옵션과 펌웨어의 키 인덱스가 같은 구조를 가리켜야 합니다.
7. JSON을 읽었다고 키맵까지 읽은 것은 아니다
VIA가 JSON을 성공적으로 읽고 키보드 그림을 표시했다고 해서 현재 키맵 정보까지 JSON에서 가져온 것은 아닙니다. JSON은 어떤 키가 어디에 존재하는지 알려주지만, 각 위치에 현재 어떤 키코드가 저장되어 있는지는 키보드 펌웨어에 요청해 확인합니다.
즉 화면 구조를 만드는 데이터와 실제 설정값을 가져오는 경로가 다릅니다. VIA는 JSON을 이용해 클릭할 수 있는 키 요소를 만든 뒤, 연결된 키보드에 VIA 프로토콜 명령을 보내 각 레이어의 키코드를 읽습니다.
펌웨어가 반환한 값은 숫자 형태의 키코드일 수 있습니다. VIA는 이 값을 내부 키코드 목록과 비교해 화면에 A, Enter, Left Ctrl, MO(1) 같은 사용자가 이해할 수 있는 이름으로 표시합니다.
- JSON: 키보드 이름, 장치 식별값, 키 위치, 키 크기, 레이아웃 옵션
- VIA 애플리케이션: JSON 해석, 화면 생성, 키코드 이름 변환, 사용자 입력 처리
- 키보드 펌웨어: 현재 레이어별 키코드, 매크로, 조명 설정, 저장 데이터
- USB 통신: VIA의 읽기·쓰기 명령과 펌웨어 응답 전달
이 구조 때문에 같은 JSON을 다른 PC에서 불러와도 키보드 내부에 저장된 키맵이 그대로 나타날 수 있습니다. 설정값이 JSON 파일이나 특정 컴퓨터에만 저장된 것이 아니라, VIA 기능을 지원하는 펌웨어의 비휘발성 저장 영역에 기록되는 구성이 일반적이기 때문입니다.
반대로 JSON만 따로 보관했다고 해서 현재 키맵 설정까지 완전히 백업한 것은 아닐 수 있습니다. 키보드 정의 JSON과 사용자가 저장한 키맵 백업 JSON은 목적과 내부 구성이 다르므로 파일 이름이 같아 보여도 구분해야 합니다.
VIA는 JSON 파일을 파싱한 뒤 장치 식별값과 레이아웃 정보를 분리해 사용합니다. VID·PID로 연결된 키보드와 정의를 대응시키고, 키의 위치·크기·옵션을 해석해 화면 배열을 생성합니다. 하지만 현재 키맵은 JSON에서 직접 읽는 것이 아니라 VIA 프로토콜을 통해 키보드 펌웨어에 요청합니다. 다음 Part에서는 VIA가 실제 키코드를 읽고 쓰는 과정, Raw HID 통신, 정의 버전 차이, JSON 오류 유형과 해결 방법을 이어서 살펴봅니다.
8. VIA는 키코드를 어떤 순서로 읽을까?
키보드 정의 JSON으로 화면 구성이 완료되면 VIA는 연결된 키보드 펌웨어에 현재 설정값을 요청합니다. 이 과정은 일반적인 키보드 입력 보고서와 별도로 동작하는 VIA 명령 통신을 통해 이루어집니다.
사용자가 아무 키도 누르지 않아도 VIA 화면에 각 키의 현재 기능이 나타나는 이유는 VIA가 펌웨어에 레이어별 키코드를 요청하고, 펌웨어가 저장된 값을 응답하기 때문입니다. VIA는 반환된 숫자 값을 다시 사람이 이해할 수 있는 키 이름으로 변환합니다.
예를 들어 펌웨어가 특정 위치의 키코드로 기본 문자 A에 해당하는 값을 반환하면 VIA는 화면에 A를 표시합니다. 레이어 이동 키나 매크로 키처럼 추가 인수가 필요한 키코드는 내부 규칙에 따라 MO(1), LT(1, KC_ESC) 같은 형태로 해석될 수 있습니다.
- VIA가 키보드 정의 JSON으로 화면의 키 위치를 생성합니다.
- 펌웨어가 지원하는 레이어 수와 키맵 구조를 확인합니다.
- VIA가 특정 레이어와 키 위치의 키코드를 요청합니다.
- 키보드 펌웨어가 저장된 키코드 값을 응답합니다.
- VIA가 숫자 값을 키 이름과 기능 이름으로 변환합니다.
- 변환된 결과를 화면의 해당 키 위에 표시합니다.
이 과정은 키 개수와 레이어 수가 많을수록 여러 번 반복될 수 있습니다. VIA가 연결 직후 잠시 로딩하는 것처럼 보이는 이유도 키보드 정의를 읽는 작업뿐 아니라 펌웨어에서 여러 설정값을 가져오는 과정이 함께 진행되기 때문입니다.
VIA 기능을 활성화한 QMK 펌웨어는 VIA Configurator와 통신할 수 있으며, 키맵과 기타 설정을 장치 쪽에 저장하는 기능을 제공합니다. :contentReference[oaicite:0]{index=0}
VIA 화면에 키보드 배열이 나타났다고 해서 통신이 완전히 정상이라는 뜻은 아닙니다. 배열은 JSON만으로도 만들 수 있지만 현재 키코드를 표시하려면 펌웨어의 응답이 필요합니다. 키보드 그림은 보이지만 키맵이 로딩되지 않는다면 JSON보다 펌웨어 통신 단계에서 문제가 발생했을 가능성이 있습니다.
9. Raw HID는 VIA 통신에서 어떤 역할을 할까?
일반적인 키보드는 운영체제에 어떤 키가 눌렸는지를 HID 키보드 보고서로 전달합니다. 하지만 VIA가 키맵을 읽고 수정하려면 단순한 키 입력보다 더 다양한 명령과 데이터가 필요합니다.
QMK의 Raw HID 기능은 키보드와 호스트 프로그램 사이에서 양방향 데이터를 주고받을 수 있도록 만든 통신 방식입니다. 키보드 입력 자체와는 별도의 데이터 채널을 이용해 명령과 응답을 교환할 수 있습니다. :contentReference[oaicite:1]{index=1}
VIA는 이와 같은 HID 기반 통신을 이용해 키보드에 현재 키코드를 요청하거나 새로운 키코드를 기록하도록 명령합니다. 펌웨어는 받은 데이터에서 명령 종류와 대상 위치를 분석한 뒤 해당 값을 읽거나 변경하고 결과를 VIA에 돌려줍니다.
| 구분 | 일반 키 입력 | VIA 설정 통신 |
|---|---|---|
| 목적 | 눌린 키 전달 | 설정 읽기·쓰기 |
| 데이터 | 키보드 HID 보고서 | 명령·위치·설정값 |
| 방향 | 주로 키보드 → PC | PC ↔ 키보드 |
| 주요 결과 | 문자·단축키 입력 | 키맵·조명·매크로 변경 |
이 통신은 브라우저에서 보이는 키보드 그림과는 직접적인 관련이 없습니다. JSON이 화면 구조를 만들고, Raw HID 계열의 통신이 실제 장치 설정을 읽고 쓰는 역할을 맡는 구조입니다.
따라서 다른 키보드의 JSON을 강제로 불러와 화면을 표시하는 데 성공하더라도 펌웨어가 기대하는 명령 구조나 키 위치가 다르면 정상적으로 설정할 수 없습니다. 화면 정의와 펌웨어 프로토콜 구현이 함께 맞아야 합니다.
VIA 연결 문제를 확인할 때는 키보드 입력이 정상인지와 VIA 설정 통신이 정상인지를 분리해서 확인해야 합니다. 타이핑이 된다고 VIA 통신까지 정상인 것은 아니며, 반대로 VIA에서 장치를 읽더라도 운영체제의 키 입력 설정에 별도 문제가 있을 수 있습니다.
10. 키 하나를 변경하면 JSON이 수정될까?
사용자가 VIA 화면에서 키 하나를 선택하고 다른 키코드를 지정하면 정의 JSON 파일이 수정되는 것은 아닙니다. JSON은 키보드 구조를 설명하는 기준으로 계속 유지되고, 실제 변경값은 키보드 펌웨어 쪽으로 전달됩니다.
VIA는 먼저 현재 선택된 레이어와 화면상의 키 위치를 확인합니다. 그다음 사용자가 선택한 키코드를 펌웨어에서 사용하는 값으로 변환하고, 변경할 레이어·행·열 또는 키 인덱스와 함께 쓰기 명령을 전송합니다.
- 사용자가 화면에서 변경할 키를 선택합니다.
- VIA가 해당 키의 논리적 위치와 현재 레이어를 확인합니다.
- 새로 선택한 기능을 펌웨어용 키코드 값으로 변환합니다.
- 키보드에 키맵 변경 명령을 전송합니다.
- 펌웨어가 동적 키맵 또는 저장 영역의 값을 갱신합니다.
- VIA가 변경된 값을 다시 읽거나 화면에 즉시 반영합니다.
VIA 펌웨어는 일반적으로 전원이 꺼져도 설정이 유지될 수 있도록 비휘발성 저장 영역을 활용합니다. 다만 저장 방식과 저장 가능한 레이어 수, 매크로 용량은 키보드 펌웨어와 MCU 구성에 따라 달라질 수 있습니다.
이 때문에 같은 키보드를 다른 컴퓨터에 연결해도 이전에 VIA에서 변경한 키맵이 유지되는 경우가 많습니다. 설정값이 브라우저에만 저장된 것이 아니라 키보드 내부에 기록되어 있기 때문입니다.
반대로 JSON 파일을 삭제하거나 다른 컴퓨터에서 VIA를 열더라도 키보드 내부의 키맵이 즉시 초기화되지는 않습니다. VIA가 해당 장치를 해석할 수 있는 올바른 정의만 다시 확보하면 펌웨어에 저장된 설정을 읽어올 수 있습니다.
VIA JSON은 설계도이고 키보드 내부 설정은 실제 가구 배치에 가깝습니다. 설계도를 지워도 방 안의 가구가 자동으로 사라지지는 않습니다. 하지만 설계도가 잘못되어 있으면 어떤 위치의 가구를 옮기고 있는지 정확히 알기 어려워집니다.
11. JSON 버전이 다르면 무엇이 달라질까?
VIA 키보드 정의에는 규격 버전에 따라 사용할 수 있는 속성과 구조가 달라질 수 있습니다. 오래된 정의와 최신 정의는 기본적인 키보드 식별과 배열 표시라는 목적은 같지만, 사용자 정의 기능과 메뉴 구성 방식에서 차이가 날 수 있습니다.
VIA V3 정의는 키보드 제조사나 개발자가 사용자 정의 UI를 구성하고 펌웨어의 특정 설정 채널과 연결할 수 있도록 확장된 구조를 제공합니다. 공식 문서에서도 V3 정의가 커스텀 기능을 제어할 수 있는 UI 구성을 지원한다고 설명합니다. :contentReference[oaicite:2]{index=2}
예를 들어 단순한 키맵 변경 외에 조명 밝기, 애니메이션 속도, 특수 동작 모드, 제조사가 추가한 기능을 VIA 화면에서 조절하려면 JSON의 메뉴 정의와 펌웨어의 명령 처리 코드가 서로 대응해야 합니다.
버전 번호만 최신으로 바꾼다고 정의가 자동으로 호환되는 것은 아닙니다. 속성 이름과 데이터 구조를 새 규격에 맞게 작성해야 하며, 사용자 정의 메뉴를 추가했다면 펌웨어도 해당 명령을 처리하도록 구현해야 합니다.
구형 JSON이 최신 VIA에서 열리지 않거나 일부 기능이 빠져 보인다면 버전 필드만 확인하지 말고 VIA 공식 규격에서 요구하는 전체 구조와 속성을 함께 비교해야 합니다.
12. JSON 오류는 어느 단계에서 발생할까?
VIA JSON 문제는 모두 같은 증상으로 나타나지 않습니다. 파일 문법, 정의 규격, 장치 식별, 레이아웃 연결, 펌웨어 통신 중 어느 단계에서 문제가 생겼는지에 따라 현상이 달라집니다.
따라서 단순히 “VIA가 인식하지 않는다”라고 판단하기보다 JSON을 불러오는 데 실패했는지, 키보드가 연결되지 않는지, 배열만 잘못 나타나는지, 키 변경만 적용되지 않는지를 구분해야 합니다.
문법 오류는 비교적 쉽게 찾을 수 있지만 키 위치 매핑 오류는 화면이 정상적으로 보이기 때문에 발견하기 어렵습니다. 모든 키를 한 번씩 테스트하고, 각 레이어에서 변경값이 정확한 위치에 적용되는지 확인해야 합니다.
키보드 제조사가 같은 모델명으로 여러 PCB 리비전이나 펌웨어 버전을 배포했다면 JSON도 버전에 따라 달라질 수 있습니다. 제품 이름이 같더라도 VID·PID, 키 위치, 노브 지원, 레이어 수가 다를 수 있으므로 정확한 리비전에 맞는 파일을 사용해야 합니다.
JSON 문제를 해결할 때는 파일을 반복해서 무작정 불러오기보다 ① 파일 파싱 여부, ② 장치 연결 여부, ③ 배열 표시 여부, ④ 키맵 읽기 여부, ⑤ 변경값 저장 여부 순서로 확인하는 것이 효율적입니다.
13. JSON 문제인지 펌웨어 문제인지 구분하는 방법
VIA 오류를 해결할 때 가장 어려운 부분은 JSON 정의와 펌웨어 중 어느 쪽에 문제가 있는지 판단하는 것입니다. 두 요소가 함께 작동하기 때문에 증상만 보고 한쪽을 단정하기 어렵습니다.
가장 먼저 확인할 수 있는 기준은 화면 배열입니다. 키보드 모양이 전혀 나타나지 않거나 물리 배열과 크게 다르면 JSON 정의 문제일 가능성이 높습니다. 반대로 배열은 정확하지만 키코드를 읽지 못하거나 변경값이 저장되지 않으면 펌웨어 통신 문제를 우선 의심할 수 있습니다.
- 키보드 모양이 잘못됨: JSON 레이아웃 정의 확인
- 장치 선택 창에 나타나지 않음: 연결 모드·USB 권한·VID/PID 확인
- 키맵 값을 읽지 못함: VIA 지원 펌웨어와 통신 기능 확인
- 특정 키만 잘못 바뀜: 키 위치와 매트릭스 매핑 확인
- 재부팅 후 설정이 사라짐: 펌웨어 저장 기능과 저장 공간 확인
- 커스텀 메뉴만 작동하지 않음: JSON 메뉴와 펌웨어 핸들러 확인
또한 VIA에서 키보드가 보이지 않는다고 바로 펌웨어를 다시 플래시하는 것은 권장되지 않습니다. 먼저 케이블, 브라우저 권한, 연결 모드, 올바른 JSON 사용 여부를 확인하는 것이 안전합니다.
펌웨어 업데이트가 필요한 상황이라면 제조사가 제공한 정확한 모델과 PCB 버전의 파일을 사용해야 합니다. 정의 JSON과 달리 펌웨어 플래시는 키보드 MCU의 실행 프로그램을 변경하므로 잘못된 파일을 적용하면 정상 부팅이 어려워질 수 있습니다.
14. VIA가 JSON을 읽는 전체 과정 한눈에 보기
브라우저가 사용자가 선택한 로컬 JSON 파일의 텍스트를 읽습니다.
VIA가 JSON을 파싱하고 버전, 이름, 식별값, 레이아웃 데이터를 분리합니다.
JSON의 VID·PID와 연결된 HID 장치의 식별값을 비교합니다.
키 위치, 크기, 회전, 레이아웃 옵션을 바탕으로 키보드 UI를 만듭니다.
화면의 각 키를 펌웨어가 사용하는 매트릭스 위치 또는 키 인덱스와 연결합니다.
VIA가 키보드에 레이어별 키코드와 지원 설정값을 요청합니다.
펌웨어가 반환한 값을 키 이름과 옵션 값으로 변환해 화면에 표시합니다.
사용자의 변경 내용을 펌웨어에 전송하고 장치의 저장 영역에 반영합니다.
VIA 공식 규격에서도 키보드 정의 JSON이 물리 키 배열, 레이아웃 옵션, 노브와 조명 같은 설정 요소를 정의하는 파일이라고 설명합니다. :contentReference[oaicite:3]{index=3}
결국 JSON을 읽는 과정은 단순히 파일을 화면에 표시하는 작업이 아닙니다. VIA가 키보드의 외형과 논리 구조를 이해하고, 연결된 장치와 대응시키며, 펌웨어 통신에 사용할 번역 기준을 만드는 과정입니다.
15. 자주 묻는 질문
아닙니다. 키보드 정의 JSON은 VIA가 장치와 레이아웃을 해석하는 데 사용하는 파일입니다. 펌웨어 플래시 파일과는 역할이 다릅니다.
JSON을 불러오는 것만으로 펌웨어가 바뀌지는 않습니다. 다만 잘못된 키 위치로 설정을 변경하면 의도하지 않은 키가 바뀔 수 있으므로 배열이 맞지 않을 때는 저장 작업을 진행하지 않는 것이 좋습니다.
VID·PID 불일치, 브라우저 장치 권한, USB 케이블, 유선 모드 설정, VIA 미지원 펌웨어 등이 원인일 수 있습니다.
일반적인 키보드 정의 JSON에는 현재 사용 중인 레이어별 키맵이 저장되지 않습니다. 현재 키맵은 연결된 펌웨어에서 읽어옵니다.
목적이 다릅니다. 정의 JSON은 키보드 구조를 설명하고, 키맵 백업 파일은 사용자가 설정한 키 배치를 저장하는 용도로 사용됩니다.
반드시 그렇지는 않습니다. 키 크기와 위치가 맞아도 화면의 키와 펌웨어의 매트릭스 위치가 잘못 연결되어 있을 수 있습니다. 실제 키 변경 테스트까지 확인해야 합니다.
펌웨어가 비휘발성 저장을 정상 지원한다면 대부분 유지됩니다. 저장 방식과 용량은 키보드의 펌웨어 구성에 따라 달라질 수 있습니다.
함께 보면 좋은 글
공식 자료
Sources
1. VIA 공식 문서, Keyboard Definition Specification
2. VIA 공식 문서, Layout Options
3. VIA 공식 문서, Configuring QMK
4. VIA 공식 문서, VIA Version 3 Changes
5. QMK 공식 문서, Raw HID
답글 남기기