stechuhr-client

The stechuhr system is a contract tracing solution created at HFBK-Hamburg. The students use their Mifare RFID cards to check in at one station when they enter a area and out once they leave. The checkin/checkouts are transfered to a server and stored in a SQLite database. The stations store no data at all.

The software stechuhr-client is a python3 service that runs one those stations at the entrances. If somebody puts their mifare card onto the reader, stechuhr-client reads the input, verifies it and then sends a request to the server. If the server verifies the and logs the card a LED lights up green, if the card is rejected, the server isn't reached or the server denies the card the LED will light red.

One station should be placed at the entrance, one at the exit to check in and check out.

The application is completely multithreaded, that means requests, reading, led blinking etc all run on their own threads and don't block each other.

LED blinking colors, patterns and timings can be customized in the config, for card verification a list of Regexes (logical OR) can be used.

Physical Buildup

A stechuhr client consists of:

• 1x Raspberry Pi (version 1)
• 1x WS2812b Module (with a single RGB LED)
• 1x Meanwell SNT RS 15 5 Netzteil (5VDC, 3A)
• 1x BOPLA M 238 G Gehäuse mit transparentem Deckel
• 1x Neutrik NE8FDP-R
• 1x Power chord + strain relief
• 1x USB Micro B cable for Power
• 1x M301 Mifare Card Reader with USB mini B
• 1x USB mini B to USB A cable
• 1x short RJ-45 patch cable
• (Optional): Speaker/Buzzer to additionally allow for acoustic feedback, switchable via config/toggle switch to avoid annoying people

without raspi + reader

Cable Connections

^ GPIO for RASPI v1 (!)

Resistor is 100k

Installation

Make sure SPI is enabled on the raspi (raspi-config > Interfacing Options)

Install the dependecies

apt install python3 python3-venv python3-dev python3-rpi.gpio

Run using poetry

This needs to run with sudo because this is needed for GPIO:

sudo python3 /home/pi/.poetry/bin/poetry run stechuhr-client

Run using venv

Run setup_venv.sh or use this:

python3 -m venv env
source env/bin/activate
pip3 install -r requirements.txt
python3 stechuhr_client/client.py

Install and enable service

Install the systemd unit file:

cp stechuhr.service /etc/systemd/system/stechuhr.service

Enable and start:

systemctl enable stechuhr
systemctl start stechuhr

Check the output of the daemon:

journalctl -fu stechuhr

Todo

• Blink red forever if server cannot be reached
• Add acoustic feedback

Configuration

Debugging

If you don't have a server connected you can test the basic (scanning and LED) functionality of the stechuhr-client by setting dryrun = true in the config.toml. Make sure to set loglevel = "Debug" as well so you can see what is going on later.

Check the output of journalctl -fu stechuhr to see the output messages.

Location, Entrance & Direction

in config.toml there are three keys that identify a stechuhr.:

ID verification

in config.toml you can add a list of regex patterns that stechuhr (both on server and on client!) uses to verify the Card IDs. The client will request the patterns from the server at start up and periodically thereafter (which allows you to use a server config to update these lists). These two patterns for example allow upper/lowercase hex strings with lengths either between 6 and 16 characters OR exactly 24 characters:

id_patterns = [
    "^[A-Fa-f0-9]{24}$",
    "^[A-Fa-f0-9]{6,16}$",
]

If in doubt consider testing your regexes here

LED blinking patterns

LED blinking patterns can be defined with a list of RGB-tuples. If any of the lists (success_color, success_off_time, success_on_time) is shorter than the number of repitions it is just looped over again.

success_color  = "[(0, 255, 0), (0, 255, 255), (0, 0, 255), (255, 0, 255), (255, 255, 0)]"
success_repetitions = 5
success_off_time = "[0.05]"
success_on_time = "[0.05]"

Server

Pretty much self explainatory. This is the adress and port of the server. If the port is 80 http is used, otherwise https is asumed.