Esp32-access control reader

esp32-access-control

An open source, ESP32-based Wiegand reader: a board, ESPHome firmware and a 3D-printable case.

At PDX Hackerspace we used RFID keys to unlock doors and access our laser cutter. We want to expand their use, to make it easy for members to print parking permits for projects, unlock the main entrance for events, claim prints on 3D printers and more. We currently use Raspberry Pis for the doors and an ESPKey for the laser cutter; this project can provide a low cost simple way to integrate with Wiegand RFID readers and possibly as the basis for replacing the aging Raspberry Pis controlling our doors.

AI disclosure: This project was written by AI under human oversight, following these rules.

What's here

Technical details

Hardware:

• dual level-shifted 5V Wiegand interfaces with wiring for data (D0, D1), LED and beep along with power
• ESP32-S3-N16R8: ESP32-S3 with 16MB of flash and 8MB of octal PSRAM (GPIO35-37 are used by the PSRAM and unavailable)
• USB C port
• power and data LEDs
• Qwiic connector for I2C devices
• header for SPI TFT displays with touch controllers
• "aux" header for satellite boards with optional power to this board

Connectors, from BOFFF.md:

I2C: SDA and SCL on J3, with 4.7k pull-ups to 3.3V. The board carries no I2C devices of its own.

examples/simple.yaml and examples/access-control.yaml wire one reader on D0 = GPIO18, D1 = GPIO17, reader LED = GPIO16 (active low) and beeper = GPIO15 (active low). Check these against the schematic before relying on them. The board has no relay output; packages/door-relays.yaml is an example for a relay or strike driven from the J1 aux header or a satellite board. examples/access-control.yaml uses GPIO38 and GPIO39 (J1) as example values; set door_relay_1_pin and door_relay_2_pin for your own hardware.

Using the packages from another project:

external_components:
  - source: github://romkey/esp32-access-control@vX.Y.Z
packages:
  access-door: github://romkey/esp32-access-control/packages/access-door.yaml@vX.Y.Z

See docs/configuration.md for the substitutions each package takes.

Datasheets: TXS0108E level shifter, WAGO 2601-1106 terminal block.

Building

Requires Docker. Nothing else needs installing.

cp examples/secrets.yaml.example examples/secrets.yaml   # then edit it (generate a real api key)
docker compose run --rm validate      # esphome config on every example
docker compose run --rm build         # compile every example
docker compose run --rm lint          # all pre-commit checks, like CI

The first build downloads the toolchains into a Docker volume; later builds reuse them and only recompile what changed.

The case is built separately with OpenSCAD: make -C case. See case/README.md.

Flashing

To flash a new board, build the firmware images:

docker compose run --rm firmware

Then open https://web.esphome.io in Chrome or Edge, connect the board over USB and upload dist/<name>.factory.bin. After that, update over the network (OTA). The images contain your Wi-Fi credentials; don't share them.

Case

case/ has an OpenSCAD design for a 3D-printable wall or desk kiosk, in portrait and landscape layouts. It holds the board, a 3.5" or 4.0" SPI TFT, and an HID ProxPoint Plus reader mounted on the front. CI renders the STLs on every change and attaches them to the workflow run. See case/README.md for parts, print settings and assumptions to check.

License

MIT, except the manufacturer datasheets in datasheets/, which belong to their manufacturers and are not covered by this license; see each datasheet's -license.txt.