
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/<model> 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

