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.h
configuration 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 held to trigger bootloader entry on boot.
See https://github.com/xyzz/stm32f103-keyboard-bootloader#adding-a-new-keyboard for an explanation.
*/
#define BL_OUTPUT_BANK GPIOB
#define BL_OUTPUT_PIN 12
#define BL_INPUT_BANK GPIOB
#define BL_INPUT_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 thevibl
bootloader(example):
MCU = STM32F103
BOOTLOADER = vibl
- In your
vial.json
file, enable thevibl
feature(example):
"vial": {
"vibl": true
}
- Compile your keyboard firmware as usual with
make mykeyboard:via
; now the build process will produce a.vfw
file 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 |