Scryfall Thermal Printer

Prints a random Magic: The Gathering creature by mana value on a thermal printer. This is designed for Momir Basic style play in paper, where you get random creatures of different mana values as your only spells.

This tool:

• Queries Scryfall for a random creature card by mana value.
• Renders a receipt-style image with the art and rules text.
• Prints to ESC/POS thermal printers over USB or network, or saves a PNG for testing.

See the Momir Basic rules here: https://magic.wizards.com/en/formats/momir-basic

Requirements

• Python 3.9+
• A USB or network ESC/POS thermal printer (58mm or 80mm)

Windows setup

1) Install Python

Install Python 3.9+ using one of these options:

• Microsoft Store (simple, auto-updates)
• python.org installer (check "Add Python to PATH")

Verify:

python --version
pip --version

2) Create and activate a virtual environment

A virtual environment keeps this app's dependencies isolated from other Python projects on your machine.

cd scryfall-thermal
python -m venv .venv

Activate it:

.\.venv\Scripts\Activate.ps1

If PowerShell blocks activation, run one of these and try again:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

or for this session only:

Set-ExecutionPolicy -Scope Process Bypass

3) Install the app

pip install -U pip
pip install -e .

4) Test the app (no printer required)

scryfall-thermal --mv 3 --dry-run --output output.png

5) Print to a printer

USB format: usb:0x1234:0xabcd[?intf=0&out=0x02&in=0x81] Network format: net:192.168.1.50:9100

Example:

scryfall-thermal --mv 2 --printer usb:0x04b8:0x0202

If your printer needs explicit USB endpoints (common on some models):

scryfall-thermal --mv 2 --printer usb:0x0525:0xa4a7?intf=0&out=0x02&in=0x81

Raspberry Pi Lite setup (headless)

The steps below assume Raspberry Pi OS Lite (no desktop) and SSH access.

1) Update system packages

sudo apt update
sudo apt upgrade -y

2) Install Python and system deps

sudo apt install -y python3 python3-venv python3-pip

If you are using the Scryfall symbol cache, CairoSVG requires extra system packages:

sudo apt install -y libcairo2 libffi-dev libgdk-pixbuf2.0-0 libpango-1.0-0 libpangocairo-1.0-0

3) Clone and create a virtual environment

git clone <YOUR_REPO_URL>
cd scryfall-thermal
python3 -m venv .venv
source .venv/bin/activate

4) Install the app

pip install -U pip
pip install -e .

5) Test without a printer

scryfall-thermal --mv 3 --dry-run --output output.png

6) Print to a printer

USB format: usb:0x1234:0xabcd[?intf=0&out=0x02&in=0x81] Network format: net:192.168.1.50:9100

Example:

scryfall-thermal --mv 2 --printer net:192.168.1.50:9100

If your printer needs explicit USB endpoints (common on some models):

scryfall-thermal --mv 2 --printer usb:0x0525:0xa4a7?intf=0&out=0x02&in=0x81

Hardware mode (Raspberry Pi 3 B)

Use a rotary encoder and a 2-digit 7-segment display (common cathode) to select mana value and trigger printing.

Default GPIO mapping (BCM numbering):

• Encoder A/CLK: GPIO17

• Encoder B/DT: GPIO18

• Encoder SW: GPIO27

• Segments 3,9,8,6,7,4,1,2: GPIO5, GPIO6, GPIO13, GPIO19, GPIO26, GPIO12, GPIO16, GPIO20

• Digit commons 10,5: GPIO21, GPIO25 Wiring notes:

• The encoder A/B/SW lines should use pull-ups (gpiozero defaults to pull-ups).

• Use 220-330 ohm resistors for each segment line.

• Because this is a bare 2-digit display, you must multiplex the digits.

• Use NPN transistors (e.g., 2N2222) to switch each digit common cathode.

• TIP120 option: emitter to GND, collector to digit common, base to GPIO through ~1k resistor (Darlington NPN low-side switch).

GPIO backend (gpiozero + lgpio):

Newer Raspberry Pi OS versions disable the legacy /sys/class/gpio interface. Use gpiozero with the lgpio backend.

sudo apt install -y python3-gpiozero python3-lgpio

Run once to test:

GPIOZERO_PIN_FACTORY=lgpio scryfall-thermal --hardware --dry-run --output output.png

Run in hardware mode:

scryfall-thermal --hardware --dry-run --output output.png

If you have a printer later:

scryfall-thermal --hardware --printer usb:0x1234:0xabcd

Override pins if needed:

scryfall-thermal --hardware --seg-pins 5,6,13,19,26,12,16,20 --digit-pins 21,25

Run on startup (systemd)

Create a systemd unit file at /etc/systemd/system/scryfall-thermal.service:

[Unit]
Description=Scryfall Thermal Hardware UI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=colefin8
WorkingDirectory=/home/colefin8/scryfall-thermal
ExecStart=/home/colefin8/scryfall-thermal/.venv/bin/scryfall-thermal --hardware --dry-run --output /home/colefin8/output.png
Environment=GPIOZERO_PIN_FACTORY=lgpio
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now scryfall-thermal

Check status/logs:

systemctl status scryfall-thermal
journalctl -u scryfall-thermal -b

Notes

• Default render width is 384px (58mm printers). Use --width 576 for 80mm printers.
• If the printer is not connected, use --dry-run to validate output.
• A symbology snapshot is bundled at src/scryfall_thermal/assets/symbology.json so new clones do not need to fetch the symbol list. PNGs are still downloaded on first use and cached locally. Set SCRYFALL_SYMBOLS_DIR to override the cache directory.
• Refresh the snapshot with: curl -L https://api.scryfall.com/symbology -o src/scryfall_thermal/assets/symbology.json
• Windows: cairosvg needs the Cairo DLLs (for example, install MSYS2 and pacman -S mingw-w64-x86_64-cairo, then add the MSYS2 bin to PATH). Ensure cairo-2.dll is discoverable before running.