Hướng dẫn sử dụng QMK cho bàn phím custom bằng QMK Firmware Builder

qmk firmware

I. Giới thiệu:

  • QMK Firmware là một firmware cho bàn phím cơ custom/DIY mạnh hàng đầu hiện nay.
  • QMK Firmware Builder là một ứng dụng trên nền web có khả năng tự tạo ra file firmware cho bàn phím dựa vào thông tin nguời dùng cung cấp, thay vì việc nguời dùng phải code thủ công bằng C để tạo đuợc file firmware. Firmware Builder hỗ trợ khoảng 90% tính năng của QMK ( 10% còn lại nguời dùng cần tự code dựa theo tài liệu ).
  • Website: KBfirmware.comQMKeyboard.cn
  • Tài liệu về QMK : https://docs.qmk.fm/
  • Đối tượng của Firmware Builder: các bàn phím custom/DIY sử dụng controller ATmega32U2, ATmega32U4, AT90USB1286. Đặc biệt các mẫu bàn phím sau có sẵn preset để nguời dùng trực tiếp keymap, bỏ qua công đoạn vẽ sơ đồ mạch:
    • Tại KBfirmware: GH60, GH60 Satan, Minivan, Planck, S60-X RGB,…
    • Tại QMKeyboard: KBD75 ( R3 trở đi ), TINA ( DZ60 ), NIU/Mechmini2 ( DZ40 )
  • Một số bàn phím không có preset trên website nhưng có firmware QMK do nguời dùng port lên có thể kể tới như: Tada68 ( file .json trong comment ), Whitefox, XD60, B.mini,…

II. Quy trình sử dụng website:

Gồm 3 bước:

B1: Tạo layout phím bằng 1 trong 3 cách:

  • Upload configuration: khi sử dụng website để keymap, ngoài việc tạo file firmware, nguời dùng có thể lưu lại tất cả tùy chỉnh vào một file .json. Mục Upload cho phép tải lên file .json trên máy tính để tùy chỉnh tiếp.
  • Import: với những bàn phím không có sẵn layout trên web, nguời dùng có thể tạo layout của phím trong KLE, sau đó dán Raw Data vào mục này rồi chọn Import để đưa layout vào tùy chỉnh.
  • Choose a preset: chọn một layout sẵn có trên website.

Lưu ý: các preset đều có tính mềm dẻo, tức một preset có thể dùng được cho nhiều layout khác nhau miễn hỗ trợ đủ nút, kích cỡ các nút trong preset không bắt buộc giống y hệt với layout người dùng hàn lên phím. VD: mọi preset cho DZ60 đều chia 3 space, nhưng nếu người dùng chỉ dùng 1 space thường ( size 6, 6.25 hay 7 là như nhau ) thì chỉ cần quan tâm keymap space ở giữa trong preset. Tương tự với các phím Shift phải, Backspace,…

B2: Chỉnh sửa tính năng của phím từ giao diện chính

  • Thẻ Wirings và Pin để chỉnh sửa ma trận phím.
  • Thẻ Keymap và Lightning để gán chức năng cho mỗi nút.
  • Thẻ Macros để tạo/sửa/xóa macro. Macro được gán vào phím bằng keycode M() trong thẻ Keymap.
  • Thẻ Quantum chỉnh giao diện kết nối cho các phím chia 2 nửa.
  • Thẻ Settings sửa thông tin tổng quát như tên phím, số bóng led gầm, số mức độ led nền.

B3: Xuất firmware từ thẻ Compile để flash vào phím

III. Hướng dẫn sử dụng website:

1/Wirings và Pins

  • Nếu ban đầu chọn upload file json hoặc load preset, có thể bỏ qua 2 mục này.
  • Nếu chọn tạo layout từ KLE, website sẽ tạo ra một sơ đồ mạch tượng trưng ( do khi import từ KLE chỉ load được số nút và vị trí nút trong layout, không có sơ đồ mạch ). Cần sử dụng 2 mục này để chỉnh lại sơ đồ mạch theo mong muốn
    • Wirings: chọn số hàng, cột trong sơ đồ mạch. Khi ấn chọn 1 nút, có thể tùy chỉnh nút này đấu vào hàng/cột bao nhiêu.
    • Pins: lựa chọn mỗi hàng, mỗi cột, đèn Numlock, đèn Capslock, dải led gầm,… nối vào chân ( Pins ) nào của chip điều khiển.

2/ Keymap:

Mục này để chính tính năng cho từng nút. Khi chọn một nút bất kỳ sẽ hiện ra keycode hiện tại của nút đó, vd KC_B, ấn vào keycode sẽ hiện ra giao diện chỉnh như sau:

Chọn layer ở trên cùng, bắt đầu từ 0.a/Thẻ Primary ngoài các tính năng thường thấy trong cụm 60% của bàn phím, còn bao gồm các chức năng sau:

  • NUHS: phím # trong layout ISO
  • NUBS: phím \| trong layout ISO
  • TRNS ( Transparent ). VD một phím ở layout 1 là B, layout 2 là TRNS. Khi giữ FN để chuyển layout 1 sang 2 và ấn phím đó vẫn sẽ ra B.
  • NO: bỏ qua, không có keymap.
  • RESET: đưa phím vào DFU mode để flash firmware.

b/Thẻ Secondary Keypad chứa các tính năng của cụm TKL, numpad, các chức năng media như chỉnh âm, chỉnh bài, tắt máy.c/Thẻ Lightning chứa các tính năng chỉnh led nền, led gầm:

  • 5 tính năng hàng 1 để chỉnh led nền: TOGG bật tắt; DEC/INC/STEP tăng giảm độ sáng, BRTG để bật/tắt chế độ breathing.
  • 6 tính năng hàng 2: tự động chỉnh màu led gầm sang 6 màu cho trước.
  • 10 tính năng hàng 3: TOG để bật/tắt, MOD để thay đổi hiệu ứng led gầm. Do QMK có tất cả 35 nấc hiệu ứng chia thành 8 loại nên có thêm 8 tính năng phía sau để nhảy nhanh đến từng loại đó.
  • 6 tính năng hàng 4: tăng giảm giá trị của led gầm RGB thủ công theo không gian màu H-S-V ( hình minh họa ):
    • HU=Hue: vùng màu chạy vòng tròn từ đỏ -> vàng -> xanh -> tím -> đỏ.
    • SA = Saturation: càng tăng thì màu càng đậm.
    • VA = Value: càng tăng thì màu càng sáng.
    • I = tăng, D = giảm.

d/ Thẻ FN là nơi tập hợp các tính năng keymap nâng cao:

  • Cụm từ LCTRL() tới ALTG(): áp nút modifier tương ứng vào keymap. VD muốn tạo keymap CTRL+C cần chọn LCTRL(), sau đó chọn tiếp nút C trong nhánh con. Cho phép lồng nhiều modifier, ví dụ muốn keymap CTRL+ALT+DEL thì mã tương ứng là LCTRL(LALT(KC_DEL)).
  • Cụm từ LT() tới MT() là các tính năng chuyển layer, giữ phím modifier:
    • MO(layer): FN đơn giản nhất, chuyển đến layer trong ngoặc khi giữ phím, chỉ cho phép đi lên layer ( vd có thể chạy MO(2) từ layer 1 nhưng không chạy được MO(1) từ layer 2 ). Lưu ý phím dùng chuyển layer phải đặt keymap TRNS trong layer đích, nếu không sẽ không thể về layer cũ khi nhả FN.
    • TG(layer): FN toggle, ấn 1 lần để chuyển layer, ấn lần 2 để về layer cũ. Cũng chỉ cho phép đi lên như MO.
    • LT(layer, key): FN dual mode, chuyển tới layer khi giữ, và gõ ra key khi ấn. Ví dụ LT(1, space) sẽ chuyển sang layer 1 khi giữ, còn gõ thường ra space. Chỉ cho phép đi lên layer.
    • TO(layer): đi đến một layer, đưa layer đó thành active. Cho phép đi lên hoặc xuống layer. VD có thể chạy TO(2) khi đang ở layer 4.
    • TT(layer): FN dual mode. Giữ phím này để chuyển sang layer, tương tự MO, nhưng gõ phím này ( mặc định 5 lần liên tiếp ) sẽ nhảy hẳn sang layer đó, tương tự TO.
    • DF(layer): đưa layer thành mặc định khi khởi động/cắm phím vào máy.
    • OSM(modifier): chuyển modifier cho 1 lần nhấn tiếp theo. VD nhấn ( không giữ ) OSM(Lshift) rồi nhấn b sẽ ra B, nhưng nhấn tiếp a sẽ chỉ ra a. Còn nếu giữ nút này thì vẫn ra Shift như bình thường. Tính năng này rất thích hợp với những ai ghét cảnh giữ Shift nhưng nhả nhanh hoặc chậm quá thành ra gõ Không lại ra không hoặc KHông.
    • MT(modifier, key): sẽ ra phím modifier khi giữ, và key khi nhấn. Ví dụ MT(LCTRL, CAPS) vào vị trí capslock thì gõ ra capslock nhưng capslock+A lại ra Ctrl+A. Mục modifier có thể giữ nhiều phím mod cùng lúc.
  • Cụm từ CTL_T() tới ALL_T() là một số phím tắt cho tính năng MT bên trên. Ví dụ CTL_T(KC_A) sẽ ra A khi nhấn, LCTRL khi giữ, LCAG_T(KC_A) ra A khi nhấn, ra đồng thời LCTRL ALT GUI(Win).
  • M(macro): Macro. Định nghĩa Macro từ thẻ macro sau đó gán số thứ tự vào keymap tại đây.
  • Tricky_ESC: phím ESC thông minh thường thấy trên các phím 60%: ấn ra ESC, còn Shift+ESC ra ~.

e/Thẻ OTHERS cho phép người dùng đánh trực tiếp keymap vào khung, phục vụ cho một số keymap mà website không hỗ trợ sẵn như OSL.Xem thêm các keymap nâng cao tại đây.

3/ Macros:

Nơi gán các chuỗi macro. Số lượng macro mà webstie hỗ trợ là không giới hạn, nhưng thực tế nếu gán quá nhiều macro + macro dài thì dễ xảy ra trường hợp controller hết bộ nhớ -> lỗi khi flash firmware.

  • Add action: thêm sự kiện như nhấn, giữ, nhả, chờ,..
  • Record macro: lưu lại những gì người dùng gõ ra cho đến khi ấn nút này một lần nữa để dừng ghi (Không lưu lại delay giữa các sự kiện, nếu cần thêm delay cần kết hợp với Add Macro).
  • Clear : xóa mọi sự kiện của macro này.

Sau khi hoàn tất tạo Macro, quay lại thẻ Keymap -> FN -> M() để gán macro đã tạo lên phím. Vd: Select a macro to modify đã chọn 1 thì ở bước sau gán M(1) vào vị trí mong muốn.

4/ Quantum:

Mục này dành cho các bàn phím dạng chia 2 nửa ( vd Lets Split ) cho phép code ma trận nhận tín hiệu giữa 2 phần bàn phím. Với bàn phím 1 cục thì bỏ qua.

5/ Settings:

Một số tùy chọn bổ sung như tên phím ( đây sẽ là tên của file config cũng như file firmware ), Bootloader size ( để mặc định 4096kb ), WS2182 LEDs ( số bóng led gầm RGB ), Backlight levels ( số mức độ sáng của led nền ).

  • Backlight level nên đặt từ 2 ( tắt và bật max sáng ) trở lên. Chỉ đặt 0 hoặc 1 sẽ khiến đèn luôn tắt hoặc luôn mở. 3 trở lên sẽ chêm vào các mức độ sáng trung gian ở giữa.
  • Trường hợp layout thiếu phím cơ bản, hay thiếu phím reset mềm, mục settings sẽ hiện lỗi như hình duới:

Cuối cùng, ấn nút Save Configuration để lưu lại toàn bộ thiết lập vào một file json để tái sử dụng sau này.

6/ Compile

Gồm 2 mục:

  • Download .hex để tải file firmware flash trực tiếp lên phím
  • Download .zip để tải về thư mục chứa mã nguồn, phục vụ chỉnh sửa thêm các tính năng nâng cao, sau đó từ folder này chạy lệnh MAKE để tạo ra file firmware .hex.

IV. Flash firmware vào phím

Sử dụng 1 trong 3 công cụ sau:

  1. QMK Toolbox, công cụ mì ăn liền All in One, hỗ trợ cả Mac ( file .zip ) và Win ( file .exe ).
  2. Atmel FLIP, công cụ chuyên dụng chỉ hỗ trợ Windows, hỗ trợ cả flash lẫn debug mạch Atmega trường hợp có lỗi.
  3. dfu-programmer , công cụ chuyên dụng hỗ trợ chủ yếu cho Mac và Linux, yêu cầu người dùng quen với các thao tác trong Terminal.

1/ Đưa phím vào DFU ( Device firmware update ) mode:

Đây là bước đầu tiên cần thực hiện khi muốn flash phím. Dựa vào loại mạch có thể sử dụng 1 trong 3 cách sau:

  • Ấn nút reset sau lưng mạch
  • Giữ Space+B sau đó cắm cáp usb vào phím
  • Ấn FN+Backspace hoặc FN+\| khi phím đang hoạt động.

Note:

  • Phím vào DFU thành công nếu ấn không còn ra ký tự.
  • Có thể cài đặt và sử dụng kết hợp các công cụ với nhau mà không làm ảnh hưởng gì đến hoạt động của phím.

2/ Sử dụng QMK Toolbox:

  • Bước 0: đưa phím vào DFU.
  • 1A: Ấn Open để trỏ đến file .hex chứa firmware đã download.
  • 1B ( bước phụ, Hỗ trợ trường hợp layout người dùng flash bị sai và cần load lại keymap gốc ): Tải file keymap từ kho của QMK: chọn tên mạch/bàn phím, chọn keymap ( đa phần chỉ kèm keymap default = mặc định ), sau đó ấn Load để tải về địa chỉ hiện lên trong cửa sổ chương trình ( VD C:\users\[tên user] \Downloads\tên firmware.hex ). Sau bước 1B vẫn cần sử dụng 1A để mở file .hex vừa tải.
  • 2: chọn tên controller ( đa phần mạch sử dụng atmega32u4 )
  • 3: Ấn Flash để flash file đã chọn vào phím, ấn Reset đưa phím về mặc định ( chỉ sử dụng với trường hợp flash lộn file )
  • Reset EEPROM: reset các giá trị Bootmagic của phím ( xem mục IV. Phụ lục )
  • List HID Devices: liệt kê danh sách các thiết bị trong DFU mode có thể flash. Nếu phím đã vào DFU, màn hình sẽ hiện thông báo dạng : DFU device connected: tên controller

3/ Sử dụng FLIP

  • Cài đặt FLIP vào máy.
  • Tắt chế độ tự động tìm và cập nhật driver trong Windows.
  • Đưa phím vào DFU mode như hướng dẫn ở trên, lúc này trong Device Manager sẽ hiện lên thiết bị Atmel USB Deviced -> ATmega32U4 ( hoặc tên khác tùy chip xử lý trên mạch ).
  • Chuột phải vào thiết bị này -> Update driver -> Browse My Computer… -> trỏ đến thư mục con USB trong thư mục cài FLIP -> OK. Đợi Windows cài driver.
  • Mở FLIP, chọn thẻ Settings -> Communication -> USB -> Open. Nếu đã hoàn tất các buớc trên, FLIP sẽ load thiết bị và hiện lên 4 chữ ký số ( với 32u4 là 58 1E 95 87 ). Chọn nút Load HEX file như trong hình:
  • Chọn file .hex và ấn Run để flash vào phím, sau đó rút phím ra cắm lại là sử dụng bình thường.
    • Với những lần flash tiếp theo chỉ cần đưa phím vào DFU mode và thực hiện từ buớc mở FLIP, bỏ qua phần cài driver.

#vnmk

4/ Sử dụng dfu-programmer

  • Yêu cầu cài đặt: máy tính nên cài đầy đủ các công cụ tại đây. Ngoài ra có thể cần thêm libusb ( sudo apt-get install libusb-dev với linux/ubuntu ; brew install libusb với Mac )
  • Hướng dẫn cài đặt tự động từ terminal: trên Ubuntu/Debian: sudo apt-get install dfu-programmer ; trên Mac:brew install dfu-programmer ( với máy đã cài Homebrew )
  • Hướng dẫn cài đặt thủ công: đi kèm file README, cơ bản yêu cầu chạy 4 lệnh ./bootstrap.sh , ./configure , MAKE , sudo MAKE Install từ folder đã giải nén. Cài đặt thành công khi chạy được lệnh dfu-programmer từ terminal.
  • Hướng dẫn flash phím:
    • Đưa phím vào DFU mode
    • Mở Terminal, chạy lệnh sudo sudo dfu-programmer [tên chip] erase để xóa firmware hiện tại trên phím. Với các mạch/phím đã giới thiệu ở đầu bài đều dùng chip atmega32u4.
    • Gõ tiếp lệnh sudo dfu-programmer [tên chip] flash [đường dẫn tới file .hex] để flash firmware mới.
    • Gõ lệnh sudo dfu-programmer [tên chip] reset để hoàn tất.
    • Hình minh họa flash 1 phím dùng chip atmega32u4 như dưới:

V. Phụ lục: Bootmagic

Một tính năng của QMK giúp thay đổi nhanh vị trí một số phím, đưa phím vào DFU,… mà không cần flash file keymap mới, tương tự như DIP switch cứng thường thấy trên bàn phím Leopold, Filco, Ducky, Poker,…Mặc định các lệnh Bootmagic được thực hiện bằng cách giữ tổ hợp phím Space+phím tương ứng sau đó cắm cáp USB vào phím ( các lệnh này sẽ không chạy nếu ấn tổ hợp sau khi phím đã được nhận diện bởi máy tính ). Các lệnh bao gồm:

  • Space+Esc: đọc giá trị mặc định của Bootmagic
  • Space+Backspace: reset bootmagic về mặc định
  • Space+B: đi vào DFU mode
  • Space+LCtrl : đảo vị trí Ctrl trái và Capslock
  • Space+Capslock: gán Capslock thành control
  • Space+LAlt: đảo vị trí Win trái và Alt trái
  • Space+RAlt: đảo vị trí Win phải và Alt phải
  • Space+LGUI(Win trái): disable Win trái
  • Space+ ` : đảo vị trí ` và Esc
  • Space+\|: đảo vị trí \| và Backspace
  • Space+N: chuyển đổi giữa 6KRO và NKRO
  • Space+số từ 0 đến 9: gán layer từ 0 đến 9 làm layer mặc định

Trường hợp phím có vấn đề ( một số phím bị đảo/tắt, layer nhảy,.. ), bước đầu tiên là reset bootmagic bằng tổ hợp Space+Backspace sau đó Space+Esc nếu vẫn lỗi.

Tác giả: Trương Đình Nho _ VNMK

Trả lời

Email của bạn sẽ không được hiển thị công khai.