Cách load file JSON vào VIA: Hướng dẫn chi tiết từng bước

Phần dễ nhầm nhất không nằm ở nút Load, mà ở loại file. VIA definition JSON, bản sao keymap và firmware là ba thứ khác nhau. Bài này đi từ cách nhận biết đúng file đến xử lý lỗi V2/V3, lỗi không thấy thiết bị và trường hợp VIA hiện sai layout.

File JSON VIA là gì?

VIA cần một keyboard definition để biết bàn phím có layout vật lý nào, ma trận phím ra sao, có những lựa chọn layout nào và có các mục điều khiển như knob hoặc đèn hay không. Definition này được lưu ở định dạng JSON. VIA còn dùng thông tin nhận diện USB trong definition để ghép đúng giao diện với thiết bị đang kết nối.

Nếu definition của bàn phím đã có trong cơ sở dữ liệu VIA, ứng dụng có thể nhận thiết bị mà không cần nạp tay. Bạn chỉ cần load JSON khi nhà sản xuất hoặc nơi bán cung cấp một definition riêng, model chưa có trong VIA, hoặc revision PCB cần file khác với bản phổ biến.

Đừng nhầm bốn loại file này

Loại file	Dùng để làm gì?	Nạp ở đâu?
VIA definition .json	Giúp VIA nhận đúng layout, matrix và tính năng của bàn phím	Design → Load Draft Definition
Keymap/layout backup	Khôi phục cách gán phím, layer hoặc macro đã lưu	Configure → Save + Load
QMK info.json	Mô tả bàn phím trong mã nguồn QMK	Không nạp trực tiếp vào VIA
Firmware .hex, .bin, .uf2	Phần mềm chạy bên trong PCB	Flash bằng công cụ và quy trình riêng của đúng model

Điểm quan trọng: load JSON không phải flash firmware. Definition chỉ giúp VIA hiểu thiết bị. Bản thân bàn phím vẫn phải chạy firmware có hỗ trợ VIA thì ứng dụng mới có thể đọc và ghi keymap.

Cần chuẩn bị gì trước khi load JSON?

• Máy tính Windows, macOS hoặc Linux và một trình duyệt Chromium có WebHID. Chrome hoặc Edge thường là lựa chọn dễ dùng nhất cho VIA web.
• Cáp USB có truyền dữ liệu. Nhiều sợi cáp chỉ sạc được nhưng không giúp trình duyệt giao tiếp với bàn phím.
• File JSON đúng model, phiên bản PCB, layout và chế độ kết nối. Bản wired và tri-mode có thể dùng definition khác nhau.
• Firmware trên bàn phím đã hỗ trợ VIA.
• Nếu file nằm trong .zip hoặc .rar, hãy giải nén trước. Nút Load cần file .json, không nhận cả gói nén.

Bạn có thể tìm file theo từng model trong kho firmware và VIA JSON của Levi Modding. Khi lấy file từ nơi khác, ưu tiên trang hỗ trợ của nhà sản xuất hoặc nguồn đi kèm đúng chiếc bàn phím đang dùng. Không chọn file chỉ vì tên model gần giống.

Nếu đang kiểm tra một kit mới, hãy đối chiếu tên PCB hoặc revision in trên mạch với tài liệu của kit. Bài cách chọn và kiểm tra kit bàn phím cơ có thêm checklist về PCB, hotswap, layout và firmware trước khi build.

Cách load file JSON vào VIA từng bước

Bước 1: Mở VIA và kết nối bàn phím

Truy cập usevia.app bằng Chrome hoặc Edge. Cắm bàn phím trực tiếp vào máy tính bằng cáp data. Nếu manual của model yêu cầu dùng VIA ở chế độ có dây, hãy chuyển công tắc sang wired/USB trước khi tiếp tục.

Bạn chưa cần bấm Authorize device ngay. Với những model cần sideload definition, nạp JSON trước thường giúp VIA nhận diện đúng bàn phím khi quay lại tab Configure.

Bước 2: Bật Show Design tab trong Settings

1. Nhấn biểu tượng bánh răng Settings trên thanh điều hướng phía trên.
2. Tìm dòng Show Design tab.
3. Bật công tắc ở bên phải. Biểu tượng Design sẽ xuất hiện cạnh Configure và Key Tester.

Nếu không thấy tuỳ chọn này, hãy kiểm tra bạn đang mở đúng VIA tại usevia.app và tải lại trang. Giao diện cũ hoặc một bản VIA do nhà bán hàng tuỳ biến có thể sắp xếp menu khác.

Bước 3: Mở Design và xác nhận cảnh báo

Nhấn tab Design. Lần đầu mở, VIA sẽ nhắc rằng khu vực này dùng để sideload keyboard definition phục vụ phát triển và xử lý lỗi. Nhấn Confirm để vào màn hình Add Definition.

Cảnh báo này không có nghĩa là thao tác load JSON sẽ flash hoặc sửa firmware. VIA chỉ nhắc bạn phải dùng definition do nhà sản xuất hoặc nguồn cung cấp đáng tin cậy phát hành cho đúng thiết bị.

Bước 4: Chọn Load Draft Definition

1. Tại dòng Load Draft Definition, nhấn Load.
2. Chọn file có đuôi .json đã giải nén.
3. Chờ VIA đọc file. Nếu thành công, mục Draft Definitions sẽ tăng số lượng definition đã nạp.

Nếu hệ điều hành đang ẩn phần mở rộng, hãy kiểm tra tên file thật. Một file có tên giống keyboard.json.txt vẫn là file văn bản và sẽ không hoạt động như definition JSON.

Bước 5: Chỉ bật Use V2 definitions khi cần

VIA hiện có công tắc Use V2 definitions (deprecated). Hãy để công tắc này tắt khi thử lần đầu. Chỉ bật V2 nếu file cũ báo lỗi định dạng và nguồn tải xác nhận đó là definition V2.

Nếu bật V2 vẫn lỗi, đừng sửa ngẫu nhiên nội dung JSON. Hãy tìm definition V3 dành cho đúng model hoặc xin lại file từ nhà sản xuất. Một file load được nhưng sai vendorId, productId, matrix hoặc layout vẫn có thể khiến VIA không nhận hoặc hiển thị sai bàn phím.

Bước 6: Quay lại Configure và Authorize device

1. Nhấn tab Configure.
2. Chọn Authorize device +.
3. Trong cửa sổ quyền của trình duyệt, chọn đúng bàn phím rồi nhấn Connect.
4. Chờ layout xuất hiện. Đối chiếu số phím, vị trí knob, cụm điều hướng và các lựa chọn ANSI/ISO với bàn phím thật.

Nếu cửa sổ cấp quyền có nhiều thiết bị HID, đừng chọn theo cảm tính. Rút các bàn phím hoặc macropad không cần thiết, mở lại Authorize device và chọn thiết bị vừa xuất hiện.

Bước 7: Kiểm tra trước khi remap

• Mở Key Tester và nhấn từng phím để kiểm tra tín hiệu.
• Trong Configure, xem đúng layer trước khi thay đổi. Layer 0 thường là lớp cơ bản; phím Fn thường gọi một layer khác theo keymap của model.
• Thử đổi một phím ít rủi ro, kiểm tra kết quả rồi mới chỉnh nhiều phím.
• Vào Save + Load để lưu bản sao keymap sau khi hoàn tất.

VIA ghi thay đổi vào vùng lưu trữ mà firmware hỗ trợ, nên nhiều keymap có hiệu lực ngay. Tuy vậy, số layer, macro, đèn và các menu xuất hiện vẫn phụ thuộc firmware cùng definition của từng bàn phím.

Xử lý lỗi khi VIA không nhận file JSON hoặc bàn phím

Load JSON xong nhưng VIA báo lỗi đỏ

• Kiểm tra file đã được giải nén và đúng đuôi .json.
• Mở file bằng trình soạn thảo văn bản. Nếu nội dung là một trang HTML, thông báo Google Drive hoặc ký tự rác, bạn đã tải nhầm trang trung gian chứ không phải JSON thật.
• Đối chiếu model, revision PCB, ANSI/ISO, wired/tri-mode và phiên bản definition.
• Nếu nguồn ghi rõ file V2, bật Use V2 definitions rồi load lại một lần.

Authorize device nhưng danh sách trống

• Đổi sang cáp USB chắc chắn có truyền data.
• Thử cổng USB khác và ưu tiên cắm trực tiếp thay vì qua hub.
• Đóng những cửa sổ VIA khác hoặc phần mềm đang giữ kết nối với bàn phím, sau đó mở lại usevia.app.
• Dùng Chrome hoặc Edge trên máy tính. Firefox không phải lựa chọn phù hợp cho quy trình WebHID này.
• Nếu bàn phím có nhiều chế độ, làm đúng bước chuyển wired/USB trong manual của model.

Trình duyệt thấy thiết bị nhưng Configure vẫn trống

Trường hợp này thường liên quan đến một trong hai điểm: definition không khớp mã nhận diện của thiết bị, hoặc firmware trên bàn phím chưa bật VIA. Hãy kiểm tra lại file của đúng revision trước. Nếu file chắc chắn đúng nhưng layout vẫn không hiện, dùng firmware và hướng dẫn từ nhà sản xuất thay vì flash thử một file gần tên.

VIA hiện layout nhưng số phím hoặc knob bị sai

Bạn đã nạp được một definition, nhưng nhiều khả năng đó không phải file của đúng biến thể. Ví dụ, hai PCB cùng tên thương mại có thể khác matrix, knob, split backspace, ANSI/ISO hoặc chế độ kết nối. Xoá definition sai trong Design nếu giao diện cho phép, nạp file đúng rồi Authorize lại thiết bị.

Đổi keymap nhưng bấm phím không ra chức năng mới

• Kiểm tra bạn đang sửa đúng layer.
• Nhấn lại phím trong Key Tester để phân biệt lỗi mapping với lỗi switch hoặc PCB.
• Không gán đè phím chuyển layer nếu chưa tạo đường quay lại layer cơ bản.
• Nếu mọi thay đổi đều không có tác dụng, khởi động lại VIA, Authorize lại thiết bị và kiểm tra firmware của model.

Những thao tác không nên làm

• Không flash firmware chỉ vì JSON báo lỗi. Hai thao tác giải quyết hai lớp vấn đề khác nhau.
• Không dùng JSON của model gần giống. Tên case giống nhau không đảm bảo PCB, matrix và mã USB giống nhau.
• Không chỉnh trực tiếp JSON khi chưa hiểu cấu trúc. Một file hợp cú pháp vẫn có thể mô tả sai phần cứng.
• Không remap hàng loạt ngay lần đầu. Kiểm tra một phím, một layer và lưu backup trước.
• Không xoá phím Fn hoặc phím chuyển layer một cách tuỳ tiện. Bạn có thể tự làm mất đường truy cập các chức năng đang nằm ở layer phụ.

Câu hỏi thường gặp

Có phải load JSON mỗi lần mở VIA không?

VIA thường ghi nhớ draft definition đã nạp trong dữ liệu của ứng dụng hoặc trình duyệt. Bạn có thể phải load lại nếu xoá dữ liệu website, dùng cửa sổ riêng tư, đổi trình duyệt hoặc chuyển sang máy khác.

Load JSON có làm mất keymap hiện tại không?

Definition JSON chủ yếu giúp VIA mô tả và nhận diện bàn phím. Nó không giống thao tác nạp một bản keymap backup. Dù vậy, trước khi chỉnh layer hoặc macro, bạn vẫn nên lưu keymap hiện tại trong Save + Load.

Có thể dùng JSON của bản wired cho bản tri-mode không?

Chỉ dùng chung khi nhà sản xuất nói rõ hai bản có cùng definition. Nếu nguồn cung cấp tách file wired và tri-mode, hãy xem chúng là hai revision khác nhau và chọn đúng file.

V2 và V3 khác nhau thế nào đối với người dùng?

V3 là định dạng hiện hành của VIA và hỗ trợ cách mô tả giao diện mới hơn. Công tắc V2 được giữ để mở một số definition cũ, nhưng chính giao diện VIA đã đánh dấu V2 là deprecated. Vì vậy, ưu tiên file V3; chỉ dùng V2 khi đúng nguồn của model yêu cầu.

Tại sao JSON load thành công nhưng bàn phím vẫn không xuất hiện?

Load thành công chỉ cho biết JSON đọc được. VIA còn phải ghép definition với mã nhận diện thiết bị và giao tiếp với firmware hỗ trợ VIA. Sai revision, sai firmware, cáp chỉ sạc hoặc chưa cấp quyền WebHID đều có thể khiến Configure vẫn trống.

Checklist nhanh sau khi hoàn tất

• Draft Definitions hiển thị file đã nạp.
• Authorize device thấy đúng bàn phím.
• Configure hiện đúng layout và đúng revision.
• Key Tester nhận đủ các phím.
• Layer và phím Fn hoạt động đúng.
• Đã lưu một bản keymap backup trước khi chỉnh sâu.

Nếu vẫn chưa tìm được file phù hợp, hãy ghi lại chính xác tên model, revision PCB, kiểu kết nối và ảnh nhãn dưới đáy hoặc trên PCB. Những thông tin này hữu ích hơn nhiều so với chỉ gửi tên thương mại của bàn phím, đặc biệt với các model có nhiều đợt mạch khác nhau.