## Safety switch

Now that we are fairly confident that (1) the compiler works, (2) it
produces code for our processor, (3) the resulting binary does not
contain any unwanted code; we’d like to build something that will run on
the actual hardware. But first we want to make sure we can go back to a
working firmware, or to flash a different program.

The stock firmware does this by handling a special USB request, upon
receiving which it reboots in ISP DFU mode. But our experimental
programs will not have USB handling until much later.

So we will establish a rule: In any unfamiliar situation, reboot to ISP.

And, in the beginning, every situation is unfamiliar.

So let’s write a function to reboot to ISP, and call it immediately upon
entering `main`.
Flashing our first program

We now want to test our first program. It should start up and
immediately reboot the device† into the bootloader.

† Which, for the time being, is no longer a keyboard, as it temporarily
loses the ability of reporting key presses to the host system.

To update the firmware code, we are supposed to use either the Truly
Ergonomic DFU tool, or the generic DFU tool from the [Megawin
MG84FL54BD][MG84FL54BD] SDK. They are functionally identical, it’s just
the logo that differs.

[MG84FL54BD]: http://www.megawin.com.tw/megawin_EN/ProductShow.asp?ID=175

Unfortunately, we can’t just run them under Wine, as it does not
emulate/bridge USB access yet. And I don’t feel like setting up a
separate Windows PC just to tinker with a keyboard.

Luckily, [VirtualBox][], with the Extension Pack installed, gives the
guest system access to USB devices. So install VirtualBox and the
Extension Pack, set up Windows inside it, and install Guest
Additions. (Additions, among other features, gives mouse pointer
integration, better video support, and shared folders.)

[VirtualBox]: https://www.virtualbox.org/

Inside the guest Windows, we need to create a directory and unpack the
Truly Ergonomic DFU tool in it. We will also set up a Shared Folder so
that our compiled program is available to the Windows VM. Copy the
`main.ihx` file into the directory with the DFU tool, and rename it
`reboot.hex`.

The DFU tool operates like this:

* You tell it to load a firmware (point to a .hex file) and then to
  Upgrade.
* It tries to find an attached USB device with the IDs of Truly
  Ergonomic Keyboard in DFU mode (VID 0E6A, PID 030B).
* If none such device is attached, it finds a Truly Ergonomic Keyboard
  in its normal mode (PID 030), sends to it a request to reboot in
  DFU mode and waits until it does.
* In both cases, when a device with PID 030B is found, the DFU tool
  sends it a series of requests transmitting the firmware code, and
  finally directs it to reboot back in application mode.

In order for this to work from within VirtualBox, we need to connect the
keyboard to the virtual machine before clicking Upgrade. We do this by
right-clicking the USB connector icon on the bottom of the VirtualBox
window and selecting Truly Ergonomic Keyboard from the popup menu. This
may be tricky if you have two identical keyboards attached. So I first
disconnect my main keyboard (or just switch off its port on my USB hub),
leaving only the test device attached. Fortunately, the DFU tool can be
operated using only the mouse.

Note that the keyboard has a protection DIP switch on its bottom. If set
to ON, the keyboard will not reboot in DFU mode when requested. So set
it to OFF on your test subject device and leave ON on the workhorse.

When the DFU tool reboots the keyboard in DFU mode, it is no longer
connected to the VM. We could connect it again using the popup menu, but
that gets tedious very quickly. Luckily, VirtualBox lets us set up a
filter that will always connect devices satisfying its conditions.

Open the Machine menu and click Settings. On the USB tab, click the
button with the plus sign. A menu pops up, listing your devices that can
be connected. Select the one that says Unknown device, Vendor ID 0E6A,
Product ID 030B. A filter will be created. Click OK.

Now, the DFU tool probably has already timed out waiting for the device.
Cycle the power to the keyboard. Connect it to the VM. Click Upgrade
again. This time, the filter will kick in and automatically connect the
keyboard (which has rebooted in the DFU mode). The DFU tool will notice
that and send it the new firmware. Then the keyboard will reboot with
the new firmware. Which, as you remember, automatically and immediately
reboots back to the DFU mode. The filter will again kick in and connect
it to the VM. You can check that this happened by right-clicking the USB
connector icon and seeing that the Unknown device (VID 0E6A, PID 030B)
is checked.

If you like to keep your spare in working condition, you can now reflash
the original firmware. This time, the device is already in DFU mode and
connected to the VM, so just load the .hex file and click Upgrade.