Sanity Check

The file included with the project bundle zip contains some predefined fake codes. These aren't actual secrets, so nothing is being given away here. The following site can be used to check that everything is working:

The first key on the MacroPad is setup with the site's default secret key of JBSWY3DPEHPK3PXP. So if your RTC is properly setup, then the same resulting 6 digit code should appear on both your MacroPad and the website. If they don't agree, double check that your RTC is synced well with UTC time.

Go back and re-run the RTC setter code if needed.

Also make sure you've adjusted this line of code:

UTC_OFFSET = -4        # time zone offset

to match your local time zone's offset relative to UTC. Good info and global map over on wikipedia:

Also take into account if daylight saving is active since the MacroPad can not determine that automatically. Do this by simply adjusting the UTC_OFFSET value by one hour as needed.

Configuring Keys

To configure the keys, you edit the the file in your CIRCUITPY folder. The example in the project bundle zip you downloaded earlier can be used as guide. Inside, you'll see something like this:

secrets = {
                  # tuples of name, sekret key, color
    'totp_keys' : [("Github", "JBSWY3DPEHPK3PXP", 0x8732A8),
                   ("Discord", "JBSWY3DPEHPK3PXQ", 0x32A89E),
                   ("Slack", "JBSWY5DZEHPK3PXR", 0xFC861E),
                   ("Basecamp", "JBSWY6DZEHPK3PXS", 0x55C24C),
                   ("Gmail", "JBSWY7DZEHPK3PXT", 0x3029FF),
                   None, # must have 12 entires
                   None, # set None for unused keys
                   ("Hello Kitty", "JBSWY7DZEHPK3PXU", 0xED164F),

The main secrets parameter is a Python dictionary. In this example, it only has one entry - the totp_keys entry. This is a list with 12 entries, one per key. You must keep this list length to 12. Each entry is a 3 tuple:

(name, code, color)

with the following contents:

  • name - A string name for the site the key is associated with.
  • code - The secret code the site provided when you set up 2FA.
  • color - The NeoPixel color to use when the key is active.

Here is an example:

("Github", "JBSWY3DPEHPK3PXP", 0x8732A8)

When editing this file, be careful not to accidentally delete any of the square brackets, parans, or commas.  Otherwise you'll end up with a syntax error when the code tries to import the secrets.

Selecting and Sending Code

Selecting codes is easy, just press the key you assigned the code to. The OLED will update to show the code for that site and the NeoPixel under the key will light up the color you set.

If you want the MacroPad to send the keystrokes for the code, as if you typed them on a keyboard, press the knob button down.

Customizable Keys

If you want to have site specific icons for each of the keys, these relegendable key caps are handy:

Get ready to customize your keeb with a 10 pack of two-part plastic keycaps for your next mechanical keyboard or 
In Stock

But these are not required. The site name is shown on the OLED. So that can be used to determine which site's pass code is currently being shown.

To make custom icons, print each out sized to a 17/32" x 17/32" square and cut them out. Removing the clear tops on the relegendable keys is best done with the keycaps mounted on a key switch. Then, just place the printed cutout on the keycap and put the plastic cover back on.

Here are some PDFs you can use to help. One is blank and the second includes some example icons that were used for this guide.

This guide was first published on Jul 19, 2021. It was last updated on Jul 19, 2021.

This page (Code Usage) was last updated on Sep 22, 2021.

Text editor powered by tinymce.