Macropad

Assembly instructions:

Assembly instructions can also be found in a printable form here

Welcome! This guide will show the steps for making a macropad (specifically the macropad rev3) from one of our kits!

Your kit should contain the following:

1. The ESP32S2-This is the microcontroller, which actually talks to your computer
2. The circuit board-This is what connects all the components together, enabling the whole thing to work
3. 3x keyswitches-These are what you actually press to make key inputs
4. Rotary encoder and knob-allows for volume control
5. 3x 1K ohm resistors-Used to get proper current to LEDs. Only required if you want to install LEDs

   

   Parts list!

• We’ll start by installing the switches! Take a switch and align the 4 pins with the holes on the pcb, and press into place. Repeat for all three switches.
  • Next, we’ll solder these into place
  • 
    • To solder, put a little bit of solder into the hot iron, then rest the tip against both of the components you want to connect. After giving them a moment to heat up, slowly feed solder into the the components, until a cone shaped ring of solder surrounds the component.
      • It's best to stop adding solder once the joint's sides have a concave shape; adding too much solder can lead to a brittle joint.
    • For a full soldering tutorial, please watch this quick guide
• Next, let’s install the rotary encoder
  1. First, make sure to bend all the pins until they’re sticking straight out. They sometimes get bent in shipping :/
     • 
  2. Now, place the encoder into the top left of the pcb. One side has 3 pins and the other has 2, so be sure you’re putting the encoder into the side of the pcb with the correct number of holes. Be careful to ensure that the encoder is sticking straight up (perpendicular to the circuit board).
     • 
  3. Now, we can solder all 7 pins on the back of the encoder in place, just as we did for the switches!
• At this point, we’re ready to solder in the controller. Start by putting 2 headers into the top right of the circuit board with the “long side” down.
  • 
    1. Now, you can place the controller itself (the purple board) onto these headers. Make sure that the usb port faces away from the encoder! It should look like this:    
       •                                          
    2. Now, solder all 16 points on this side. It should look something like this: (though your board will have switches)
       • 
    3. To fully connect the controller to the board, you’ll also need to solder the 16 headers on the other side, like so:
       • 
       • Once you have all the connections soldered, the legs of the headers (on the back) should be trimmed. However, it's likely best to get firmware up and running beforehand, in case repairs need to be done.
• Congratulations; that’s all the required soldering to get the board working! LEDs can also be added, but they are optional.
• Now, you can follow the programming guide on the makerspace.cc wiki to get the code up and running!
  • If you’d like to tweak or optimize the code, feel free! The source code can be found here.

Adding LEDs

1. To install LEDs, you'll need 3x 1.8mm LEDs and 3x 1000kΩ resistors.
   • Note: If you're planning on using green LEDs, it's probably better to use 470Ω resistors; otherwise they might be a little dim
2. Start by bending the resistors to a U-shape; they should look like this
   • 
3. Then install them into the holes next to each switch and solder them into place.
   • Note that direction does not matter for resistor installation
     • 
4. Now, we'll add the LEDs; take care during this step, as the direction the LED is installed matters. The longer leg of the LED is positive and the shorter negative.
   1. take an LED, and put it through the small hole in the front of your switch, so that it pokes out the two metal holes on the back of the pcb.
   2. The longer leg should be facing the left side of the macropad. Look to the resistor image above to see the orientation the LEDs need to be installed.
      • 
      • after installation, it should look like this:
      • 
   3. As before, these can be soldered into place from the back

Instructions for Programming the makerspace macropad

If you just made your macropad, you'll need to flash it with the firmware.

1. download the Visual Studio Code
2. Once installed, click on the extension menu (looks like 3-4 cubes stacked on top of eachother)
3. Search for platformio, then install! Select trust this author. This may take awhile, so be patient
4. In the mean time, go to the github page, and download the repo
5. Back in VScode, click the new tab on the left that looks like an ant. you should be greeted with a home screen that has an option for opening an existing project. You want to find this, or a similar option, and use it to open the firmware folder from the repo you just cloned!
6. Once you do this, platformio will automatically start installing dependencies! Wait for these to be done, then plug in your board.
7. Hold down the zero button on the esp32 itself (it's the button next to the usb port labeled 0), then press the reset button.
8. Now, In the bottom row of VScode, press the right arrow button and wait for it to flash
   1. it may say "failed to upload"; this is usually not a big deal, so long as you saw the flashing progress bar a few seconds prior.
9. You should be good to go!

if you've already made, and flashed the firmware, there are only a few steps to reprogram:

1. press the zero button on the esp32. This should stop keys from typing out null when pressed.
2. after ~5seconds, pressing key 1 should cause an address to be typed in; specifically 192.168.1.1
3. Now, go to your wifi settings, and connect to the new network that's appeared (likely named macropad or macropad-config, unless you manually renamed it)
   1. unless changed, the default password for this network is just "password"
4. open any web browser (while connected to this network) and type in the address 192.168.1.1 (or just press key 1)
5. this should take you to the programming page! now, enter in what you want each key to do, and press submit!

A few notes on configuring the keys:

• With the default firmware, the 3 main keys are set up to do basic keyboard functions and the volume knob does media controls. You can't mix and match functionality between these two groups without manually editing the firmware
• to input modifiers (ie. shift, control, alt), you have to use a strange format
  • Shift = KEY_LEFT_SHIFT, Alt = KEY_LEFT_ALT, Control = KEY_LEFT_CTRL
  • put whatever modifiers you want at the start of your macro, and seperate them with "+++" from the rest of your input
    • for example to send "ctrl+shift+t" I would input: KEY_LEFT_CTRL+++KEY_LEFT_SHIFT+++t
    • modifiers must be at the start of the sequence: KEY_LEFT_CTRL+++t+++KEY_LEFT_SHIFT will not work
• Here's a comprehensive list of every availible special key:
  • KEY_LEFT_CTRL KEY_LEFT_SHIFT KEY_LEFT_ALT KEY_LEFT_GUI KEY_RIGHT_CTRL KEY_RIGHT_SHIFT KEY_RIGHT_ALT KEY_RIGHT_GUI KEY_UP_ARROW KEY_DOWN_ARROW KEY_LEFT_ARROW KEY_RIGHT_ARROW KEY_MENU KEY_SPACE KEY_BACKSPACE KEY_TAB KEY_RETURN KEY_ESC KEY_INSERT KEY_DELETE KEY_PAGE_UP KEY_PAGE_DOWN KEY_HOME KEY_END KEY_NUM_LOCK KEY_CAPS_LOCK KEY_F1 KEY_F2 KEY_F3 KEY_F4 KEY_F5 KEY_F6 KEY_F7 KEY_F8 KEY_F9 KEY_F10 KEY_F11 KEY_F12 KEY_F13 KEY_F14 KEY_F15 KEY_F16 KEY_F17 KEY_F18 KEY_F19 KEY_F20 KEY_F21 KEY_F22 KEY_F23 KEY_F24 KEY_PRINT_SCREEN KEY_SCROLL_LOCK KEY_PAUSE

Legacy steps for reprogramming - As of april 2026, we have moved our firmware to Platformio build system, as it makes for a much more repeatable development and usage experience. If you would like to use the old arduino code and procedure, feel free to look through old commits in the github, and follow the tutorial below.

1. download the arduino IDE
2. In the arduino IDE, go to tools->boards->board manager. Then search esp32 and install the library made by arduino
3. Then go to tools->manage libraries then install the following:
   1. ArduinoJson
   2. StringSplitter
4. press select board, esp32, and select esp32S2 Dev Module
5. go to the github page, and download all the files. Now, open the ino file in the arduino program (you may need to do some renaming-the IDE should do this for you).
6. Now plug in your board, and press the two reset buttons that are on the ESP32 (the purple board) itself; they're located near the usb port. If you're using the makerspace case, there's a hole on the top of the case and next to the usb port. Specifically, you want to hold the top button for ~2s and then press the other key once.
7. Go to tools->port->then select the one with esp32
8. now press the upload button! (it's the right-facing arrow, in the top left)

if you've already made, and flashed the firmware, there are only a few steps to reprogram:

1. press down key 1 (the left key) and the encoder knob at the same time, until key 1 stops sending keypresses
2. after ~5seconds, pressing key 1 should cause an address to be typed in; specifically 192.168.1.1
3. Now, go to your wifi settings, and connect to the new network that's appeared (likely named macropad or macropad-config, unless you manually renamed it)
4. open any web browser (while connected to this network) and type in the address 192.168.1.1 (or just press key 1)
5. this should take you to the programming page! now, enter in what you want each key to do, and press submit!