Build your 11-Key Mechanical Macropad

Eleven satisfying keys, one tiny board and a handful of solder joints. That's all it takes to give yourself one-tap mute, volume, copy-paste, screenshots, or whatever you use most. If you've never soldered before, this is a friendly first project: every joint is big, accessible and repeated eleven times, so you'll be confident by key three.

Which version do you have? - DIY kit: follow every step. - Assembled: switches are soldered and the firmware is installed. Press on the keycaps (Step 7), snap on the cover, then go to Customise your keys. - Fully built: plug it in and start clicking. Your keymap is already loaded.

What's in the box

| Item | Qty | |---|---| | Printed case (switch plate), snap-on bottom cover, keycaps | 1 + 1 + 11 | | Seeed Studio XIAO RP2040 board | 1 | | Gateron G Pro 3.0 Yellow linear switches | 11 + spares | | Hook-up wire (red and black), solder | 1 each | | USB-C cable | 1 |

Tools you'll need

• Soldering iron (25–60 W; temperature-controlled is ideal, around 330 °C) with a stand and a damp sponge or brass wool
• Wire stripper or a sharp craft knife, and small side cutters
• Tweezers or a "helping hands" clip (optional, very handy)
• A computer with a USB port

Safety notes

• The iron tip is around 330 °C. Always return it to its stand, never touch the metal and keep the cable clear of your hand.
• Work somewhere ventilated and don't breathe the solder smoke. A small fan blowing across (not at) the work is enough.
• Wash your hands after handling solder.
• Eye protection is a good idea when trimming wires, because cut ends can fly.
• Children should solder only with an adult at their side.

Step-by-step build

1. Fit the switches

Push each switch into the case from the top until both clips click. The two metal pins should point toward the back of the case (towards the USB opening), and all eleven should face the same way. Press firmly on the switch housing edge, not the stem.

2. Seat the XIAO

Turn the case over. Press the XIAO onto its little printed pegs with the USB-C port lined up with the hole in the back wall, and the RGB LED facing the side window. Plug the USB-C cable in once to check the fit, then unplug.

3. Plan your wires

Each switch has two pins. In this guide, pin 1 is the pin nearer the case's left edge and pin 2 the other one. It doesn't matter electrically, but staying consistent makes checking easy.

• Pin 1 of each key gets its own red wire to a XIAO pin (table below).
• Pin 2 of every key joins one black wire that daisy-chains along all eleven and ends at the XIAO's GND pin.

4. Solder the ground chain

Strip about 5 mm of insulation at points along a length of black wire, so you have one bare section above each switch's pin 2. Tin each pin with a touch of solder, then lay the bare section on it and reheat until the solder flows. Work row by row and finish at the XIAO's GND pad.

5. Solder the signal wires

Cut eleven red wires to length, leaving a little slack, and strip about 3 mm at each end. Solder one end to pin 1 of each key, then the other end to the XIAO pin shown below. Tin the XIAO pads first; a quick, clean touch is better than holding the iron there.

6. Check your work

Look for shiny, volcano-shaped joints. Make sure no stray solder bridges two XIAO pads and no bare wire touches another.

7. Firmware, then keycaps and cover

Install the firmware (next section), test every key, then push the keycaps onto the stems and snap the bottom cover on.

Wiring

Key layout, viewed from the top with the USB port at the back:

K1  K2  K3
K4  K5  K6  K7
K8  K9  K10 K11

| Key | XIAO pin | Default action | |---|---|---| | K1 | D0 | Mute | | K2 | D1 | Volume down | | K3 | D2 | Volume up | | K4 | D3 | Previous track | | K5 | D4 | Play / pause | | K6 | D5 | Next track | | K7 | D6 | Copy | | K8 | D7 | Lock screen | | K9 | D8 | Screenshot / snip | | K10 | D9 | Undo | | K11 | D10 | Paste | | all pin 2s | GND | shared ground |

The firmware switches on the RP2040's internal pull-up resistors, so you need no diodes and no other components.

Firmware flashing

We use CircuitPython, which lets you edit the keymap like a text file.

1. Install CircuitPython: download the latest stable .uf2 for the Seeed Studio XIAO RP2040 from <https://circuitpython.org/board/seeeduino_xiao_rp2040/>.
2. Hold the XIAO's tiny B (boot) button while plugging in the USB-C cable. A drive called RPI-RP2 appears. Drag the .uf2 onto it. The board restarts as a drive called CIRCUITPY.
3. Add libraries: download the Adafruit CircuitPython Library Bundle matching your CircuitPython version from <https://circuitpython.org/libraries>. Copy the `adafruit_hid` folder and `neopixel.mpy` into CIRCUITPY/lib/. HID library source: <https://github.com/adafruit/Adafruit_CircuitPython_HID>.
4. Add our code: copy docs/firmware/code.py from this project onto CIRCUITPY, replacing the file that's there.
5. Open code.py in any text editor and set OS = "windows", "mac" or "linux". Save. The pad restarts automatically and the LED glows blue.

Testing

1. Open a text editor and press K7 (copy) and K11 (paste) on some selected text.
2. Play a song or video and try K1–K6.
3. Press each key and watch the LED flash orange. If one key does nothing, see Troubleshooting.

Customise your keys

Edit the KEYMAP list in code.py. Each line is one key, from K1 to K11:

• ("media", CC.VOLUME_INCREMENT) sends a media key
• ("keys", (MOD, K.SHIFT, K.T)) sends a shortcut (MOD is Ctrl on Windows/Linux and Cmd on Mac)
• ("text", "Thanks, talk soon!") types a phrase

Save the file and the pad updates instantly.

Troubleshooting

| Problem | Try this | |---|---| | No CIRCUITPY drive | Re-do step 2 of flashing while holding B, and try a different cable (some cables are charge-only). | | LED doesn't light, keys don't work | Check adafruit_hid and neopixel.mpy are inside CIRCUITPY/lib. Connect with a serial console (e.g. the Mu editor) to see error messages. | | One key dead | Reflow that key's two joints and check its red wire goes to the right pin. Swapping in a spare switch rules out a faulty switch. | | Several keys dead in a row | A break in the black ground chain. Reflow the joint just before the first dead key. | | A key repeats or triggers others | Look for a solder bridge between neighbouring XIAO pads. | | Mac shortcuts wrong | Set OS = "mac" in code.py. |

Credits

• Case and keycap designs by netpaq: "MacroPad – Seeed Xiao RP2040 – 11 keys" (<https://www.printables.com/model/412449-macropad-seeed-xiao-rp2040-11-keys>) and "Cherry MX Keycap – Blank" (<https://www.printables.com/model/397305-cherry-mx-keycap-blank>), both CC BY 4.0. Photos by netpaq, CC BY 4.0. We split the case file into its two parts and laid out 11 keycaps on one plate.
• Firmware code.py written by MyPartLab, MIT licence. It uses Adafruit's CircuitPython HID and NeoPixel libraries (MIT).
• This guide, the wiring diagram and the renders are original MyPartLab material.