posts: add diagram for shared Guix profiles and store
[software/elephly-net.git] / posts / 2014-11-23-upgrading-trulyergonomic-firmware.markdown
1 ---
2 title: Upgrading the TEK's firmware on GNU/Linux
3 date: 2014/11/23
4 tags: keyboard, virtualbox
5 ---
6
7 I'm using the Truly Ergonomic Keyboard (model 209) for most of my
8 typing, because it's a pretty comfortable keyboard (when it works).
9 One of the greatest features of this keyboard is that the layout can
10 be customised and flashed to the hardware with a firmware upgrade.
11 Unfortunately, the application used to flash the firmware is only
12 available for Microsoft Windows.
13
14 As a GNU/Linux user I find this to be very inconvenient. I simply
15 don't have access to a machine running Microsoft Windows (not even at
16 the office). Luckily, Microsoft provides
17 [free virtual machine images](http://modern.ie) of various versions of
18 their operating system for browser evaluation purposes. I
19 occasionally use them to verify that a web page works all right in the
20 proprietary and often quirky Microsoft browsers. Although these
21 images could be used in KVM, converting and tweaking them takes a
22 little too long and is a bit annoying. For the quickest results these
23 images should be imported with Virtual Box instead.
24
25 Truly Ergonomic recommends not to use virtualisation software to
26 update the firmware of the keyboard, but as I was out of other options
27 I decided to give it a try anyway. You probably should not be doing
28 this if you don't feel you would be able to perform a
29 [manual reset](https://www.trulyergonomic.com/store/troubleshooting--truly-ergonomic-mechanical-keyboard#Reset)
30 of the controller in case something goes wrong.
31
32 ## Preparation
33
34 - a recent version of Virtual Box
35 - a virtual machine image of Microsoft Windows
36 - a user account that is a member of the group *vboxusers*; required
37 to access any host USB devices from within a Virtual Box machine.
38 If you have just added your account to this group, remember that you
39 need to log off and on again before the changes come into effect.
40 - enable USB 2.0 support, provided by the *Oracle VM VirtualBox
41 Extension Pack*. The extension pack has to be installed through the
42 preferences menu in the VirtualBox client. Note that you may have
43 to run the client as root to have sufficient permissions to install
44 the extension pack.
45 - a USB device filter configured to pass host USB devices through to
46 the virtual machine
47
48 If everything is set up properly you should be able to forward USB
49 devices from the host system to the virtual machine. Try setting up a
50 USB device filter in the USB settings menu of the virtual machine.
51 You should be able to create a filter for the Truly Ergonomic Keyboard
52 right there. If you cannot see a list of USB devices at all at this
53 point check that your user account is a member of the group
54 *vboxusers*.
55
56
57 ## Performing the upgrade
58
59 Inside the Windows machine start the official firmware upgrade tool,
60 load the firmware you want to flash to the keyboard, and click on
61 *Upgrade*. This will result in an error message, but that's okay:
62 don't panic! The reason why this error occurs is that the USB
63 identifier of the keyboard will have changed from something like this:
64
65 ID 0e6a:030c Megawin Technology Co., Ltd Truly Ergonomic Computer Keyboard
66
67 to something like this:
68
69 ID 0e6a:030b Megawin Technology Co., Ltd Truly Ergonomic Computer Keyboard (Device Firmware Update mode)
70
71 Since the USB identifier has changed, VirtualBox may no longer forward
72 this device from the host to the virtual machine guest system. All
73 you have to do is add a filter for this new USB device in the guest
74 settings and resume the upgrade by clicking on *Upgrade* again. This
75 will again lead to another error, but I found that by that time the
76 upgrade has already been performed successfully.
77
78 Note that while the USB device is being forwarded to the guest system
79 you cannot use it in the host. To test if the new firmware works as
80 expected in your system, disable the USB filters in the guest
81 settings.
82
83
84 ## Next steps
85
86 It should also be possible to flash the firmware directly from a
87 GNU/Linux system. I suppose one could sniff the USB communication and
88 build a little tool that performs the upgrade natively on GNU/Linux.