Troubleshooting Firmware Upload Issues

While in most cases uploading new firmware to your Model 01 or Model 100 is a simple and straightforward process, sometimes things don't work as well as they should. This page tracks and provides solutions to issues that you may experience. If the information here does not solve your issue, please reach out the Keyboardio Community in the Help and Getting Started category.

General Troubleshooting

Turn on Verbose Upload Output

Turning on Verbose output can assist you in determining any issues. To do this, in the Arduino IDE, open the Preferences dialog either from the menu, File > Preferences, or by typing Ctrl+Comma. On the "Settings" tab of the Preferences dialog window, there is an option labeled "Show verbose output during:". Check the "upload" checkbox for that option. Click OK to save the setting change and close the Preferences dialog.

Reboot the keyboard into its bootloader

Arduino doesn't know how to reboot the Model 100 into its bootloader. For now, if you want to use the IDE, you need to hold down Prog while plugging in the keyboard to put it in bootloader mode.

Issue: Upload Does Not Complete in Time

One of the most common, and simplest to resolve issues is that the bootloader times out before the Arduino IDE is able to make a connection to it during the Upload process. When you hold down te prog key, the Model 01 goes into bootloader mode, but for only about 8 seconds. After that it reverts back to its "just a keyboard" state. There are a few potential causes for this and corresponding things we can do to mitigate them.

When you click the Upload function, the Arduino IDE first compiles and then uploads the built binary to the Model 01. However, it needs to start the "uploading" phase before the Model 01 bootloader connection times out. If it does not, the upload will fail. For a variety of reasons -- a slow system, resource constraints, a complicated sketch, etc. -- the "compiling" phase can dramatically extend the total time it takes for the full Upload process ("Compiling" then "Uploading") to complete.

Mitigation Suggestions

Always Verify First

Always run Verify (The check-mark button) before you run Upload. While the Upload process does compile the sketch, it will run faster if you first do a Verify.

Just try a Second Time

Often, just running the Upload process a second time is all it takes to get a successful upload. But if you have to continually do this, then try some of the other Mitigation Suggestions provided.

Delay pushing the prog button

Ultimately, the prog button on your Model 01 needs to be pushed (and held in) before the "Uploading" phase of the full Upload process. If you wait until the "Compiling" phase is partially or nearly complete before you press and hold the prog button, you can help to ensure that the Model 01 does not timeout of the bootloader mode before it begins the "Uploading" phase. When you run the Upload process, you will see a status message on the left side of the teal bar that separates the top white editor section and black output console of the Arduino IDE. During the Upload process, the message will first say "Compiling Sketch...". Once the "Compiling" phase completes, it will switch to "Uploading...". During the "Compiling" phase, there will also be a progress bar on the right side of the teal separation bar. You can use this progress bar to wait until the "Compiling Phase" is near completion before pressing and holding the prog button. It is important however that you do push and hold it before the "Uploading..." phase starts. Sometimes the Progress Bar may only proceed to about ½ way, hold for a moment, and then jump to completion. Usually after a few attempts, you will get a feel for the timing on your system with your sketch. Alternatively, just use the Release and Repress mitigation below.

Release and Repress the prog Button Every 8 Seconds

After initially pressing the prog button, either use a clock/timer or count the seconds using a second long placeholder word to track the duration. Every 7 or 8 seconds, quickly release and repress the prog button. This method has been successfully used many time. The process works fine as long as you are not in a "release and repress" cycle (which likely only takes a ¼-½ second) at the very instance the Upload process switches from its "Compiling" phase to its "Uploading" phase. And if that happens, just wait for the process to fail and then do it again.

Upload the Firmware Using the Command Line

While the above mitigation suggestions work most of the time, an alternative and almost surefire way to deal with the timing issue is to upload the firmware via the command line. This breaks the Upload process into two distinct steps -- creating the binary and then uploading it -- rather than a single combined process.

• Command Line Upload Instructions for Windows
• Command Line Upload Instructions for Mac PENDING
• Command Line Upload Instructions for Linux PENDING

Issue: Help, I bricked my Model01 with bad firmware!

First of all: do not worry! It is very hard to completely brick a Model01!

If you managed to flash a firmware that does not function properly, which prevents you from flashing the normal way, that's no problem: there's a way to flash still, and it requires no extra hardware, nor disassembly, nor anything drastic like that!

Take a known-good firmware, like the factory one, or go back to a version of your sketch that used to work. Compile it, if you have to, but before flashing it the usual way, pull the keyboard out from the computer. Before plugging it back in, press and hold the PROG key, and continue holding it even after you plugged the board back. Then, flash it as per usual.

The trick here is that the boot loader of the Model01 is set up in such a way that if it detects PROG being held when the board is plugged in, it will not load the firmware flashed onto it. This way, a buggy firmware can't crash, can't prevent you from entering programming mode. Therefore, you can flash a known-good firmware, and start figuring out what caused the issue.

If this method still does not work, you still don't have to panic: there are other ways to fix your keyboard. There's a reset button hidden below the enclosure, for example. You can press that at any time to reboot into the bootloader, you don't have to hold it either.

As long as you can put the keyboard into programmable mode, you can fix any bad firmware you may have flashed.