RFID Access

From Hive13 Wiki
Revision as of 06:33, 24 March 2021 by Hodapp (talk | contribs) (Minor reorganizing, add Star Trek Door section)
Jump to navigation Jump to search

Hive13 Project
RFID Access System
Status: Active
Start Date: 1/12/2012

2701 Front Door

Currently involved:

  • Hodapp (software stuff, electronics stuff)
  • Drew Kirkman (infra stuff)
  • Chris Davis (hardware stuff)
  • Dave Velzy (hardware stuff)

Right now this is running from a Raspberry Pi 3B+ with Alpine Linux and some software written in Go. This code interfaces with RFID readers over the Wiegand protocol, communicates with intweb to request access for some badge, and listens over HTTP for 'manual' door open requests. The Raspberry Pi was meant as the "temporary" fix, but..... we know how temporary fixes go. The only thing that makes this Raspberry-Pi-specific is that the software relies on a Pi-specific GPIO library (including some interrupt-driven code for the Wiegand protocol). Besides that, anywhere that Go code runs, and that has controllable GPIOs, "should" work.

Code is at: https://github.com/Hive13/HiveRFID

The badge reader is a generic RFID reader that uses the Wiegand protocol. Other types should work. (USB ones exist too, but would require some additions in the software.)

The electric door strike is a HES 5000 from Assa Abloy. (Installation instructions: https://content.assaabloyusa.com/doc/AADSS1009179&.pdf)

The relay board to switch power to the door strike is a HiLetgo, but almost any solution that can let a 3.3 V signal switch 12V at max 200-300 mA should suffice for this.

The Raspberry Pi is using the uctronics PoE hat (not the mini one). This board was chosen because it exposes a +12VDC supply that is ideal for both the RFID reader, which can run from 6-14VDC, and the electric door strike, which can use either 12V or 24V (see HES5000 docs for the peak current rating).

Beep Codes & Diagnostics

The code makes some attempts at communication via the RFID reader itself, which has an LED and a beeper:

  • The RFID reader will light up (a pale purple, on this one) if it is even receiving power.
  • When the software starts, it will quickly beep several times.
  • While the software runs, it will blink the LED at regular intervals.
  • When a badge is scanned:
    • One short beep: Software is not responding, possibly not running. (The RFID reader always responds like this if it has power.)
    • One short beep, one long beep: successful access
    • One short beep, two long beeps: denied access
    • One short beep, three long beeps: some error prevented it from even querying access with intweb (typically network problems or misconfiguration). Check logs for the actual error.

Logs are in /var/log/door_access.log. Older logs are rolled on a weekly basis. Currently, these logs are present in RAM only.


Diagram to follow, eventually.

Make the following connections:

Function RFID reader wire Raspberry Pi pin Level shifter pin
Ground Black (Ethernet: brown pair) GND GND (either)
Wiegand D0 @ 5V logic Green (Ethernet: green) RXI channel 1
Wiegand D1 @ 5V logic White (Ethernet: white/green) RXI channel 2
D0 @ 3.3 V logic BCM 17 RXO channel 1
D1 @ 3.3 V logic BCM 18 RXO channel 2
3.3 V 3.3 V LV
5 V 5 V HV
Beeper (active-low input) Purple (Ethernet: white/orange) BCM 26
LED (active-low input) Grey (Ethernet: orange) BCM 16


  • Raspberry Pi BCM 24 to relay board input (on the board we use, "IN").
  • GND and 5V to relay board's negative and positive, respectively (on the board we use, "DC-" and "DC+").
  • Connect +6-14V power to RFID reader's red wire (the blue pair on the Ethernet cable). The +12V terminal of the uctronics PoE hat works fine for this.

Double-check that D0 and D1 from the reader are always on the high-voltage side (HV) of the level shifter, and that the Raspberry Pi's GPIOs are always on the low-voltage side (LV). For the HW211 level shifter (which is based on the TXS0108E chip), the A side corresponds to LV, and the B side to HV - i.e. connect +3.3V to VA, +5V to VB, D0 and D1 to (for example) B1 and B2, and the Pi's inputs to A1 and A2. Further, the OE pin needs to be tied to VA for the level shifter to work at all.

If you have no level shifter, this also works:

  • Wiegand D0 (green) to BCM 17 through a resistive divider to ground (two 1K resistors)
  • Wiegand D1 (white) to BCM 18 through a resistive divider to ground (likewise two 1K resistors)

The resistive divider is because D0 and D1 use 5V, while the Raspberry Pi runs at 3.3V - so they may damage the Pi if used directly. The divider steps this down to a safer 2.5V. Any kind of level shifter that works similarly should be fine here. The beeper and LED pins do not need their level shifted; they are active-low inputs.

HES5000 at Front Door

The HES5000 electric strike had its wires connected to the Ethernet cable run through the front door frame as follows:

Function (if +12VDC) Function (if +24VDC) HES5000 wire color Ethernet pair
Supply + Supply + Red Orange
Supply + Connect to blue Purple Brown
Supply - Connect to brown Black Blue
Supply - Supply - Red/green stripe Green

The left two columns simply repeat what is in the HES5000 installation manual.

(This was tested to work in the +12VDC mode with the +12V supply from the uctronics PoE hat, and in the +24VDC mode with a ~20V laptop supply.)

Using the strike's +12VDC mode with the uctronics PoE hat and the current relay board, connect:

  • +12V terminal from PoE hat to the relay board's "COM" pin
  • GND terminal from PoE hat to the badge reader's negative supply (i.e. blue and green pairs)
  • Relay board's "NO" (normally open) pin to the badge reader's positive supply (i.e. brown and orange pairs)

Note the other connections to the relay board in the above section.

RFID Reader at Front Door

Likewise, the RFID reader's wires were connected to Ethernet cable, and uses the same mapping as the old space:

Function Scanner wire color Ethernet wire color
Wiegand D0 Green Green
Wiegand D1 White White/Green
Light Grey Orange
Beeper Purple White/Orange
+12V Red Both blues
Ground Black Both browns

Note the connections in the "Wiring" section, and the warnings about the D0/D1 pins. They are 5V logic, so a level shifter is needed to connect them with 3.3 V logic.

DIN Rail

This will be turned to a better diagram at some point, but the tentative wiring used for the Pi on the DIN rail is given below:


A photo of the inside (as of 2020 August) is here:


To do

  • More complete documentation on wiring (suggested: WireViz which works with Graphviz and further could be committed into version control easily)
  • Photographs?

Star Trek Door

Currently a work-in-progress.

Latest blocking issue is that the code doesn't run on the Pi 4 due, possibly, due to [Alpine's version of WiringPi] being quite out-of-date (still 2.46 as of 2021 March); a Stack Overflow post mentions that version 2.52 may be needed.

As WiringPi is no longer updated, we might consider a change to gpiod (for directly in Go) or to directly using the libgpiod interface. These bring some big advantages:

  • They should work on anything with a GPIO chip the Linux kernel supports - not just a Raspberry Pi.
  • They are actually still being updated.
  • They should make it much easier to set up something like a cross-compiling dev environment for Go, as it is no longer tied to a Pi-specific library like WiringPi.

As far as I understand it, libgpiod and the Go library gpiod use exactly the same kernel mechanism.

To do (software)

  • Restricted WiFi backdoor in case intweb goes offline?
  • Back up this Linux image someplace that people can find it easily if needed
  • Migrate away from WiringPi, which is unsupported (see note above on maybe using gpiod/libgpiod)
  • Make better use of beeper and LED?
  • Write clearer instructions for a dev environment, ideally one that isn't Pi-specific!

To do (longer term)

  • Once the updated intweb/HiveWeb is in place, migrate the code to use this REST API instead.
  • Make a newer version with cleaned-up wiring. Perhaps use a balenaFin with PoE and the DIN rail case
  • Make a version that can run on microcontrollers like the ESP8266 or ESP32 rather than a Raspberry Pi. (Dave B. is interested in the electronics for this, possibly in integrating nearly everything into a single board.)

Overview (archived for 2929)

This older section was left in place for the moment. It refers to some work done originally at 2929, some of which was still in use at 2701, but almost all of which is in the process of being updated.


The purpose of this project is to build a modular RFID Access System for all of the tools, doors, and vending machines in the Hive.

  • Requirements
    • Uses the Access Protocol
    • Accepts NFC tags and phones with NFC for access and tracking control (our badges run at 125 KHz)
    • Central database (Postgres, accessed via HTTP, served by a Perl Catalyst app)


What needs to be done

Main Door RFID

  • Battery backup somehow? It's PoE and that's on battery backup.
  • Have it log temperatures

Annex Door RFID

  • Schematic and PCB is on GitHub
  • Battery backup somehow?
  • Motion sensor so it unlocks when you approach it from the inside.
  • Consider switching it to wired for power backup reasons.
  • Add in a mechanical key for when the power's out.

Vending Machine RFID

  • Get compressor being controlled by the Arduino
  • Mount the relay board instead of it being set on a block of wood
  • Clean up the wiring

The Snack Vending Machine has been gutted, its coin validator removed, and RFID card mounted to the machine, however, no work has been done to bring that machine to vending status.

Places it'd be nice to have badge readers

  • Doors out to annex hallway
  • Outside door by the Dumpster
  • Certification-only tools

Enrollment Station

One of the goals of this project is to build a case where cash payments to the hive can be recorded (and membership automatically extended), and cash payments can be automatically made to the card for the purposes of purchasing sodas.

This project is in the planning phase right now -- however, if you want to help, I would appreciate the time and can provide my guidance for this project.


  • The annex uses a WeMos D1 mini.
  • The main door uses an Arduino Mega.

Wiring Diagrams

Scanner to MCU wiring

  • This is correct for the annex door
  • The main door needs to have its wiring changed to match.
Function Scanner Wire Color Ethernet cable wire color
Wiegand D0 Green Green
Wiegand D1 White White/Green
Light Grey Orange
Beeper Purple White/Orange
+12V Red Both blues
Ground Black Both browns