Apogee Mathkeeb Assembly instructions

Mathkeeb™ Advanced User’s Guide
2019-2020 edition

Table of Contents
Table of contents
Welcome/Getting Started
page number
1
2
Reprogramming
Custom Firmware
Troubleshooting
3
5
10
1

Welcome!
Thank you for purchasing an Apogee Industries Mathkeeb! As you know, this keyboard was
designed specifically to aid in efficiently typing mathematical expressions while writing equations,
programming, or just for everyday use. However, we recognize that not all programs speak the
same language! To solve this issue we have written up this small guide on how to customize the
Mathkeeb to meet your personal needs, whatever they may be.
We’re glad you’ve decided to take the next step and download the Advanced Users Kit. With
this kit you will be able to load different hex files onto the keyboard’s controller allowing it to speak
different languages, or even have an entirely new layout. This guide will provide instructions on
how to create and load your own custom firmware, or load one of the alternative firmwares which
we have provided as a part of this kit.
Getting Started
In order to use this guide you will need the following resources:
1. An Apogee Industries Mathkeeb™
2. The included .zip folder
Note: Using some of the tools mentioned in this guide will require an internet connection.
2

Reprogramming
Reprogramming of your Mathkeeb is done by loading a new .hex file onto the Teensy
Controller. This chapter will guide you through the process of doing so.
Loading .hex files onto your Mathkeeb is made simple via the use of the Teensy Loader
software. This software can be downloaded from the PJRC website at the following link:
https://www.pjrc.com/teensy/loader.html
Once you have acquired the loader software, the loading process is as simple as pressing a
few buttons.
The first button is located on the Mathkeeb itself. To access this button, flip the keyboard
over and set it down on its keys. You should see a small pinhole near the usb port at the top (see
below)
Please keep in mind there are delicate electronics inside this case! We recommend using a
toothpick to push the button at the bottom of this hole. Once the button is pressed, you may hear a
sound from your operating system indicating disconnection of a USB device. This confirms that you
successfully hit the button.
Your Mathkeeb is now in programming mode. If you have the Teensy Loader software open,
it should look something like this:
3

To use the loader, press the purple button on the left to open the .hex file you wish to load.
Next, press the button in the middle with the green arrow pointing downwards to load the file to
the keyboard. Finally, you can press the third button with the green arrow pointing to the right to
reboot the keyboard. [NOTE - you will have to unplug the Mathkeeb and plug it back in to turn it
back on]
You should now be able to use your mathkeeb with the newly loaded .hex file! If you are still
having trouble loading a custom hex to the keyboard, please see the PJRC website for help.
https://www.pjrc.com/teensy/
4

Custom Firmware
We recognize that the firmware included with Mathkeeb and provided on our website may
not cover the needs of all users. To remedy this, we have made available certain files that you can
use, with a little work, to modify or create new firmware for Mathkeeb. In this guide, we discuss two
methods to create new firmware .hex files for Mathkeeb. Which one you use will depend on your
operating system, user needs, and your level of comfort with programming in C.
Method 1: Online Firmware Creator
This method involves using the Keyboard Firmware Builder by Ruiqi Mao, which can be
found at https://kbfirmware.com/. We recommend using this method in the following cases:
1. You are using the Windows version(s) of Mathkeeb’s firmware
2. You are not using the Windows version(s), but are OK with losing functionality of any
Unicode macro keys (on the Linux firmware, these are the keys which type π, Π, Σ, and ±)
3. You do not need any other features which are unavailable in the Keyboard Firmware
Builder
Why these recommendations? The Linux/MacOS version of Mathkeeb’s firmware types certain
symbols using Unicode input. This option, while supported by the TMK firmware base, is not
available on the Keyboard Firmware Builder site. The Windows version does not use Unicode input
- instead, it types the symbol’s Alt code, which is unique to the Windows operating system and does
not require any special modifications in the source code.
In the online web tool, you can upload a specially formatted .json file containing the
keyboard’s layout, or start from scratch. To make modifying Mathkeeb’s layout easier, we’ve
included the necessary .json file in the .zip package for the Windows firmware versions, which can
be downloaded on our website (on the same page you found this very guide).
NOTE: A .json is NOT included with the Linux/MacOS Mathkeeb firmware packages for the reason
described above. Linux/MacOS users who wish to create new firmware using the online tool will
need to download the Windows firmware package in order to get the .json file.
Upon uploading Mathkeeb’s .json file to the Keyboard Firmware Builder site, you will see a screen
like the image below:
5

PLEASE DO NOT change any settings on the ‘WIRING’ or ’PINS’ tabs unless you know what you are
doing! This should never be necessary!
To edit the layout of your keyboard simply go to the ‘KEYMAP‘ section and click which keys you
wish to swap. Please note what the key is configured to do! If you are relocating a key that says
‘macro’ the new key must be set to use the same macro. Modifying macros can be done with ease
under the ‘MACROS’ section.
When you are finished modifying the layout of your keyboard, modifying macros, etc, navigate to
the ‘SETTINGS’ tab. Here you can rename your new layout and download a new .json file using the
‘Save Configuration’ button. NOTE - always save your .json file! It will be required if you wish to edit
your current layout in the future!
After saving your layout, the new .hex file can be downloaded from the ‘COMPILE’ section. If you
want to later add functionality not available on the Keyboard Firmware Builder site, you can
download your layout as .zip, which will include the source code used to compile the .hex (see
Method 2 for more information on this source code).
CONGRATULATIONS!!  - You now have a firmware with your very own Mathkeeb layout! To
see how to load this firmware onto your keyboard, please see Chapter 3 - Programming.
6

Method 2: Compiling a .hex from source
This method is a bit more involved, especially on Windows. We recommend compiling from
source in the following cases:
1. You want to create new firmware retaining Unicode input or other functionality supported
by TMK but not by the Keyboard Firmware Builder site
2. You are familiar with C and/or Makefiles, including the necessary dev tools
3. You are curious what the source code used to create Mathkeeb’s firmware looks like
Before modifying any Mathkeeb keymap files you will need to set up a development
environment. Linked below is the documentation website for TMK, the open-source firmware
builder tool on which Mathkeeb and many other custom keyboards are based.
https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/build.md
Click this link and follow Step 1: Install Tools. After doing this, you should have the necessary
“toolchain” to compile a .hex for Mathkeeb. Note that the Mathkeeb does use the PJRC Teensy, and
you will need the Teensy Loader to flash any new .hex files onto Mathkeeb (this is covered in the
“Reprogramming” section above).
You do not need to bother with Step 2, as all of the source files for Mathkeeb are provided as a .zip
on the advanced users page of our website. All you need to do is download and extract this .zip to a
location of your choice.
NOTE: You should avoid working in a directory that has spaces in the file path (e.g. “Program Files”)
as this can cause problems. Stick to a path like C:\Users\Apogee\... instead.
For most changes that you might want to make to Mathkeeb’s layout, you will need to open
and edit one of the keymap.c files. Which one you choose will depend on your operating system: the
keymap.c located in the ‘windows’ folder has macros for Alt codes, whereas the one in the ‘linux’
folder has macros for Unicode input.
First, open the keymap.c file in your text editor of choice. You should see something similar to the
figure below. What you are looking at is each layer of Mathkeeb, expressed as a matrix of keycodes.
You will notice that the default firmware only uses the first 8 layers, although TMK supports a
maximum of 32 layers.
7

Screenshot of one of Mathkeeb’s keymap.c files, using VSCode
There are different types of keycodes:
●Ones beginning with “KC_” are letters or symbols that would appear on a normal keyboard
○KC_TRANS indicates that the key is ‘transparent’, and will not do or type anything
when pressed
8

●Those using “M( )” are macros, which are identified by a number and defined in the
keymap.c file below the layer matrices
●Other functions include “LT( )” which toggles a particular layer when held, and “TO( )”
which switches to a particular layer
●A more complete list of valid keycodes and functions can be found here:
https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/keymap.md
The same keymap.c file, showing some of the macro definitions
Macros are defined in the switch statement after the layer matrices. Inside the “MACRO( )” call,
provide a comma-separated list of the actions you want to be executed by the macro, in the order
you want them to be executed. Defining macro actions works a little differently from how the layer
matrices were defined above:
●“T( )” indicates a key which is typed once
9