Saturday, July 8, 2023

Build Log: Keycode Access Control for the Fort

 My sons requested a keycode-based access control system for their backyard fort. I'm pretty happy with what we created. In this blog post I'll talk through the details of what we built and why. 

The keypad and custom mounting bracket

Parts List


  • Adafruit Metro ESP32-S2
  • The Adafruit Metro ESP32-S2 is a fairly inexpensive ($20) controller that includes wifi and Adafruit's Qwiic I2C connector system. 


Electronic Lock


  • Fuses (PTC Fuse Resettable Fuses 72V 0.5A 500mA RXEF030 Series)
  • Diodes
  • Qwiic Button



I worked with my friend Peter to develop requirements for the lock. The requirements are written up on github here. In summary, the lock: 
  1. shall not allow a child to get stuck
  2. shall be resistant to critters/teenagers
  3. shall not require physical keys
The current solution meets all three of these requirements. 

Cyberphysical System Models

This project gave me a good excuse to spend time learning the Assume Guarantee REasoning Environment (AGREE). AGREE is a model-based tool that helps you build and verify an argument for correctness in your architecture. 

This specification, written in the Architecture Analysis and Design Language (AADL) describes a magnetic lock actuator that physically actuates (locks) only when power is applied to the system and the lock gets an actuation signal. The first section, "lock_actuator" describes the desired behavior in terms of assumptions and guarantees. The section section, "lock_actuator.magnetic_actuator" describes the state transitions of a particular lock design. 

This type of reasoning is helpful when thinking through design choices. For example, I considered using a solenoid lock like this version from SparkFun: 

But this kind of lock does not meet the conditions described in my assumptions and guarantees. Namely, (as I verified through bench testing) the SparkFun solenoid lock physically actuates (locks) when power is not applied. Such behavior would violate the requirement, "shall not allow a child to get stuck," because a power loss could cause a child to become stuck in the fort.   

Electrical Architecture

Architecture Figure 1: Electrical System

Electrical Summary

A MOSFET relay with a dedicated 12VDC source controls power to the electronic lock. At Peter's recommendation, both sides of the 12VDC supply are protected with resettable fuses to avoid shorting the system (if, for example, something is wired backward). 

The ESP32 board uses one of its General Purpose Input/Output (GPIO) pins to trigger the relay. Input to the ESP32 comes from two sensors (a button and a keypad) both of which are connected via the I2C protocol using Sparkfun's Qwiic cable system (which I absolutely love). 

Flyback Diode

When the magnetic field of the electromagnetic lock collapses, it can induce a current in the reverse of the normal direction. To avoid damaging the microcontroller, I used a Flyback Diode as described on this page. Normally current flows in the B to A direction (illustrated on the figure), but when the lock's power is disengaged, the collapsing magnetic field induces a current in the A to B direction, making a circuit back through the electronic lock to dissipate the remaining power. 

Physical Assembly

The lock I purchased was intended to by mounted on the interior of a door frame. The fort door is an exterior door, so this mounting approach would not work (the lock would be exposed to weather). To mount the lock entirely inside the fort, I welded a "Z" bracket from two pieces of "L" steel. 

Architecture Figure 2: Installation. After taking this photo I had to shim the steel plate (attached to the black painted steel) so that it made good contact with the magnet.

I installed the microcontroller, relay, and exit button in a standard 2 gang electrical box. 

Architecture Figure 3: Exit button and installation box

My son and I designed the keypad mounting bracket in TinkerCAD (this was great practice for him using a micrometer). You can find the .stl file here

Architecture Figure 4: Mounting Bracket for SparkFun QwiicKeypad

Software Architecture

Architecture Figure 5: Software

The software design is pretty simple. As shown in Architecture Figure 5, the microcontroller simply waits for input from either the keypad or the exit button, storing up keypresses to compare to a saved code, resetting if input times out. 

Development Environment

This was my first time using CircuitPython and the Mu Python editor. Overall I'm still on the fence about CircuitPython. It is certainly convenient once it is working, but the set up process is not as straightforward as I'm accustomed to with Arduino. 

1. Install CircuitPython to Board Flash Memory

  • Download esptool (I used version 4.4)
  • Find ESP32 in my device manager (on Windows this was COM8)
  • Write circuitpython bootloader to flash
    • .\esptool-v4.4-win64\esptool-v4.4-win64\esptool.exe --port COM8 --after=no_reset write_flash 0x0 .\tinyuf2-adafruit_metro_esp32s2-0.12.0\combined.bin
Once CircuitPython is loaded on your board's flash memory, the board will appear as a storage device.

2. Install Mu Editor

You can download Mu here. Overall I'm content with Mu, but the CircuitPython model seems to require I only use a single file, "" which makes version control cumbersome.

3. Install Required Libraries

CircuitPython libraries are not the same as regular Python libraries. You can find many CircuitPython libraries here. Copy the files for the devices you are using from the lib directory of the CIrcuitPython library to the lib directory on your board. For example, I copied sparkfun_qwiickeypad.mpy to the lib directory of my board so that I could do:

import board
import sparkfun_qwiickeypad
i2c = board.I2C()
keypad = sparkfun_qwiickeypad.Sparkfun_QwiicKeypad(i2c)


Access Testing

My kids helped me test the lock - both the entry PIN and the exit button work as desired. We also talked through the emergency protocol if they need to leave the fort and the exit button is not working (just unplug it). 

Power Consumption

I used a KASA wifi power outlet adapter to measure power consumption. It holds steady at about 9 Watts for the lock alone (not including the controller). 

Final Thoughts

I learned a ton doing this project. The practice doing circuit design was particularly valuable, as I made (and corrected) lots of mistakes.