RFID Access: Difference between revisions

From Hive13 Wiki
Jump to navigation Jump to search
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Infobox Project
{{Infobox Project
|ProjectTitle=RFID Access System
|ProjectTitle=RFID Access System
|ProjectImage=Image:Arduino-RFID-Door-Lock.jpg|240px
|ProjectImage=Image:RFID-reader-2701.jpg|240px
|ProjectStatus=Active
|ProjectStatus=Active
|StartDate=1/12/2012
|StartDate=1/12/2012
}}
}}


= 2701 Front Door =
=General information=


Currently involved:
Currently involved:


* Hodapp (software stuff, electronics stuff)
*Hodapp (software stuff, electronics stuff)
* Drew Kirkman (infra stuff)
*Drew Kirkman (infra stuff)
* Chris Davis (hardware stuff)
*Chris Davis (hardware stuff)
* Dave Velzy (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 https://github.com/Hive13/HiveRFID]. This Wiki page is meant for details that are particular to the installations here.


Code is at: https://github.com/Hive13/HiveRFID
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 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 [https://wiki.alpinelinux.org/wiki/Alpine_local_backup#Committing_changes 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:
# Disconnect power to whatever door controller's Raspberry Pi you're restoring.
# 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.)
# 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".)
# Download the respective .zip archive for this Raspberry Pi.
# Unzip the .zip archive onto the microSD card.
# 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 | 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: [https://github.com/formatc1702/WireViz 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 [https://www.balena.io/fin/ balenaFin] with PoE and the [https://store.balena.io/collections/accesories/products/modular-din-rail-case-for-balena-fin 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 [https://golang.org/ 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 [https://www.assaabloyesh.com/en/products/electric-strikes/5000-series/ HES 5000 from Assa Abloy]. (Installation instructions: https://content.assaabloyusa.com/doc/AADSS1009179&.pdf)
The electric door strike is a [https://www.assaabloyesh.com/en/products/electric-strikes/5000-series/ HES 5000 from Assa Abloy]. (Installation instructions: https://content.assaabloyusa.com/doc/AADSS1009179&.pdf)
Line 27: Line 126:
The Raspberry Pi is using the [https://www.uctronics.com/tools-and-accessories/pi-accessories/uctronics-poe-hat-5v-3a-for-raspberry-pi-4b-3b-and-802-3af-poe-network-with-cooling-fan.html 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 Raspberry Pi is using the [https://www.uctronics.com/tools-and-accessories/pi-accessories/uctronics-poe-hat-5v-3a-for-raspberry-pi-4b-3b-and-802-3af-poe-network-with-cooling-fan.html 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).


== Wiring ==
The RFID reader is this [https://www.amazon.com/gp/product/B00UX04JDG?psc=1 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.
Diagram to follow, eventually.
Line 34: Line 135:


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


Additionally:
Additionally:


* Raspberry Pi BCM 24 to relay board input (on the board we use, "IN").
*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+").
*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.
*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 [https://www.ti.com/lit/ds/symlink/txs0108e.pdf 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.


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). If you have no level shifter, this also works:
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 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)
*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.
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 ===
===HES5000 at Front Door===


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


{| class="wikitable"
{| class="wikitable"
! Function (if +12VDC)
!Function (if +12VDC)
! Function (if +24VDC)
!Function (if +24VDC)
! HES5000 wire color
!HES5000 wire color
! Ethernet pair
!Ethernet pair
|-
|-
| Supply +
|Supply +
| Supply +
|Supply +
| Red
|Red
| Orange
|Orange
|-
|-
| Supply +
|Supply +
| Connect to blue
|Connect to blue
| Purple
|Purple
| Brown
|Brown
|-
|-
| Supply -
|Supply -
| Connect to brown
|Connect to brown
| Black
|Black
| Blue
|Blue
|-
|-
| Supply -
|Supply -
| Supply -
|Supply -
| Red/green stripe
|Red/green stripe
| Green
|Green
|}
|}


Line 135: Line 238:
Using the strike's +12VDC mode with the uctronics PoE hat and the current relay board, connect:
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
*+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)
*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)
*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.
Note the other connections to the relay board in the above section.


=== RFID Reader at Front Door ===
===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:
Likewise, the RFID reader's wires were connected to Ethernet cable, and uses the same mapping as the old space:


{| class="wikitable"
{| class="wikitable"
! Function
!Function
! Scanner wire color
!Scanner wire color
! Ethernet wire color
!Ethernet wire color
|-
|-
| Wiegand D0
|Wiegand D0
| Green
|Green
| Green
|Green
|-
|-
| Wiegand D1
|Wiegand D1
| White
|White
| White/Green
|White/Green
|-
|-
| Light
|Light
| Grey
|Grey
| Orange
|Orange
|-
|-
| Beeper
|Beeper
| Purple
|Purple
| White/Orange
|White/Orange
|-
|-
| +12V
| +12V
| Red
|Red
| Both blues
|Both blues
|-
|-
| Ground
|Ground
| Black
|Black
| Both browns
|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.
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 ===
===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:
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:


[[File:Wiring.png|400px]]
[[File:Wiring.png|400px|caption]]
 
A photo of the inside (as of 2020 August) is here:


== To do ==
[[File:RFID-reader-electronics.jpg|400px|caption]]


* More complete documentation on wiring
=Star Trek Door=
* Photographs?


=== To do (software) ===
This works much the same as the street door except that the door type is different. Wiring - and most parts - should be otherwise identical.


* Restricted WiFi backdoor in case intweb goes offline
=Overview (archived for 2929)=
* Back up this Linux image someplace that people can find it easily if needed
 
* Migrate away from WiringPi, which is unsupported
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.
* Make better use of beeper and LED?


=== To do (longer term) ===
==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.


* Once the updated intweb/HiveWeb is in place, migrate the code to use this REST API instead.
*Requirements
* Make a newer version with cleaned-up wiring. Perhaps use a [https://www.balena.io/fin/ balenaFin] with PoE and the [https://store.balena.io/collections/accesories/products/modular-din-rail-case-for-balena-fin DIN rail case]
**Uses the [[ Access_Protocol | Access Protocol]]
* 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.)
**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)


= Overview (archived for 2929) =
==Contributors==


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.
*[[User: Greg J Arnold|Greg]]
*[[User:Ian Wilson|Ian W.]]
*[[User:reportingsjr|Jon]]


== Summary ==
==What needs to be done==
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
===Main Door RFID===
** Uses the [[ Access_Protocol | 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 ==
*<s>Battery backup somehow?</s> It's PoE and that's on battery backup.
* [[User: Greg J Arnold|Greg]]
*Have it log temperatures
* [[User:Ian Wilson|Ian W.]]
* [[User:reportingsjr|Jon]]


== What needs to be done ==
===Annex Door RFID===


=== Main Door RFID ===
*Schematic and PCB is on [https://github.com/Hive13/hive13-access-pcb GitHub]
* <s>Battery backup somehow?</s> It's PoE and that's on battery backup.
*Battery backup somehow?
* Have it log temperatures
*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.


=== Annex Door RFID ===
===Vending Machine RFID===
* Schematic and PCB is on [https://github.com/Hive13/hive13-access-pcb 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
* Get compressor being controlled by the Arduino
*Mount the relay board instead of it being set on a block of wood
* Mount the relay board instead of it being set on a block of wood
*Clean up the wiring
* 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.
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 ===
===Places it'd be nice to have badge readers===
* Doors out to annex hallway
 
* Outside door by the Dumpster
*Doors out to annex hallway
* Certification-only tools
*Outside door by the Dumpster
*Certification-only tools


=== Enrollment Station ===
===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.
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.
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 =
=Hardware=
* The annex uses a WeMos D1 mini.
 
* The main door uses an Arduino Mega.
*The annex uses a WeMos D1 mini.
*The main door uses an Arduino Mega.
 
==Wiring Diagrams==
===Scanner to MCU wiring===


== Wiring Diagrams ==
*This is correct for the annex door
=== Scanner to MCU wiring ===
*The main door needs to have its wiring changed to match.
* This is correct for the annex door
* The main door needs to have its wiring changed to match.


{| class="wikitable"
{| class="wikitable"
! Function
!Function
! Scanner Wire Color
!Scanner Wire Color
! Ethernet cable wire color
!Ethernet cable wire color
|-
|-
| Wiegand D0
|Wiegand D0
| Green
|Green
| Green
|Green
|-
|-
| Wiegand D1
|Wiegand D1
| White
|White
| White/Green
|White/Green
|-
|-
| Light
|Light
| Grey
|Grey
| Orange
|Orange
|-
|-
| Beeper
|Beeper
| Purple
|Purple
| White/Orange
|White/Orange
|-
|-
| +12V
| +12V
| Red
|Red
| Both blues
|Both blues
|-
|-
| Ground
|Ground
| Black
|Black
| Both browns
|Both browns
|}
|}


[[Category:RFID]]
[[Category:RFID]]

Revision as of 19:15, 30 August 2022



Hive13 Project
RFID Access System
RFID-reader-2701.jpg
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:

caption

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

caption

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

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