Keypad

Home Assistant Keypad

A 9-key macro keypad for Home Assistant, running ESPHome. Every key is RGB backlit, and comes in two variants: one that sits on a desk and one that mounts on a wall, with magnets or screws.

Desk variant:

Wall variant:

Discord

Join the Discord if you want to follow along or ask questions: https://discord.gg/4yMsHbQQGn

Waitlist

Want a pre-assembled one instead of building it yourself? Join the waitlist: https://keypad.alex-labs.dev

How to build it

Tools required

• FDM 3D printer
• Soldering iron
• Phillips screwdriver
• 8 mm hollow gasket punch (wall variant only)
• Flush cutters

Note: in the current revision of the board the level-shifter component is really small, and if you are not comfortable with SMD soldering already, you may have issues. Consider having the board populated by your vendor if you're not sure.

Order components

The part names link to a search, so you can pick whichever shop you prefer.

For the wall-mounted variant you also need:

The keycaps I used are these ones, variants B-A1 V2 and W-A2 V2.

The XIAO usually ships with pin headers. You need two 7-pin strips, so keep them.

Order PCB

The board is 53 × 53 mm, 2 layers. Any fab house will work, but these instructions are for JLCPCB.

1. Download gerber.zip. Don't unzip it.
2. Go to jlcpcb.com, click Order now / Add gerber file and upload the zip.
3. Set the options below. Anything not listed is already correct at its default, leave it alone.
4. Save to cart and pick a shipping method at checkout.

Notes:

• 5 boards is the minimum order. You only need one, so you will have spares.
• Colour and silkscreen are cosmetic. Green is the fastest to produce.

Print the enclosure

The STL files are in the enclosure folder. Pick desk or wall depending on the variant you want. The wall variant also needs 4 magnet plugs.

I included an OrcaSlicer project with all the parameters already set: enclosure/keypad-orca-slicer.3mf. It contains both variants, so disable the parts you don't need before slicing.

The parts are designed to be printed in this orientation. Nothing needs supports.

My settings:

If you slice the STL files yourself instead, these are the settings that matter:

IMPORTANT: the top plates and the magnet plugs print at 100% infill, the bottom parts stay at 25%.

Tolerances are tight. If the board doesn't drop into the top shell, your parts have most likely shrunk. Scale them up a little, start with 100.5%, and reprint. In my case the original scale worked fine.

PCB assembly

Do this in exactly this order.

There is a keyswitch "underneath" the ESP32 chip, so you must add the keyswitch before the ESP32.

1. Solder all the SMD components on the PCB

All the SMD parts go on the front side of the board, the switches go on the back later. The photos below show where each part sits.

R1 (330 Ω) and U1 (74AHCT1G125GW), both in the top left corner:

9 × SK6812MINI-E LED:

IMPORTANT: the LEDs go in one orientation only. The package has one corner cut at an angle, and the board has a small triangle printed next to every LED footprint. The cut corner points at the triangle. All 9 LEDs face the same way, so before you solder, check that all nine cut corners point in the same direction.

The LEDs are daisy chained, so a single LED turned the wrong way breaks the chain: that one and every LED after it stay dark.

10 × 100 nF capacitor:

2. Solder the two pin headers

Put the two 7-pin headers into the U2 footprint from the front, pins pointing up, and solder them from the back.

To ensure the USB-C port lines up with the case, ensure the 10-pin headers are flush with the board.

It can be helpful to use the XIAO ESP32 that sits on these headers to align the pins while solderinb, but DO NOT SOLDER THE XIAO ESP32 TO THE HEADERS YET as we need to install the keyswitches.

IMPORTANT: solder the headers to the PCB only. Don't solder the XIAO module onto them yet, it goes on in step 4.

Stop, check your work.

If you're not comfortable in your soldering, now is a good time to test your board out.

Moving beyond this step and attaching the switches locks the board in place and it can be very hard to correct any mistakes after this point.

My XIAO ESP32 module appeared to connect to the pins on the header just being "inserted" into the headers and resting on them, and didn't require I finish soldering it to the headers and lock it in place, yours may or may not work similarly. You can test continuity between a pad and the pin it's supposed to connect to see if this works for you.

If this is the case for you, you can set the module on the headers, and temporarily skip ahead to the steps on how to configure it in esphome and try it manually using the web interface to verify the LEDs work. If you can toggle on the LEDs and they work, this proves almost all the components

If you're stuck - examine the level shifter pins to make sure they are lining up with the pads, it is by far the toughest component. If things still aren't working, you can use the continuity mode of a multimeter and make sure all GND pins on the LEDs are connected to each other, as well as 5V. You can check this out by viewing the PCB layout in KiCad (or KiCanvas can work if you don't use KiCad) and looking for pins labelled GND or VBUS/+5V.

3. Solder the switches

IMPORTANT: install all the switches in the top shell first, then put the PCB in the shell and solder them in place.

Press all 9 switches into the top shell from the inside until they click:

Then drop the PCB onto the switch pins, SMD side up. Each switch has two pins that come through the board, so solder all 18:

4. Solder the controller module

Push the XIAO onto the two headers, with the USB-C connector pointing at the slot in the shell wall, and solder both rows, 14 joints. Trim the header pins with the flush cutters.

Assemble the enclosure

Desk variant

The desk variant is the simplest one. Press the heat-set inserts into the four holes. A soldering iron with a conical tip works well for this.

Then screw the top and bottom parts together with the 4 screws. They go in from the front, between the switches.

Install the keycaps and it's done!

Wall variant

The wall variant uses the same inserts and the same 4 screws to hold the two parts together. On top of that it has 4 beds for the magnets and 4 printed caps that hold the magnets in place.

The beds are the corner holes. The 2 smaller holes in the middle are for the wall screws.

Put the magnets in place and screw the caps in. The caps have a slot, so a flat screwdriver works.

Finally, add the silicone rubber pads on the other side. Punch them out of the silicone sheet with the 8 mm gasket punch.

Build and flash ESPHome

ESPHome is a tool that turns a YAML file into firmware for ESP32 boards, no coding needed. esphome.yaml in this repo is not a whole config, it is only the part that describes the 9 keys and the 9 LEDs. You paste it under the config ESPHome writes for you.

1. In Home Assistant go to Settings → Add-ons → Add-on store, install ESPHome Device Builder, start it and open it.
2. Press + New device, call it keypad and pick Seeed Studio XIAO ESP32C6. It asks for your wifi once and remembers it.
3. Open the new device with Edit, put the cursor at the very bottom and paste the whole contents of esphome.yaml there. Change nothing above it: the generated API key, OTA and wifi blocks are yours, and the file doesn't touch them. See below for what you should end up with.
4. Plug the keypad into your computer with a USB-C cable, press Install and choose Plug into the computer running ESPHome Device Builder. Later updates go over wifi, no cable needed.
5. Home Assistant finds the keypad by itself. Go to Settings → Devices & services and confirm it.

This is what the wizard writes in step 2. Your name, key and hotspot password will be different. Leave all of it alone and paste at the bottom:

esphome:
  name: keypad
  friendly_name: keypad

esp32:
  variant: esp32c6
  flash_size: 4MB
  framework:
    type: esp-idf

logger:

api:
  encryption:
    key: "the key generated for you, don't share it"

ota:
  - platform: esphome

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: keypad Fallback Hotspot

You get 18 entities:

In an automation, trigger on a key entity and branch on its event_type attribute. The hold time is 1 second; change long_press_ms at the top of the config to adjust it.

License

CC BY-NC-SA 4.0. Build it, modify it, share it, but not commercially, and credit the original. See LICENSE for the details and for the third-party footprint libraries used in the KiCad project.