ESPHome Fingerprint Keypad

I couldn’t find a keypad with the features I wanted for Home Assistant, so I built one with ESPHome.

A while ago I retrofitted an old alarm system with Konnected, which lets you expose the old sensors to Home Assistant and use the Alarmo integration to rebuild the system. It worked great, but using only my phone to control it got a bit annoying.

Picture this You’re coming in or heading out while the system is armed, you open the door, the delay starts, and you’re fumbling for your phone to disarm before it triggers.

Remote access is great, but for everyday use I'd prefer a dedicated controller. This build solves that with a fingerprint sensor for quick local auth, a keypad for PIN entry as fallback, and a status light.

Supplies

Order PCBs from PCB Way ( Get $5 New User Free Credit)

• Keypad PCB → Gerbers
• Keypad BOM → BOM

Parts

• Capacitive Fingerprint Module (R503) Amazon
• Optional Adafruit SGP30 Air Quality Sensor Adafruit
• Optional Adafruit BME680 Sensor Adafruit
• Optional STEMMA QT / Qwiic JST SH 4-Pin Cable Adafruit

Fasteners

• M2 Self-Tapping Screws Assortment Amazon
• Command strips Amazon or Drywall Screws Amazon

Tools

• FDM 3D Printer Bambu Lab P1S
• Filaments (PLA Matte) Bambu Filament
• Electric Precision Screwdriver Set Amazon
• Precision Screwdriver Set Amazon
• Soldering Station/Iron. Amazon
• Helping hands Amazon
• Wire stripper Amazon
• Wire Crimpers
• Heat Shrink
• Flux, Solder
• Flush cutters
• Tweezers, pliers

Affiliate links may be included. I may receive a small commission at no additional cost to you.

Step 1: Watch the Video

In the project video, I walk you through the entire process of designing and building this keypad. Watching it will make the steps below feel familiar and provide practical insights if you're looking to build your own dedicated smart home devices.

Step 2: 3D Print the Enclosure

The enclosure files are located in the project repo on GitHub, or you can export in the format of your choice from the Autodesk Fusion embed.

These parts are straightforward and easy to print. The only thing to keep in mind is the diffuser, which should be printed in white PLA. If you don’t have a multi material setup, you can make a small diffuser plug that friction fits into the black outer shell.

The keycaps are also 3D-printed. I made these particular ones in resin on an older project, but they’re totally doable in FDM. I recommend a 0.08 mm layer height, with the keycaps angled on one of their sides.

Step 3: Electronics

I started with the bottom side of the PCB where most of the SMD parts go. I used a solder paste syringe to put solder on the pads by hand, placed the components, then reflowed that side on a hot plate. You can also do this by hand and that’s what I did for the top side where I placed the four NeoPixels and their caps.

There’s usually some rework to clear bridges and add solder where needed.

⚠️ Note: the diodes need to be soldered the opposite of what's on the silkscreen. I discovered this when the keypad matrix didn’t work on first test. The ESPHome component expects the rows to be outputs and I had wired it the other way. I think you can flip it in the config as well, but it’s cleaner this way.

Step 4: ESPHome Setup

With the SMD parts done, get the ESP ready for first use in Home Assistant. You can check the ESPHome guide.

If it will not enter download mode, hold the BOOT button, press and release RESET, then release BOOT.

Make sure to set up OTA so you can send firmware and changes over the air. When the first-time setup finishes, you should see the device online inside the ESPHome Builder in Home Assistant.

If that’s the case, add this snippet to your ESPHome YAML and click Install to compile and upload.

# Keypad Matrix
matrix_keypad:
id: mykeypad
rows:
- pin: GPIO4
- pin: GPIO5
- pin: GPIO6
- pin: GPIO7
columns:
- pin: GPIO10
- pin: GPIO11
- pin: GPIO12
keys: "123456789*0#"
has_diodes: True
# Key Collector
key_collector:
- id: pincode_reader
source_id: mykeypad
min_length: 4
max_length: 4
end_keys: "#"
end_key_required: True
clear_keys: "*"
allowed_keys: "0123456789"
timeout: 5s
on_progress:
- logger.log:
format: "input progress: '%s', started by '%c'"
args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ]
on_result:
- logger.log:
format: "input result: '%s', started by '%c', ended by '%c'"
args: [ 'x.c_str()', "(start == 0 ? '~' : start)", "(end == 0 ? '~' : end)" ]
on_timeout:
- logger.log:
format: "input timeout: '%s', started by '%c'"
args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ]
# Status Light
light:
- platform: esp32_rmt_led_strip
rgb_order: GRB
chipset: WS2811
pin: GPIO21
num_leds: 4
name: "Status Light"
id: status_light
restore_mode: ALWAYS_OFF

If everything went okay, you’ll see log output after boot. Test the LEDs by changing the light color from the Home Assistant entity directly.

To test the keypad, use tweezers to short the switch pads (as shown in the photos). You should see the corresponding numbers printed in the ESPHome Builder logs.

Step 5: Assembly

I started by soldering a 2 pin right-angle header to the footprint next to the USB-C connector. I’d planned to power the board with a 90 degree USB-C cable but didn’t have one on hand, so I crimped a 2 pin Dupont connector onto a regular USB cable and plugged that into this header.

Next, I dropped the fingerprint sensor into the outer shell and tightened it with the supplied nut. I added the optional environmental sensors using a STEMMA cable, routed the wires around the shell, and fixed the sensors in place with M2 self-tapping screws ⚠️ The switch plate needs to be in before you secure the sensors.

With that done, I set the main PCB in place and secured both the board and the switch plate down with more M2 screws.

Then I snapped the MX switches into the plate and soldered them to the PCB. I also soldered the fingerprint sensor to the UART header and one end of the STEMMA cable to the I2C header.

A few wiring notes:

• UART: TX on the sensor goes to RX on the header, and RX goes to TX.
• Power: The sensor’s red wire goes to the pad labeled PWR.
• Wake: The white wire goes to the 3.3 V pad.
• Touch sense: The blue wire runs to the TS pad;

With the onboard transistor, ESPHome can put the sensor to sleep.

At this point all the hardware is installed and ready for final firmware.

Step 6: ESPHome Firmware

With the keypad powered on and showing up in ESPHome Builder, grab the YAML from GitHub and paste it over the current config. Wi-Fi, encryption, and OTA keys are redacted with !secret variables, so I drop those values into my secrets.yaml (or paste them in directly) using the same credentials used when first flashed the device for first use.

Once ready hit install to update the firmware on the device.

Step 7: Home Assistant Automations

Before setting up any automations, register a few fingerprints. Use the buttons that are now visible on the device page in Home Assistant: click Add, scan the finger twice, and you’re done. From now on, scans give visual feedback: green for a match, red for an unknown print, purple for a misplaced finger.

Once fingerprints are stored and a scan matches, the device fires a Home Assistant event called esphome.fingerprint_authenticated. I created an automation that listens for that event and calls a script that toggles the alarm: if it’s armed it disarms, and vice versa.

The same happens when you enter a 4 digit PIN and press # (bottom right key). That action fires esphome.keypad_code_entered with the PIN as the payload. A second automation grabs that event and calls the same script, passing the PIN along.

Inside the script Alarmo receives the PIN. If the code is for a valid user, Alarmo toggles the system; if not, nothing happens.

The third automation simply watches the alarm state and change the color for light entity in the device to reflect it.

⚠️ Security note:

You can also limit the automations to events coming from a specific device if you want tighter control. Do your own research before relying on this for critical security. All of my "smart" devices live on a separate VLAN that can’t reach the rest of the network. The overall security of this device still depends on how you configure Home Assistant, Alarmo, and your network.

Step 8: Wall Mounting

I mounted the keypad with Command Strips first to test placement for a few days. You can use screws and fix the wall plate permanently if you prefer.

Run the power cable either inside the wall through the opening in the wall plate or straight down through the pass-through at the bottom. In both cases, zip-tie the USB cable to one of the tie points on the wall plate so it can’t tug loose.

When the cable is secured, plug it into the 2-pin header (GND is marked on the silkscreen), snap the keypad assembly onto the wall plate and you’re done.

Step 9: Done

Thank you for sticking around until the end! I'd love to hear your suggestions in the comments below.

I have other ideas and I plan on making more projects like these Follow me for more.

📺 Youtube /@salimbenbouz