Set up build environment

You could read this repository as if it were a book, but that would be
pretty boring. You’d get lost at roughly the third significant commit
without following along. So, what do you need if you want to build and
try everything here?

## Hardware

* Of course, a computer capable of working with USB devices.
* A [Truly Ergonomic] Computer Keyboard, any model. I actually have two
  of them — an older Model 109 to type on, and a newer 209 to conduct my
  horrible evil experiments on. (Muahahahaha.)
* I also find that a USB hub with individual port on/off switches is
  very handy, though rare to find.

I plug my both keyboards into the hub, and the hub into the computer.
When updating the firmware in the test keyboard, I switch off my main
keyboard port, so as to prevent surprises. I also keep the test keyboard
port switched off when not hacking.

## Software

* I work under [Ubuntu] 14.04 “Trusty Tahr”, amd64 version. This has its
  benefits and drawbacks.
  * The benefit is that I don’t have to fiddle with installation of
    other tools — I install a few packages and it Just Works. On
    Windows, you should be able to install all of the below, but
    expect to spend some time getting everything to work.
  * The drawback is that the Truly Ergonomic DFU (Device Firmware
    Upgrade) tool does not run under Wine. (That’s to be expected as
    it needs direct access to the USB device, which is not yet
    supported.) So I run [VirtualBox] with a Windows installation
    inside, and the Extension Pack which is required in order to
    connect USB devices directly to the VirtualBox machine. (I will
    detail VirtualBox setup when it comes to flashing our first test
    program into the TECK.)
* To compile my test programs, I use [SDCC] 3.3.0.
* The _de facto_ standard way to manage compilation of a software
  project in the Free software world is GNU [Make]. Ubuntu 14.04
  comes with Make 3.81.
* On the early stages, I will use a disassembler to look at what the
  compiler produces. I use [Dis51] 0.5.
* And of course you need [Git] in order to clone this repository and
  navigate around it.

[Truly Ergonomic]: https://www.trulyergonomic.com/
[Ubuntu]: http://ubuntu.com/
[VirtualBox]: https://www.virtualbox.org/
[SDCC]: http://sdcc.sourceforge.net/
[Make]: http://www.gnu.org/software/make/
[Dis51]: http://home.earthlink.net/~davesullins/software/dis51.html
[Git]: http://git-scm.com/

To install all of the required software in Ubuntu 14.04:

```
$ sudo apt-add-repository 'deb http://download.virtualbox.org/virtualbox/debian trusty contrib'
$ sudo apt-get update
$ sudo apt-get install virtualbox-4.3 sdcc make dis51 git
```

## Safety notice

By updating firmware from inside a virtual machine and over a USB hub, I
violate two guidelines that Truly Ergonomic recommends on their site. I
do this because it works for me and is more convenient than hacking
under Windows, rebooting each time I want to try a new version, or
setting up a physical Windows machine as a firmware update station.

If a firmware update process goes wrong, the keyboard might become
“bricked”. I have never managed to screw up so badly as to be unable to
repeat the firmware update; that is, all the code that is required to
enter the DFU mode has remained functional. However, it is said that one
can force a hard reset to DFU mode by opening up the device and shorting
pins 1 and 36 while power is on.
Using Git to move around on this branch

To clone this repository and check out this branch:

```
$ git clone -b sdcc https://github.com/yurivkhan/teck.git
```

I suggest that you then use `gitk sdcc` to navigate around the branch.
For example, find this commit in the list, right-click it and select
“Create new branch”. Then type in a name for your reading branch. Then
right-click the newly created branch and choose “Check out this
branch”.

To move to a different commit, right-click it and select “Reset _name_
branch to here”. When prompted for the reset type, choose Hard reset.