The Treasure Macropad Type-9
Open Hardware – TMT9
This DIY, programmable input device is a compact companion to your keyboard, with nine keys and 16 layers that can be customized for different applications and games.
From keyboards to graphic tablets, modern input devices are sporting programmable keys. These keys are not only convenient, but help to reduce repetitive stress injuries by keeping the fingers on the keyboard. Yet there is something to be said for a single compact programmable device rather than several scattered across your workspace. That is the advantage of the Treasure Macropad Type-9 (TMT9) [1], the first product of Eric Boudo's new company (Figure 1). Measuring a little over 2x2 inches, the TMT9 has only nine keys, but includes 16 different layers, for a total of 144 programmable keys altogether. It's a compact little device, although for Linux users it requires a certain amount of work and patience, since only graphical setups for Windows and macOS are available.
No matter what your operating system, the TMT9 requires some DIY adjustments, especially since the company is not set up for technical support. Fortunately, ample help is available on the Quantum Mechanical Keyboard (QMK) website [2], although configuration takes several steps. In addition, units ship unassembled, although no soldering is required. Nor do units ship with keycaps for the Cherry MX mechanical key switches, which have to be ordered separately from a third party [3] (Figure 2). Also, while a newer model that supports USB C is due out soon – and may be available by the time you read this article – the TMT9 requires a USB 2.0 A-Male to Mini-B cable, which is not easy to find in computer stores these days. In the end, I had to order one from Amazon.
Configuring QMK for Linux
However, for Linux users, the challenge is just starting. The most common tools for flashing firmware, the Arduino IDE and the avrdude
command, will not work. The TMT9 uses the Atmel DFU bootloader, which neither of the two usual tools supports. However, this fact is obscured by avrdude
's man page being out of date, which can easily lead the inexperienced – like me – on a false path.
Instead, what you need is to install QMK, an open source toolset specifically designed for keyboard input devices that must be installed before creating firmware. The instructions are for Debian or one of its derivatives. With git
and AVR-GCC installed, create a clone of the QMK repository (Figure 3):
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git cd qmk_firmware
The repository includes a number of keyboards that use QMK that will help you build firmware. Continue by running this script to finish setting up the repository:
util/qmk_install.sh
The script is set up for Debian and its derivatives, and installs or updates all the necessary packages (Figure 4). However, be aware that the script mistakenly looks for pip3, when the package required is python3-pip. Installing python3-pip will also pull in a lot of dependencies, but it is necessary for successful setup.
You can check that the build environment is sound by running:
make treasure/type9:default:
This command gives the path to the firmware tools for a default piece of software, followed by the name of the firmware version after the colon. You may need to reset the bootloader by poking the wrench that comes with the device into the hole in the back of the device. If no error message is given, try tapping one of the keys in a text editor. The result will be a number from 0 to 8 if the firmware was successfully loaded (Figure 5).
Creating and Uploading the Firmware
The easiest way to create new custom firmware is to copy the default one and modify the original. Copying the default not only preserves a workable firmware if you need to recover from a flawed one, but saves you typing. To customize, open a copy of keymap.c
, and scroll down to the line:
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] =
Following this line are the key layouts for each layer. The first layer is designated 0, and has the nine keys laid out in three rows, with each row a comma-separated list of keycodes (Figure 6). You can have up to 16 layers, each customized, if you choose, for a particular application or game, or any other combination of keys you find useful. Note that some keys may have no effect in a particular application; for example, an F11 key will have no effect if an application does not use that function key. You can edit the default layer or add another layer by copying the default layer, changing the layer number, and modifying the keycodes. In either case, use the summary of keycodes as a guide [4].
Keys can be alphanumeric, control or function keys, or for sound, Bluetooth, or toggling backlights and changing their brightness. Advanced key functions include one-shot keys that remain active until another one is pressed, making key combinations easier, and Mod-Taps keys that behave differently when tapped instead of held down. When building a custom setting, it is best to do it one key at a time, because not all keycodes in the QMK documentation appear to be implemented, and some are specific to the operating system. Be sure to preserve the commas and the surrounding parentheses, or your custom layer will not compile.
If you have multiple layers, be sure that you provide a navigation system to switch between layers. Since the documentation suggests not switching to a lower level, the best method is to create a toggle system, using the keycode DF(1)
on layer 0 to allow switching to layer 1, DF(2)
on layer 1, and so on, ending with DF(1)
on the highest layer you are using, DF(2)
on layer 1, and so on. This navigation system uses one key on each level, but still leaves plenty for other macros.
When your custom firmware is completed, save it as the default and upload it using the version of the command structure given above to test the environment. Contrary to the documentation, a keymap with a different name may not compile. At times, too, an Error 1 message is given, but checking the device shows that the firmware was successfully uploaded.
If you prefer a graphical interface, you can customize layers using the online instructions' steps 9-16 [5], and place the resulting .json
file in a place where you can conveniently compile and flash it. To customize, open the QMK Keyboard Firmware page, and scroll down to the Treasure Keyboard Macropad button. Either way, a simple map of the TMT9's keys displays (Figure 7). Do not change anything on the Wiring or Pin tabs, but click instead on the Keymap or Macro tab.
To program a key with the online interface, select the layer (starting at 0), and click a key. At the bottom of the page, the current configuration for the key displays in a box. Click the box, and chose another configuration from the graphic interface. The site contains a summary of the available keycodes built into the interface.
When you have configured all the keys you want in the graphical interface, go to the Settings tab to save the source file on your machine. The only setting you need to change is the name, but you might want to set the brightness of the backlights on a 10 point scale, with 10 being the highest (Figure 8). Then move to the Compile tab to produce the finished .hex
file and download it to your computer. As you work, you may want to record a layer's contents on one of the two cards that comes with the device for future easy reference.
To upload the .json
file, install QMK CLI [6], and use the command qmk compile
; don't forget to disable the bootloader by poking the wrench into the hole on the bottom of the device.
The End Results
Countless variables make setting up the TMT9 with Linux a slow process. Here, I can only discuss the circumstances you are most likely to find. Setup is not helped by the fact that the TMT9 hides the indicator light that shows when it is reset, and the DIYer can only go by the slight give when the wrench is poked into the inner workings. Would an external LED really be too much to ask?
Still, that is the nature of DIY products. While my stubbornness in insisting on working in Linux complicated setup immensely for me, in the process I learned a lot about AVR devices and how they work, gaining a body of knowledge that I would have missed had I given in to the temptation to work on a neighbor's Windows machine.
I am surprised, though, that Treasure has not bothered to add Linux support. After all, while Linux users may be a small minority, I suspect that they include a percentage of DIYers that is far higher than among Windows or macOS users. Or possibly, the expectation is that Linux users will know enough to follow the instructions on the QMK site.
However, in the end, I don't regret the effort. The TMT9 offers more convenience and efficiency than any other device with the smallest footprint that I have ever encountered. I would far rather have a TMT9 on a keyboard than a number pad, for instance. Moreover, in its red anodized aluminum case, it is an elegant device. I am still organizing layers, but I can already see that it will lead to a major improvement in my workflow – to say nothing of my efforts to reduce repetitive stress injuries.
Infos
- TMT9: http://macropad.co/
- QMK documentation: https://beta.docs.qmk.fm
- Cherry MX Keycaps: https://duckduckgo.com/?q=cherry+mx+keycaps+blank&t=ffnt&ia=shopping
- Keycodes for programming: https://docs.qmk.fm/#/keycodes?id=keycodes-overview
- Windows and macOS instructions: http://macropad.co/support/
- QMK CLI: https://docs.qmk.fm/#/cli
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
Linux Sees Massive Performance Increase from a Single Line of Code
With one line of code, Intel was able to increase the performance of the Linux kernel by 4,000 percent.
-
Fedora KDE Approved as an Official Spin
If you prefer the Plasma desktop environment and the Fedora distribution, you're in luck because there's now an official spin that is listed on the same level as the Fedora Workstation edition.
-
New Steam Client Ups the Ante for Linux
The latest release from Steam has some pretty cool tricks up its sleeve.
-
Gnome OS Transitioning Toward a General-Purpose Distro
If you're looking for the perfectly vanilla take on the Gnome desktop, Gnome OS might be for you.
-
Fedora 41 Released with New Features
If you're a Fedora fan or just looking for a Linux distribution to help you migrate from Windows, Fedora 41 might be just the ticket.
-
AlmaLinux OS Kitten 10 Gives Power Users a Sneak Preview
If you're looking to kick the tires of AlmaLinux's upstream version, the developers have a purrfect solution.
-
Gnome 47.1 Released with a Few Fixes
The latest release of the Gnome desktop is all about fixing a few nagging issues and not about bringing new features into the mix.
-
System76 Unveils an Ampere-Powered Thelio Desktop
If you're looking for a new desktop system for developing autonomous driving and software-defined vehicle solutions. System76 has you covered.
-
VirtualBox 7.1.4 Includes Initial Support for Linux kernel 6.12
The latest version of VirtualBox has arrived and it not only adds initial support for kernel 6.12 but another feature that will make using the virtual machine tool much easier.
-
New Slimbook EVO with Raw AMD Ryzen Power
If you're looking for serious power in a 14" ultrabook that is powered by Linux, Slimbook has just the thing for you.