Threeboard: Short On Keys, Long On Documentation

The threeboard simulator running

As peripherals go, few are hacked on more than keyboards. The layouts, the shapes, the sizes, materials, and even the question of what a keyboard is are all on the table for tinkering. In that vein, [TaylorConor] released his simplified keyboard called the threeboard on GitHub, having only three keys and replicating a full keyboard.

We’ve covered keyboards built with chording in mind, wrapped around coffee cups, and keyboards with joysticks for added speed. So why cover this one? What makes it different? The execution is superb and is a great example to look at next time you’re making a project you want to show off. The keyboard is just three mechanical switches, two 8-bit binary displays (16 LEDs total), three status LEDs, and three LEDs showing the current layer (four layers). The detailed user’s manual explains it all. There is a reliable Atmega32U4 microcontroller and two EEPROM chips at its heart.

Where this project shows off is the testing. It has unit tests, simulated integration tests, and simulated property tests. Since all the code is in C++, unit testing is relatively straightforward. The integration and property tests are via a simulator. Rather than recompiling the code with some new flags, he uses the simavr AVR simulator, which means it simulates the same binary file that gets flashed onto the microcontroller. This approach means the design is tested and debugged via GDB. It’s an incredible technique we’d love to see more of in hobby projects. Marketing speak might call this a “digital twin” but the idea is that you have a virtual version that’s easier to work on and has a tighter iteration loop while being as close as possible to the physical version.

[TaylorConor’s] goal was to create a from-scratch microcontroller project with easy-to-read code, fantastic documentation, and best practices. We think he nailed it. So feel free to run the simulator or jump right into building one for yourself. All the hardware is under a CERN-OHL-P license, and the firmware is under GPLv3.

7 thoughts on “Threeboard: Short On Keys, Long On Documentation

  1. but now he’s got a complicated and brittle toolchain for a very simple project. the parts that make it well-structured and easy-to-develop are more complicated than the project itself. good coding is *managing* complexity. it’s worth adding some complexity if it helps you manage the complexity that is inevitable. but if your goal has no complexity from the start, then adding complexity is just adding complexity.

      1. This is HaD. Every article about a project will have at least one of the following:

        – Should have just bought a commercial product
        – Could have done it simpler
        – Should have done it with a 555/Arduino/Rust/Go/Erlang/Chisel

    1. Original author here: the “complicated and brittle” toolchain enables compiling almost all targets for x86 and AVR simultaneously, so unit tests can be run against almost all targets from a local x86 dev environment. While I agree that this increases the amount moving parts in the toolchain, it’s built upon Google’s Bazel build system, which is designed explicitly to be used and extended in this way. So the tradeoff is definitely worthwhile.

      1. lol.

        me: complicated brittle toolchain
        you: google buzzword

        google’s tendency to dump projects before it’s even done pumping them up is legendary and nowhere is it more on display than in their pernicious approach to development environments.

        anyways, my point was, your keyboard driver is so simple that you don’t need a cross-platform emulator / debugger environment, you can just write it correctly the first time around. i know that sounds so trite it borders on sarcasm but the time you spend debugging something like that is nothing compared to the future cost you’ve embedded into this project if anyone ever does revisit it. in 5 years, anyone looking at your project will be so mad at you for your dependency on bazel.

Leave a Reply

Please be kind and respectful to help make the comments section excellent. (Comment Policy)

This site uses Akismet to reduce spam. Learn how your comment data is processed.