Quick start guide for Model F Labs "New Model Fxx" Vial firmware ---------------------------------------------------------------- This firmware covers most Model F Labs LLC keyboard models (inclusive of "Model F" and "Model B") released to-date that use the wcass variant of the xwhatsit USB controller. It incorporates pandrew's capsense implementation for QMK, and is based on Vial version 0.4.1. The Vial utility is backwards-compatible with older Vial firmwares (newer versions of the utility can configure keyboards running older Vial firmware releases), so you should be able to download and run the latest version of the Vial utility from https://get.vial.today/ or use the online web-based configuration utility located at https://vial.rocks/ in order to configure your keyboard once it is running this firmware. The following is a complete list of currently supported models: * F62 (excepting "scumyc" variant) * F77 * F50 * F104 revision 1** * F104 revision 2 * FSSK revision 1 * FSSK revision 2 * F15 split * FOrtho ergonomic * B62 * BSSK revision 1 * BSSK revision 2 * B104 revision 1*** **note1: there are two minor variants of F104 rev1; if you flash "f104" firmware to your rev1 board and discover that the Caps Lock and Scroll Lock LEDs are swapped, then re-flash with "f104_ns" instead ***note2: B104 rev2 uses a different controller and this firmware is not compatible with this keyboard; please consult Model F Labs LLC to obtain firmware appropriate to this keyboard model -------- FLASHING -------- If you are just interested in the already-compiled firmware, and want to flash it to your keyboard, either to replace a different firmware (such as original xwhatsit, QMK, or VIA) or to upgrade from an older version of Vial firmware, follow these steps: 1. Run the "link-flash-scripts.bat" (Windows) or "link-flash-scripts.sh" (Mac or other UNIX) 2. Navigate to the flash-scripts/ directory representing your keyboard model 3. Run the corresponding .bat (Windows) or .sh (Mac/UNIX) script file for your preferred stock layout 4. If the given layout doesn't suit your exact preferences, run Vial after flashing and adjust to taste Your keyboard controller will need to be put into bootloader mode before the flash can proceed; if it isn't already in bootloader mode when you run the script, then the script will wait until you have successfully put it into bootloader mode, so you will know for sure if you have been successful. Bootloader mode can be achieved in one of the following ways: 1. Run the pandrew-util, and click the "Enter Bootloader" button 2. Run Vial, and go to Security > "Reboot to bootloader" 3. Press the key on your keyboard mapped to the "RESET" function (reboot the controller into DFU/bootloader mode), if you have one 4. Physically short the two pads marked "PROG" on the controller while plugging the USB cable into the host PC 5. If the controller flash is blanked/empty, it will enter bootloader mode automatically upon being plugged in (Other non-Vial firmwares may provide other options for putting the controller into bootloader mode; consult the applicable documentation for details and instructions.) If you have a split ergonomic model, each half is seen by the host computer as a discrete keyboard, and you will need to flash each half separately. The two firmwares for the two halves are suffixed with "_l" and "_r" for Left and Right, respectively. Put the left half into bootloader mode, run the "_l" flash script for your particular model, then repeat for the right half with the matching "_r" flash script. If you want to flash from a Linux host, then from the root of this expanded archive's directory, you will need to... 1. Install a proper "dfu-programmer" for your particular Linux distribution; e.g., "yum install dfu-programmer" (on Fedora / CentOS / derivatives) "apt install dfu-programmer" (on Debian / Ubuntu / derivatives) 2. rm flash-util/dfu-programmer (removes existing symlink to included pre-built MacOS dfu-programmer binary) 3. ln -s dfu-programmer.stock flash-util/dfu-programmer (makes new symlink to stock/system dfu-programmer shim) -------- BUILDING -------- If you want to build the firmware from source, then on a Linux or Mac host, perform the following steps: 1. Follow the QMK "Setting Up Your QMK Environment" document at http://github.com/qmk/qmk_firmware/blob/master/docs/newbs_getting_started.md to prepare your build environment 2. Run the "build.sh" script in the root of this archive Upon successful compilation, the resulting .hex files will be placed in the firmwares/ directory of wherever you expanded the contents of this archive to. The build machine will need to be internet-connected as it will need to pull down build dependencies from various online sources. The firmware is assembled from a mish-mash of pandrew's private QMK fork, a backleveled version of the Vial sources from their public Github (roughly equal to Vial version 0.4.1), and various custom patches included with this archive. If you want to build on Windows, in theory it should be possible, but doing so is left as an exercise for the reader. Assuming you have successfully set up a stock QMK build environment on Windows that is tested working, a quick study of the build.sh script should make it fairly obvious what one would need to do in order to build this particular firmware. ------- KEYMAPS ------- You can of course configure your keyboard to adhere to your preferred layout and keymap all to your heart's content using Vial, but for your convenience, there are various pre-defined stock keymaps included for you to choose from for each keyboard model. You can either use these as-is, or use one as the starting point for building your own custom keymap without starting completely from scratch. If there is a particular keymap or layout which isn't included here but that proves to be popular within the community of New Model F owners for a given model, please feel free to reach out to see about having it included in a future release of this package. Keymap files are distributed in two different formats: * .vil files are Vial layout exports * .hex files are keyboard controller EEPROM dumps The "hex" versions of the keymaps are what can be programmed into the keyboard during the initial firmware flash process. The Atmel chip used as the "brains" of the xwhatsit capacitive USB controller variants has two different forms of nonvolatile memory: flash and EEPROM. Flash memory is where executable code -- such as the firmware -- is stored. EEPROM is where persistent but malleable data that the firmware needs to consult -- such as the keyboard layout -- is stored. During programming, the hex file from the firmware/ directory for your particular keyboard model is written to flash, and the hex file from the keymaps/ directory for the given keymap+layout that you chose is written to EEPROM. The "vil" versions of the keymaps are what can be loaded into the keyboard EEPROM without having to resort to a full re-flash of the firmware; these are included because the Vial utility does not itself understand the format of the raw EEPROM dump. If you wish to change from whatever keymap you are currently using to one of the other included stock keymaps, simply run the Vial utility, go to File > "Load saved layout...", and select the desired vil file corresponding to the keymap you wish to use. Your keyboard will be instantly reprogrammed with the new keymap+layout. Explanation of keymap naming legend: The combined keymap+layout names follow this convention: base_modifier1_modifier2_[...]_modifierN ...where... * base is either 'ansi' or 'iso': * ansi uses an ANSI Enter, and non-split left shift * iso uses an ISO Enter, and a split left shift * modifiers are strung together to explain the deviation from the base; each of the below modifier groups are mutually-exclusive: * fn / hhshift / hhkb: * fn means: split right shift (HHKB-style), with rightmost 1U key being mapped to Fn * hhshift means: as above, but also Caps Lock and Left Ctrl are swapped relative to ANSI * hhkb means: as above, but "full HHKB" (backspace is moved down a row to replace 1.5U backslash, original backspace is split) * optN: for F77, refers to the right-side block layout option, where N is from 1 to 5, as described by Model F Labs * nlock / simulock: * nlock means: enables the Num Lock layer 1 selection feature * simulock means: "simulated" Num Lock (used on F77 only) So for example, "f77-ansi_fn_opt3_nlock" would be an F77 layout based on ANSI, with HHKB-style split right shift, right block option #3, implemented with the Num Lock based layer switching feature. ------- CREDITS ------- Hardware: Model F and Model B reproduction boards manufactured by Model F Labs LLC https://www.modelfkeyboards.com/ xwhatsit USB capsense controller design by Tom Wong-Cornall http://downloads.cornall.co/ibm-capsense-usb-web/ibm-capsense-usb.html xwhatsit controller design updated by "wcass" @ Deskthority https://deskthority.net/viewtopic.php?p=299133 Software: Vial GUI is (C) Ilya Zhuravlev Licensed under terms of GNU General Public License version 2 Vial firmware is forked from QMK and VIA https://get.vial.today/ QMK capacitive matrix implementation is (C) Purdea Andrei http://purdea.ro/ VIA is (C) Olivia and the VIA Team https://www.caniusevia.com/ QMK is (C) Quantum Mechanical Keyboard Firmware project https://qmk.fm/ QMK is forked from TMK, which is (C) Jun "Hasu" Wako Licensed under terms of GNU General Public License version 2 https://github.com/tmk -- Edited, assembled, and packaged by Nathan Anderson release 5.1, 21 February 2024