USB Apple Extended Keyboard

Obviously I used QMK.

Repository containing the custom keyboard definition for my hardware is here: https://github.com/SkUrRiEr/qmk_firmware/tree/skurrier_aek_usb_custom

Sounds simple, right? Not really, getting here was an adventure.

1. What even is QMK?

The most simplistic answer is a cross-platform firmware for custom keyboards.

Which is correct, in the highest level view, but really, QMK is an "application" for ChibiOS which is a somewhat cross-platform hardware abstraction layer / kernel / operating system for microcontrollers.

So ultimately this means that QMK works on any microcontroller that ChibiOS supports, which means that a lot of microcontrollers work out-of-the-box, but there's also a few which are supported only through third-party code, which is kinda quasi-supported: QMK ships it, but that's it.

The Teensy family of microcontrollers fall into that latter category.

Ultimately I would probably have had a better experience with a different microcontroller, but I bought a Teensy LC for this project before I knew that, so I persisted.

2. How to QMK?

That's an interesting question to answer.

There's at least two different projects out there to help you go from your custom keyboard to a firmware for it's microcontroller.

• QMK's official configurator is excellent, if your keyboard is already supported. It doesn't appear to have any direct support for building firmware for your 100% custom keyboard.
• kbfirmware.com (I think that's where I got it from) is a way to turn a keyboard-layout-editor.com layout into firmware, and when I used it (over a year ago) it appeared to give me an ancient (even at the time) version of QMK configured with my keyboard's layout.

Neither of these are really a good path forwards if you have something truly custom. In my case, my keyboard is 100% custom, has a very simple layout (I'm not doing complicated stuff like layers, non-traditional modifiers, etc.) and has a weird matrix due to it's history as the Frankenstein monster of a random USB controller mixed with an Apple Keyboard.

So I went the most manual route, downloaded the official QMK firmware and associated tool, and did it all manually.

3. So how did that go?

I was able to rescue most of the layout work done by kbfirmware.com to make the layout bits work, however that was very much written from a "layout follows matrix" perspective which didn't really help me verify and modify the layout, so I ended up building my own custom layout macros and stuff so I could understand the layout files.

Then came the adventure of actually getting it compiled for the MKL26Z64 on the Teensy.

This is where the documentation dried up, and what had been a relatively straight-forward process became complicated.

I ended up copying all the files I needed from one of the other MKL26Z64 powered keyboards and that worked fine in my testing, but that doesn't seem to be the process one would expect. I'd expect to have some tutorial somewhere explain to me what I'm doing, what the values in the files I copied do, why they're there and why those values are "correct".

I can't find that documentation, I can't find any documentation on how this is supposed to work. The MKL26Z64 is one of the "not really supported but works" microcontrollers supported through the third-party code shipped with QMK. I can't find any useful documentation, and the tool you're "supposed" to use to manage these files doesn't seem to be documented.

I took my working firmware, flashed it, made some tweaks (hold a key to boot to the bootloader, fixed some mistakes in the layout) and I'm calling it done.

4. Conclusion

QMK really is the path forwards: even if you do it 100% manually like I did, it's pretty easy to go from some switches wired to a supported microcontroller to a working keyboard (if somewhat time consuming) and it has loads of fancy features around it to let you add some bling to your keyboard.

But ultimately, it's an open source project, focused on a small number of commercial keyboards who's companies employ the core developers. Everything, literally everything else is community supported and therefore anything outside the well beaten path is poorly documented, if it's documented at all.

I am more than happy with my keyboard and it's firmware, but I feel like it could have been better.

Maybe I'll end up with something more satisfying if I build the super-ergonomic split keyboard I've been thinking about...

At the time of writing this, I'm considering this project fundamentally complete:

• The key matrix has been re-built to contain anti-ghosting diodes
• The USB controller has been replaced with a Teensy LC
• Some relatively minor changes have been made to the non-key electronics to adapt it to these changes
• A custom keyboard matrix and layout have been built for QMK
• And that Teensy LC has been flashed with this QMK build and the QMK configuration has been tweaked a little to suit the final product

This post is going to cover the hardware side of this latest round of progress.

The Matrix

The original matrix was designed to replicate the matrix of a cheap membrane USB keyboard and as such was just point-to-point connections between switches with some flying leads to the USB keyboard's PCB. QMK can support this sort of matrix, so I could have just gotten away with replacing the original USB PCB with the Teensy LC, but that wouldn't have produced the result I was after.

Adding a diode to every key took 4 days of work.

The plan was pretty straight forward:

1. Remove the original controller
2. Add diodes
3. Add in the Teensy LC

This is what the original matrix looked like after the controller and all it's flying leads were removed. You can see the leads in a pile in the bottom half of the case.

I also took the opportunity to label the connection point of every column and row, these are the big "C11" and "R5" labels. Note the thick sharpie marks next to some pads, this was to make it obvious exactly which pad was the connection point as there was already a lot of sharpie marks on the keyboard from the original matrix. (I believe I used these to mark connections in the original matrix once I was sure it "dealt with": either connected to the correct keyswitches or cut)

And this is what the board looked like when I was finished. I got into the groove and didn't take any progress shots.

Each keyswitch got it's own diode, however actually adding those diodes to the matrix required some level of creativity:

• Some were easy: I'd previously cut a trace on the "row" side of the keyswitch, so that  pad was isolated, this just required shortening the connecting wire and adding a diode. You can see examples of this at the top right and top left.
• Some required a little extra thought: it technically doesn't matter which side of the keyswitch the diode is on, as long as it faces the correct direction, so if the pad on the "column" side of the keyswitch was isolated, then I could just stick the diode on that side instead.
• There were a few places where, through some happy accident, the connecting wire was short enough and direct enough that I could just solder a naked diode in place of it and that would be enough. You can see an example of this at the middle right running diagonally.
• However the vast majority of the keyswitches required a lot of creativity to hook up. There were a lot of places where a bunch of isolated pads were nearby, so I used diodes to bring these to a common point (or set of points) and connecting a wire to each "end" of this structure. This occurred on both sides of the keyswitches. An example of this o the "row" side is visible at the top right just to the right of the big hole and at the bottom left diagonally above the "C14" label. There's also an example of this on the column side half-way between the masking tape label and the "C9" label.

Using all of those options together resulted in an even more confusing matrix than it was originally: due to how all of this fit together, every keyswitch has at least one diode, and some have two or more connected to them. There was a lot of work required to decide which technique to use on each keyswitch, keeping in mind both the column and row nets and their particular requirements. I also took the opportunity to "weave" the hookup wires together so they kinda held each other down to the PCB, and after 4 days of effort, more solder joints than I can count, and a bit of frantic work to disconnect two nets that somehow became hooked together, it was finally complete, and to my immense surprise, worked correctly first time with all diodes in the correct directions and no shorts or mistakes.

I then found an empty part of the board near the top to glue down the Teensy LC, hooked it up with coloured wire (white for columns, black for rows) and started working on the QMK build for this keyboard. I'll cover that in the second post.

USB Hub

The original keyboard had a built-in USB 2.0 hub to drive the two USB ports on the right of the keyboard, I kept that, but replaced the hard-wired connection to the original controller board with a short USB micro-B cable. The idea here was that I could then glue the hub into the base of the keyboard's case and be able to disconnect the keyboard when disassembling. I ended up glueing the plug to the keyboard with hot glue during final assembly, so it's possible but not likely that I'll be doing that -  the micro-B plug there is particularly cheap and doesn't hold onto the socket particularly well.

LEDs

I'd chosen the pins used on the Teensy LC such that the columns were all in order and on a single bank of pins in the hope that this would allow QMK to do something optimal - I don't believe it does - and forgot to check the current ratings of the column pins when I wired them up. Consequently I ended up with 4 pins left over: 13 which has the LED hooked up to it - which I wanted to leave alone - and 24, 25 and 26, which are really the "extra" pins which really should get used for other stuff and frustratingly all have 5mA current limits.

I therefore made the decision to use some of the huge stack of BC547s I had lying around to allow for a higher amount of current on the LEDs. One of the problems with the original keyboard was that the very old LEDs on the AEK weren't particularly bright when driven by the original USB controller board, so the mistake I made - using 5mA limited pins - ultimately gave me an opportunity to fix another minor problem with the original board.

The circuit here is pretty trivial: a 240 ohm resistor between the LED and +5v, and a 1K resistor between the base and the IO pin on the Teensy.

Those who know AEKs well will notice that the LEDs are hooked up backwards. When I was labelling the LED pins while removing the original controller, I incorrectly assumed that the common pin was negative and then designed my structure above with the LEDs backwards. When testing I quickly found that the LEDs weren't working, so I removed them and reversed them.

Final Touches

Once the entire thing was tested, working and all the keyboard wiring was finalised, I added hot glue to every "free" joint on the board:

• The transistors and connections around them.
• Any place where diodes met in a location away from an existing pad, e.g immediately to the right of the USB connector.
• Any place where a wire joined onto a diode's leg instead of onto a pad, e.g. where the yellow wire connects to the diode at the bottom left under the middle transistor.

As discussed, the USB connection to the Teensy LC was marginal at best, so a blob of hot glue was added to keep the USB plug from falling out (it was approximately where the blue and red wires cross)

I also firmly glued the hub to the bottom case of the keyboard, positioned so the remaining USB socket faced into the body of the keyboard. I've thought seriously about adding a Logitech Unifying dongle to that socket, but I primarily use this keyboard with a Bluetooth mouse, so it would be of limited use.

Despite all the modifications I made to the lower case of the keyboard when originally modifying the keyboard, the new location of the cable pressed against one of the remaining stiffening ribs, so that had to be modified to allow it space to move around the post that goes in the hole to the left of the connector.

At this point the hardware was complete: I could close it up, flash it with QMK and be done.

However actually getting QMK working here required a surprising about of effort, so I'll cover that in a separate post.

[Atomic Shrimp] on Youtube posted a project he was working on here:

This is essentially the same sort of project as the original incarnation of this keyboard, but with the added simplicity of starting off with a chunk of protoboard instead of trying to hack an existing PCB.

He did a lot of things right:

• a mix of mapping out the matrix and brute-forcing the keyboard matrix is a much better process to map out the keyboard than my process of building a quasi-chorded keyboard with a button for each row and column hooked to a common point
• magnet wire is much neater than my solid-core breadboard wire (even though you then can't have all links for a particular row or column the same colour)
• designing a keyboard layout from scratch drastically simplifies the project - I'm sure that adapting the original Apple Keyboard matrix to suit my donor USB keyboard controller was a significant amount of mental effort

However at the end of this he did come to the correct conclusion: building a key matrix to suit an existing controller is far more complicated and difficult than building a matrix from scratch and programming your controller to suit.

Keyboard design is a compromise between hardware complexity, software complexity, and cost:

• QMK adds a lot of software smarts and this can be used to drastically simplify the hardware design
• But this requires "expensive" hardware, i.e. key matrices with diodes
• A bit of hardware cleverness - designing the matrix to minimise ghosting opportunities - can drastically reduce the hardware cost, but that greatly increases the complexity of the hardware and pretty-much precludes any attempt to hand-wire it
• That hardware cleverness, as well as mass-production efficiencies, can also drastically reduce the amount of software complexity required - no need to detect ghosting if it should never happen - and therefore reduce the requirements of the hardware running that software

Long story short, it's a big game of give and take - on one hand these cost optimisations have enabled us to be able to buy reasonable keyboards for $7 / £3, however the design optimisations required to achieve that have made what should be a very simple device mind-bogglingly complex.

I tend to think of design happening in this rough sequence of phases:

1. Proof of concept - works well enough to show critical people
2. First generation manufacturing - can be manufactured in large quantities
3. Later generation optimised manufacturing - has been extensively analysed to reduce costs

The problem for us hobbyists is that most consumer products are now multiple generations into phase 3 and have been streamlined and optimised to the point where we're unlikely to ever fully understand them.

Thanks [Jenny List] for the writeup.

Reading through the comments I'd love to acknowledge any other people who had made insane contraptions like this. If you end up writing them up, please let me know I'd love to read them and I'll link to them from here.

To respond to the people writing things like "I'd use product X instead of going to all this effort", the answer at the time I constructed this was simple: cost.

I had pulled this awesome keyboard out of a dumpster and said to myself "man, I'd love to actually be able to use it". I had no Apple hardware, no sensible way to acquire an ADB-to-USB converter (I believe they did exist at the time and were quite expensive) and knew nothing about custom keyboard controllers, had no usable microcontroller (I hadn't encountered Arduinos yet, so electronics programming was either a Lego RCX or stuff hooked up to a computer's parallel port, neither of which would work here.) and no idea how ADB, PS/2 or USB worked, so weighing up all the available options, the simplest solution to my problem seemed to be to graft in a donor keyboard controller.

The total cost for this project was:

1. $7 for the donor USB keyboard
2. $20 for the USB hub (I can't remember how much it cost, but I purchased, literally, the cheapest I could lay hands on. $20 seems about right.)
3. a couple of dollars for the matrix wire, solder, solder wick, etc. (all of which I had on hand already)
4. a couple of dollars for the USB-B port (I believe I had to purchase one new)
5. Every other piece of hardware (The Apple Extended Keyboard, USB-A ports, PCB scraps, the yellow and black wires, the thick black cables, etc.) was recycled.

My time, given that I was a university student, was free.

So overall the total cost was about $30 + a few weekends of my time.

I also wanted to remap some of the keys (specifically the ctrl, option and apple keys) so they matched the order they'd be in on a PC keyboard, so any converter would had the modifiers ordered ctrl, alt, win, not ctrl, win, alt, so I would have needed software hacks to make the keys match where my fingers think they are. I was running Windows at the time and I'm not sure it's possible to switch the modifier keys without third-party software.

If I'd done this today, I'd have found or built a USB-C hub that could use any port as the upstream port so I could have had USB-C ports on both sides and used a Teensy or equivalent to run the original matrix in place of the original controller chips. This would have made this project a mostly-software project, not a crazy hardware project. I'd also have ended up chasing the ideal of having this daisy chained with a Thunderbolt monitor or USB-C power supply.

Someone commented on the longevity of the joints and hot snot. I can only talk to this particular keyboard, but I've had zero problems over the past decade, so as far as I can tell, there's no issues with longevity. Note that this has been bounced around a bit, travelled and gone through several house moves. I'm not gentle with my electronics, even stuff I've made myself, so if it was going to fail, it would have by now.

The construction is a little eccentric, mainly because of the specific parts and stuff I had available. The yellow and black wires are multi-strand wires recycled from somewhere and are relatively flexible. All the other wire is solid-core wire and relatively inflexible. All wires are point-to-point wires between legs of the various keyswitches. Some of the soldering is a bit dodgy, but it's all solid. There are resistors at the board end of all the black wires and those are all anchored with way too much hot snot, most of that hot snot is globbed over other wires, so even if it pops off the board itself, the wires should keep it from moving around too much.

Version 2 of this, i.e. proper matrix with diodes and a Teensy, will require adding diodes to every single keyswitch, so there will be a lot more potential for movement there, but I'll be adding a lot of diodes and the matrix should allow me to tie the diodes together, so they should be no more delicate than any other hand-wired keyboard.

And the last comment was about harvesting it for parts and building something new. The goal here was, from the very beginning, to have an Apple Extended Keyboard I could use on my PC. I agree that this keyboard could easily be stripped for parts and make an awesome custom keyboard, that's not the objective here.

Thanks for the write-up, thanks for the comments and thanks for the reminder that all the bits I need for version 2 are currently in my possession - all I need to do now is build it.

When I initially built this, I mapped out the matrix of the USB keyboard controller by attaching wires to the pads for the 8 rows and 18 columns to a bunch of switches and used those to map out the entire matrix.

I did this by building a piece of protoboard with 26 switches all wired to a common wire, then wiring the rows to 8 and the columns to the remaining 18. I could then simulate a key at a particula row and column by pressing the switches for the row and column simultaneously.

I wrote this up in an Excel spreadsheet which I've lost somewhere on one of the dead hard disks from my first computer.

I then cut traces and soldered wires to convert the matrix of the AEK into that particular matrix.

Now, 15 years later, I'm having to reverse-engineer the bits I need from that map by beeping out the keyboard.

I ended up with this:

(Colours indicate rows of physical keys, blank cells are rows and columns that don't have a corresponding key.)

I'm going to need to make some modifications to improve this to make the microcontroller selection a touch easier:

• Combine columns 9 and 15: this moves the shift keys into the gap in column 9.
• Combine columns 14 and 16: this moves the left alt key into a gap in column 14.
• Combine columns 0 and 17: this moves the right alt key into a gap in column 0.

This leaves me with 8 rows and 15 columns requiring a total of 23 GPIOs to produce a total of 105 keys. Adding in the three LEDs, I need 26 GPIOs.

Frustratingly my LeoStick has only the Arduino standard 14 + 6 = 20 GPIOs and even if I use the 3 in the programming port, I'm still 3 GPIOs short, so I'm going to have to buy a microcontroller for this.

Hacking two keyboards together requires making compromises between what is available on the controller and which keys are present on the keyboard.

I got somewhat lucky by buying a keyboard with a Windows compatible power key, so I was able to wire that to the power key on the keyboard.

However there were a couple of other compromises that I made to make it all work properly:

Modifier Keys

Apple keyboards have their modifier keys arranged as Ctrl, Option / Alt, Command / Apple and PC keyboards have them arranged as Ctrl, Windows, Alt.

As a PC user, I made the decision when hacking the matrices together to ignore the labels on the keys and wire the modifiers in the PC fashion. Thankfully, this isn't a big deal as QMK lets me map the keys however I like.

Keypad Equals Key

Numpads on Apple Keyboards have a "=" key next to the numlock / clear key and all of the operator keys (+, -, * and /) get moved around to fit it in.

This isn't something that's done on PC keyboards so the controller I used didn't have any sensible place on it's matrix to wire this to.

Consequently I made the decision to make it work with most calculator applications so I wired it in parallel with the numpad enter key.

This is something that I'll have to rectify when re-wiring the matrix.

My knowledge of custom keyboards and the community around them has grown immensely in the past 15 years. Concepts like easy-to-program microcontrollers with USB ports and big community led projects to make easily customisable keyboard software were unheard of when I started.

Back then Arduinos were barely a thing, let alone stuff like the Arduino Leonardo or Teensy.

So ultimately the sensible path forwards was to acquire a board that did what I wanted and hack stuff to make it work.

However today, I have desires to build designs of keyboard I can't get elsewhere (I want a full-size Thinkpad-style keyboard with Cherry MX Blues or an Ergodox style split one with a built-in Trackpoint) and maybe a simple step towards that would be to take my slightly annoying old AEK and modernise it's internals.

What's even better is that I already have a QMK compatible microcontroller on hand: a LeoStick, essentially a thumb-drive sized Arduino Leonardo with an ATMEGA32U4 (Freetronics is an Australian manufacturer of Arduino compatible boards)

So now all I need to do is modify the matrix to be compatible (which I believe will be adding diodes to prevent ghosting) and replace the existing controller board with the LeoStick.

Simple!

Except it won't be, I'll have to map out the entire matrix, figure out where I can hack in the diodes, then modify it.

Mapping out that matrix will be the next step.

Ultimately the fate of the AEK was that I barely used it. My computer at the time required a PS/2 keyboard, so I used a Microsoft Multimedia Keyboard on that (also excellent to type on) and shortly after I upgraded it to a motherboard that fully understood USB keyboards my partner bought me an (excellent) DAS keyboard which immediately became my daily driver.

The AEK then ended up in my pile of computer stuff in my wardrobe and was mostly forgotten about until, almost 10 years after I built it, I ended up working for a company that provided me with a MacBook Pro for my development computer, and as the supplied external keyboard (an Apple Magic Keyboard - I still don't know what made it magic) was a poor typing experience, the only obvious solution was to dig out my old Apple Extended Keyboard and plug it back into a Mac.

My colleagues loved it, I loved it, but as I got used to it's shape and layout I started typing faster and faster and discovered that while it was lovely to type on, it had a pretty glaring flaw: certain combinations of keys, ones which I hit fairly regularly, wouldn't work every time. I think that the issue is that there's a maximum number of keys the controller can detect at once and when I typed fast enough, I was hitting that limit.

I replaced it with a Logitech one which didn't have that issue.

So back into the cupboard it went until 2020 when I started working from home full-time and needed a good keyboard. My partner has an old Acer keyboard from forever ago which got her through an essay heavy university course without a single hiccough, but somewhere in the past 15 years the spacebar's springs had failed so it wouldn't pop back up reliably. I tried to fix it, but nothing I did worked reliably.

Faced with the possibility of having to steal a fairly cheap Logitech keyboard from another computer, I remembered my AEK and pressed it back into service almost 15 years after I built it.

And it's excellent, the keys are wonderful to type on, not quite as nice as the Cherry MX Blues in my DAS, but still pretty damn good, and once again, I've started running into the limitations of it's hardware: every now and again it misses a keypress. I'm clearly typing slower now than I was before, because it doesn't happen as often as it used to, but it's still bothering me.

So it's time to do something about it.

Back when I was a poor university student, I came across a bunch of Apple peripherals in a dumpster, this included this Apple Extended Keyboard, a couple of mice and one of their smaller keyboards.

I'd never really spent any time with Apple hardware (my family is firmly IBM PC compatible) so I'd never typed on one, but it felt nice and after opening it up, I concluded that it would be possible to make it a USB keyboard by the simple process of completely re-wiring the matrix to suit a USB keyboard controller and wiring all of that together.

I was technically right, it was possible to do all of that, but it was a heck of a lot more effort than I'd expected and produced a far inferior result than I'd hoped for.

The parts required were pretty trivial:

1. A USB keyboard (I got what was, at the time, an unbelievably cheap one for $7)
2. A USB hub (this was so I could replace the ADB port on the far side with two USB ports)
3. Some USB connectors (I bought the USB-B one and the dual-USB-A one came from a PC case)
4. Wire (some is breadboard wire I purchased for the project, the rest is misc wire from ... well anywhere I could pull it from)
5. USB cabling (all recycled from the $7 keyboard's cord)

And the process was simple, but time consuming:

1. Map out the entire matrix of the USB keyboard (it had a bunch of bonus keys that the hardware recognised but didn't have a physical key, presumably for international layouts)
2. "Apply" that onto the AEK's PCB
3. Wire between the new controller, USB connectors and hub
4. Cut out some of the standoffs and supports in the base so the wires would actually fit
5. Expand the far-side ADB hole so two USB plugs would fit
6. Glue everything down (hot snot FTW)
7. Plug it in and enjoy it

The "application" of the new matrix onto the PCB was, by far, the most complicated and time consuming part.

I did this by doing three major operations: de-populating the board of anything that got in the way (essentially all the controller chips) cutting traces on the board where they didn't fit and wiring between pads to build out new bits of matrix where needed.

It was rather time consuming.

I can't remember exactly how I did it, but I do remember that I couldn't remove the metal plate that holds the keyswitches in position, so I couldn't remove the wire links that allowed some of the traces to jump over other traces, so I had to cut those traces by cutting the copper on the board. I estimate that I made well over 100 cuts to split the nets up into the few bits that corresponded with the matrix of the USB controller.

While I was doing that, I was also wiring between keyswitches to link the various chunks of net together to form the matrix the USB controller was expecting. I think I marked each keyswitch off as I wired it in by putting a black sharpie mark covering the copper next to the pad.

Each net got either a yellow or black wire attached to it which then connected it to the relevant pad on the USB Keyboard controller board. The USB keyboard I bought was a cheap membrane keyboard so it had some black substance on the pads which I had to scrape so I could solder to them.

The black (row?) nets also got a resistor in series with them (harvested from somewhere) to simulate the resistance of the membrane traces. (This was probably unnecessary, but I didn't want to risk it)

Finally I wired the original LEDs up to the LED pads on the controller board, wired in the USB hub, glued everything down closed it up, plugged it in and marvelled at how awesome it was to type on what was one of my first a mechanical keyboards.