PS:1 Nametag Printer

Features

1. Members can scan their RFID fobs to get nametags
   1. Uses the "Preferred Name" field, if one is specified
   2. Else, uses the "First Name" field only (for privacy)
2. Custom nametag support via an integrated webserver

Hardware

1. Brother QL800
2. Raspberry Pi 4 Model B (1 GB)
3. 125Khz EM4100 USB RFID ID Card Reader

Prerequisites

Setup your Raspberry Pi:

1. Install Raspberry Pi OS Lite (64-bit)
2. Wi-Fi connection is live
3. SSH access enabled
4. RPi is running

Wild Apricot Credentials

The nametag printer needs to query our membership database to retrieve names based on scanned RFID tags. It authenticates to the API as an external application. If you set up a new microSD card for the printer, you need to copy the app credentials into its environment. This only needs to be done once.

1. You must be an admin for the PS:1 Wild Apricot account
2. Navigate to the Authorized applications page in the dashboard
3. Open the nametag-printer application
4. Copy the "API key", "Client ID", and "Client secret"

If the application was deleted, create a new one. Restrict it to "Read only".

Create a .env file in the root of this repo, wherever you cloned it.

Caution

Do not commit the .env file! It is in .gitignore, so this should be hard to do.

Paste the credentials you copied into the .env file:

WA_CLIENT_ID=""
WA_CLIENT_SECRET=""
WA_API_KEY=""

When you run Ansible, it'll check if this .env file exists and is filled out. If so, Ansible will sync the .env to the RPi, and restart application services.

Ansible

Install Ansible using whatever method. Then, test if Ansible can connect to the printer:

# Always run Ansible commands from the `ansible` subdir
$ cd ./ansible

# Test your connection
$ ansible nametags -a "echo hi"
nametags | CHANGED | rc=0 >>
hi

Our Ansible inventory assumes the following:

• Hostname: nametags
• User: pi

If the RPi has a different hostname or user, update the inventory, or specify -h and/or -u:

ansible -i hostname -u user -a "echo hi"

Run the playbook:

ansible-playbook playbook.yml

This will setup the RPi from a fresh state. It's safe to run multiple times.

Tip

You must run the playbook whenever you want to deploy code updates.

Printer CLI

This application includes brother_ql_next as a requirement. While SSH'd into the RPi, you can use the CLI provided by that package to check on the printer. There's no need to do this, but it's interesting for debugging.

# Change directory to where we deployed the app
cd /app

# Check on the printer status (sudo required)
sudo uv run brother_ql \
    --printer usb://0x04f9:0x209b \
    --model QL-800 \
    --backend pyusb \
    status

Development

Use the uv project manager to work with this project. Sample commands:

# Create a virtual environment and install all dependencies
uv sync
source .venv/bin/activate

# Start the webserver in development mode
python -m nametags.webserver

# Test RFID lookup
nametag lookup <tag_number>

# Test nametag rendering
nametag render "Grade Hopper" --second-line "she/her"

# Test lookup and rendering at once
nametag lookup 0001234567 | nametag render -

If you modify pyproject.toml, run uv sync and commit uv.lock changes.

This repo contains some configs to support VSCode and common tooling:

• .vscode/settings.default.json = Workspace Default Settings for VSCode
• .editorconfig = EditorConfig (extension)
• .flake8 = flake8 (extension)

Acknowledgements

• https://github.com/LunarEclipse363/brother_ql_next
• WaApi.py was provided by Wild Apricot