(post
 :title "Upgrading the TEK’s firmware on GNU/Linux"
 :date (string->date* "2014-11-23 00:00")
 :tags '("keyboard" "virtualbox")

 (p [I’m using the Truly Ergonomic Keyboard (model 209) for most of my
     typing, because it’s a pretty comfortable keyboard (when it
     works).  One of the greatest features of this keyboard is that the
     layout can be customised and flashed to the hardware with a
     firmware upgrade.  Unfortunately, the application used to flash
     the firmware is only available for Microsoft Windows.])
 
 (p [As a GNU/Linux user I find this to be very inconvenient.  I
     simply don’t have access to a machine running Microsoft Windows
     (not even at the office).  Luckily, Microsoft provides ,(ref
     "http://modern.ie" "free virtual machine images") of various
     versions of their operating system for browser evaluation
     purposes.  I occasionally use them to verify that a web page
     works all right in the proprietary and often quirky Microsoft
     browsers.  Although these images could be used in KVM, converting
     and tweaking them takes a little too long and is a bit annoying.
     For the quickest results these images should be imported with
     Virtual Box instead.])
 
 (p [Truly Ergonomic recommends not to use virtualisation software to
     update the firmware of the keyboard, but as I was out of other
     options I decided to give it a try anyway.  You probably should
     not be doing this if you don’t feel you would be able to perform a
     ,(ref
     "https://www.trulyergonomic.com/store/troubleshooting--truly-ergonomic-mechanical-keyboard#Reset"
     "manual reset") of the controller in case something goes wrong.])
 
 (h2 [Preparation])
 
 (ul
  (li [a recent version of Virtual Box])
  (li [a virtual machine image of Microsoft Windows])
 
  (li [a user account that is a member of the group ,(code
       [vboxusers]); required to access any host USB devices from
       within a Virtual Box machine.  If you have just added your
       account to this group, remember that you need to log off and on
       again before the changes come into effect.])
 
  (li [enable USB 2.0 support, provided by the ,(em [Oracle VM
       VirtualBox Extension Pack]).  The extension pack has to be
       installed through the preferences menu in the VirtualBox client.
       Note that you may have to run the client as root to have
       sufficient permissions to install the extension pack.])
 
  (li [a USB device filter configured to pass host USB devices through
       to the virtual machine]))
 
 (p [If everything is set up properly you should be able to forward USB
     devices from the host system to the virtual machine.  Try setting
     up a USB device filter in the USB settings menu of the virtual
     machine.  You should be able to create a filter for the Truly
     Ergonomic Keyboard right there.  If you cannot see a list of USB
     devices at all at this point check that your user account is a
     member of the group ,(code [vboxusers]).])
 
 
 (h2 [Performing the upgrade])
 
 (p [Inside the Windows machine start the official firmware upgrade
     tool, load the firmware you want to flash to the keyboard, and
     click on ,(em [Upgrade]).  This will result in an error message,
     but that’s okay: don’t panic!  The reason why this error occurs is
     that the USB identifier of the keyboard will have changed from
     something like this:])
 
 (pre (code [ID 0e6a:030c Megawin Technology Co., Ltd Truly Ergonomic Computer Keyboard]))
 
 (p [to something like this:])
 
 (pre (code [ID 0e6a:030b Megawin Technology Co., Ltd Truly Ergonomic Computer Keyboard (Device Firmware Update mode)]))
 
 (p [Since the USB identifier has changed, VirtualBox may no longer
     forward this device from the host to the virtual machine guest
     system.  All you have to do is add a filter for this new USB
     device in the guest settings and resume the upgrade by clicking on
     ,(em [Upgrade]) again.  This will again lead to another error, but
     I found that by that time the upgrade has already been performed
     successfully.])
 
 (p [Note that while the USB device is being forwarded to the guest
     system you cannot use it in the host.  To test if the new firmware
     works as expected in your system, disable the USB filters in the
     guest settings.])
 
 
 (h2 [Next steps])
 
 (p [It should also be possible to flash the firmware directly from a
     GNU/Linux system.  I suppose one could sniff the USB communication
     and build a little tool that performs the upgrade natively on
     GNU/Linux.]))