vibl: a driverless keyboard bootloader that integrates with Vial GUI.
Currently, implementations are available for:
- STM32F103 (based on bootsector/stm32-hid-bootloader)
-
Add a new line in CMakeLists.txt for your keyboard, e.g.
add_bootloader(mykeyboard) -
Add a new option in the
bootloader/src/config.hconfiguration file for your keyboard before the final "else" statement:
#elif defined(TARGET_MYKEYBOARD)
/*
This should match the UID you have configured in the Vial firmware
See Vial porting docs for more info: https://vial-kb.github.io/gettingStarted/porting-to-vial.html
*/
#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}
/*
These configure an emergency key which triggers bootloader entry when it is held during boot.
The definitions match a typical QMK COL2ROW setup. If you use a ROW2COL setup, switch around ROW and COL in the defines below.
*/
#define BL_COL_BANK GPIOB
#define BL_COL_PIN 12
#define BL_ROW_BANK GPIOB
#define BL_ROW_PIN 13- Compile the bootloader
cd bootloader
mkdir build && cd build
cmake ..
make
This should produce a bootloader-mykeyboard.bin file.
- Flash and write-protect the bootloader
In order to program option bytes, you should use a fork of stlink. Once you compile it, flash the bootloader with:
st-flash opterase
st-flash write ../../misc/opt-head.bin 0x1FFFF800
st-flash write bootloader-mykeyboard.bin 0x8000000
st-flash write ../../misc/opt-tail.bin 0x1FFFF802
st-flash --area=option read
You should confirm that the final command produces the following output:
A5 5A FF 00 FF 00 FF 00 FE 01 FF 00 FF 00 FF 00
FE 01 indicates that the first block of 0x1000 bytes is write-protected.
Power-cycle the device and confirm it boots into the bootloader:
[1737747.221873] usb 1-5.2: new full-speed USB device number 8 using xhci_hcd
[1737747.468303] usb 1-5.2: New USB device found, idVendor=1234, idProduct=5678, bcdDevice= 0.01
[1737747.468306] usb 1-5.2: New USB device strings: Mfr=1, Product=1, SerialNumber=2
[1737747.468307] usb 1-5.2: Product: vibl-HIDUSB
[1737747.468308] usb 1-5.2: Manufacturer: vibl-HIDUSB
[1737747.468309] usb 1-5.2: SerialNumber: vibl:d4f8159c
- In your keyboard
rules.mk, enable theviblbootloader(example):
MCU = STM32F103
BOOTLOADER = vibl
- In your
vial.jsonfile, enable theviblfeature(example):
"vial": {
"vibl": true
}
- Compile your keyboard firmware as usual with
make mykeyboard:via; now the build process will produce a.vfwfile in addition to the.bin:
Compiling: quantum/via.c [OK]
Compiling: tmk_core/common/command.c [OK]
Linking: .build/vial_test_via.elf [OK]
Creating binary load file for flashing: .build/vial_test_via.bin [OK]
--------------------------------------------------------------------------------
Vial update package created at vial_test_via.vfw
--------------------------------------------------------------------------------
Creating load file for flashing: .build/vial_test_via.hex [OK]
Size after:
text data bss dec hex filename
0 30934 0 30934 78d6 .build/vial_test_via.hex
Copying vial_test_via.bin to qmk_firmware folder [OK]
(Firmware size check does not yet support cortex-m3 microprocessors; skipping.)
At that point you should be able to open Vial GUI, have the bootloader auto-detected and flash your firmware package. Further, after flashing such firmware for the first time, the update process can also be performed without having to manually restart in bootloader mode.
Firmware updater when keyboard is in bootloader mode |
Firmware updater when keyboard is running vial-qmk firmware |
- Verify the emergency key download is working
Make sure to test that you configured the emergency bootloader key correctly by holding it down while plugging in the keyboard. Review and correct your vibl configuration if the keyboard does not start in bootloader mode when the key is held.