RFID Access

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

General information

Currently involved:

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

Code is at https://github.com/Hive13/HiveRFID. This Wiki page is meant for details that are particular to the installations here.

Right now this is running from two 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. No part of this is Raspberry Pi specific; anything that has a Linux-supported GPIO port should work.

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 front door's controller is "janus". The inside door's controller is "juno".

SSH access

See the Hive13's Bitwarden. Find "Door RFID controllers, SSH private key" there. This contains SSH private keys, as well as the internal IP addresses, for the door controllers.

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.

Backups and restoring

Some background: As mentioned, the systems run on Alpine Linux - specifically, in a 'diskless' configuration. In this configuration, Linux runs completely from RAM once booted, and the disk is left read-only - so no changes to the system persist, unless explicitly persisted with LBU. Further, since a Raspberry Pi boots from a FAT partition, the entire system resides in a small collection of files on a FAT partition on the microSD card - that is, it requires no boot sector, hidden bootloader code, special files or file permissions. Making a copy of these files is sufficient to back the system up, and since these files are not modified (outside of LBU), this can be a "live" backup done while the system is running. Reproducing the same collection of files onto another SD card is sufficient to restore the system.

Restoring from backups

Short answer: Get a microSD card with a single empty FAT32 partition. Get the .zip archive from Google Drive. Unzip it onto the microSD card.

Longer answer:

1. Disconnect power to whatever door controller's Raspberry Pi you're restoring.
2. Format a microSD card with a single FAT32 partition. (That's with an MBR partition table, not GPT. If you don't know what that means, you can probably ignore this.)
3. See the following Google Drive link: https://drive.google.com/drive/u/1/folders/0AAorz4S9QyY7Uk9PVA (Access may be restricted, but cto@hive13.org should have access to this whole folder. Folder name is "Door controller Alpine images".)
4. Download the respective .zip archive for this Raspberry Pi.
5. Unzip the .zip archive onto the microSD card.
6. Put the microSD card into the respective Raspberry Pi, and power back on.

Creating backups

Short answer: SSH into the door controller, and copy the entire directory free of /media/mmcblk0p1 off, how ever you feel like it.

Longer answer: (TODO)

MQTT

Some MQTT support was just added. See Mqtt for more information on this, and the HiveRFID repo for more information on configuring the client.

Note that client ID strings for MQTT must be unique (at least with the current broker), or all clients on that client ID will be unable to connect. If adding another door controller, mind this (and keeping topics distinct too).

To do

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

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
• 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.)

How to add another door controller

(Work-in-progress)

Hardware

Very rough list:

• A Raspberry Pi, or some other kind of Linux system that can run HiveRFID and has sufficient (and supported) GPIOs.
• A Wiegand-compatible badge reader, and the necessary electronics to interface with it (e.g. a level shifter to safely turn higher-voltage signals to 3.3 V level for the Raspberry Pi).
• Something you can electrically control access to. (For instance: a relay board, controlling an electric door strike.)

Software

This needs the bare minimum to run HiveRFID. It has only Go as a compile-time dependency, and no run-time dependencies at all (it is built as a static binary).

Configuration

More site-wide:

• The intweb access URL
• Optionally, the MQTT broker, username, and password

Unique to this device:

• An intweb device name, key, and item to access. (These will have to be added into intweb by someone who can.)
• If using MQTT: a unique client ID, and topic names for the badge and sensor

2701 Front Door

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).

The RFID reader is this cheap Amazon one. For whatever reason, we had no success using better-quality HID readers that ostensibly supported Wiegand too.

Wiring

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

Additionally:

• 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:

Star Trek Door

This works much the same as the street door except that the door type is different. Wiring - and most parts - should be otherwise identical.

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.

Summary

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)

Contributors

• Greg
• Ian W.
• Jon

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.

Hardware

• 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