Keyboardio Model100 custom-firmware notes

I am typing this on my new Keyboardio Model100!  Setup was a bit rocky; hopefully these notes will help you!

What worked (try 3)

Setup prerequisites

1. Add udev rules for the Model100 per https://community.keyboard.io/t/model-100-firmware-update-to-fix-corruption-issues/5553/9 .
   • chown root:root the new rules file or it won’t be used (ask me how I know! 😉 )
2. Install the latest dfu-util from source
   • Clone per instructions at https://dfu-util.sourceforge.net/
   • ./autogen.sh && ./configure && make -j
3. Confirm that the keyboard is accessible:
   1. Hold prog while plugging in the keyboard
   2. Run ./src/dfu-util -lv and make sure Model 100 (bootloader) appears
4. Install the latest firmware using Chrysalis per https://community.keyboard.io/t/model-100-firmware-update-to-fix-corruption-issues/5553

Setup Chrysalis-Firmware-Bundle

1. Clone https://github.com/keyboardio/Chrysalis-Firmware-Bundle and cd into the clone dir.
2. Run ./tools/bootstrap.  This will create .arduino/ and .kaleidoscope/ and download lots of files into them.
3. export KALEIDOSCOPE_DIR="$(realpath .kaleidoscope/)"
4. export ARDUINO_DIRECTORIES_USER="$(realpath .kaleidoscope/.arduino/user)"
5. make -C .kaleidoscope setup

Build the firmware

1. make Keyboardio/Model100 VERBOSE=1.  This should leave output in output/Keyboardio/Model100/default.bin.
2. Unplug the Model100, hold Prog, and plug the Model100 back in.  The prog key should light steady red.
3. Run dfu-util -d 3496:0005 -D ./output/Keyboardio/Model100/default.bin -R — use your locally-built dfu-util.  You should see something like the below “Sample dfu-util output”.  The first column of keys will cycle green while this is happening.
4. When the programming is done, the keyboard should reset.  If it doesn’t, unplug and replug it.

Sample dfu-util output

dfu-util 0.11-dev
...
dfu-util: Warning: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release
Opening DFU capable USB device...
Device ID 3496:0005
...
Copying data from PC to DFU device
Download [=========================] 100% 167104 bytes
Download done.
DFU state(7) = dfuMANIFEST, status(0) = No error condition is present
DFU state(2) = dfuIDLE, status(0) = No error condition is present
Done!
Resetting USB to switch back to Run-Time mode
dfu-util: error resetting after download: LIBUSB_ERROR_OTHER

Customizing the firmware

1. Edit Keyboardio/Model100/Model100.ino.  Example.
2. Run the “Build the firmware” steps from above.

Try 1 (didn’t work)

1. Add udev rules for the Model100 per https://community.keyboard.io/t/model-100-firmware-update-to-fix-corruption-issues/5553/9 .
   • chown root:root the new rules file or it won’t be used (ask me how I know! 😉 )
2. Install the latest dfu-util from source
   • Clone per instructions at https://dfu-util.sourceforge.net/
   • ./autogen.sh && ./configure && make -j
3. Confirm that the keyboard is accessible:
   1. Hold prog while plugging in the keyboard
   2. Run ./src/dfu-util -lv and make sure Model 100 (bootloader) appears
4. Install the latest firmware using Chrysalis per https://community.keyboard.io/t/model-100-firmware-update-to-fix-corruption-issues/5553
5. Update the Arduino keyboard defs:
   1. Tools | Boards | Board manager
   2. Select Type: Updateable in the upper-left
   3. click on Keyboardio, then Update
   4. In the top-right box, search for Model 100 (with a space)
   5. Click on the result and select Install
6. Fork https://github.com/keyboardio/Chrysalis-Firmware-Bundle .  Clone and create a dev branch.
7. In the dev branch, `git checkout 50a7fbb`.  This is to prevent a compile error (reported here).
8. In the Arduino IDE, open the Model100 firmware from your clone of Chrysalis-Firmware-Bundle/Keyboardio/Model100/Model100.ino
9. Build:
   1. Tools | Board | Kaleidoscope Keyboards (2021+) | Keyboardio Model 100
   2. Sketch | Verify/Compile
10. Upload: When I try to upload, I get an error because the bundled dfu-util needs glibc 2.34, which my dev machine does not currently have.  Therefore:
    1. Sketch | Upload
    2. Copy the dfu-util command line from the error window
    3. Unplug the keyboard, then plug it back in while holding prog
    4. Run the dfu-util command using my built-from-source dfu-util

Unfortunately, the result is a nonfunctional keyboard!  The led key’s LED breathes green briefly but the keyboard is otherwise inert (although does show as USB-connected).  I am able to use Chrysalis to get back to factory firmware, however.

Try 2 (didn’t work)

1. Remove my old ~/.arduino15/
2. Download Arduino 1.8.19 tarball from https://www.arduino.cc/en/software
3. Untar it
4. Run cd arduino-1.8.19 && ./install.sh.
5. Run the IDE
6. File | Preferences, and add https://raw.githubusercontent.com/keyboardio/boardsmanager/master/package_keyboardio_index.json as an additional board manager URL (ref.)
7. Tools | Board | Board manager
8. Search for Keyboardio
9. Install the Kaleidoscope Keyboards (GD32) bundle (takes a while)
10. Fix a warning: cd ~/.arduino15/packages/keyboardio/hardware/gd32/1.99.7/libraries/Kaleidoscope-LEDControl && ln -s ../Kaleidoscope/src/Kaleidoscope-LEDControl.h .
11. Add the built-from-src dfu-util: cp ~/src/dfu-util/src/dfu-{prefix,suffix,util} ~/.arduino15/packages/keyboardio/tools/dfu-util/0.11.0-arduino3/
12. In the IDE, Tools | Board | Kaleidoscope Keyboards (2021+) | Keyboardio Model 100
13. In the IDE, File | Examples | Kaleidoscope | Devices | Keyboardio | Model 100
14. In the IDE, Sketch | Verify/Compile
15. Unplug the Model100, then hold Prog and plug it back in.  Prog should light steady red.
16. In the IDE, Sketch | Upload