catprint-daemon

A background daemon that watches a Gmail inbox and prints emails on a cat thermal printer over BLE.

Phase 1 — Project setup & printer test

Prerequisites

• Python 3.10+
• Bluetooth enabled on your computer
• Cat printer (GT01, GB02, GB03, or compatible) powered on and nearby

1. Clone this repo and the catprinter library

git clone https://github.com/yourusername/catprint-daemon.git
cd catprint-daemon

# Clone rbaron's catprinter library into the project
git clone https://github.com/rbaron/catprinter.git catprinter_lib

2. Create a virtual environment

python3 -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate         # Windows

3. Install dependencies

pip install -r requirements.txt

macOS note: bleak requires Bluetooth permissions. When you first run a BLE scan, macOS will prompt you to grant Bluetooth access to Terminal (or your IDE). Accept it.

Linux note: You may need to run sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f venv/bin/python) once so bleak can scan without root.

4. Test the printer

python test_printer.py

This script will:

1. Scan for nearby BLE devices advertising a catprinter service
2. Print the found device address/name
3. Send a small test pattern (a checkerboard stripe) to confirm the printer responds
4. Report success or a clear error message

You can also specify a device explicitly if auto-discovery is slow:

python test_printer.py --device GT01
# or with a MAC/UUID address:
python test_printer.py --device 09480C21-65B5-477B-B475-C797CD0D6B1C

Project layout

catprint-daemon/
├── catprinter_lib/      ← rbaron/catprinter (cloned separately)
├── venv/                ← virtual environment (git-ignored)
├── daemon.py            ← main daemon entry point (Phase 2+)
├── gmail_client.py      ← Gmail poller (Phase 2+)
├── renderer.py          ← image + text renderer (Phase 3+)
├── printer.py           ← BLE send wrapper (Phase 3+)
├── state.json           ← tracks printed email IDs (auto-created)
├── config.toml          ← your settings (copy from config.example.toml)
├── test_printer.py      ← Phase 1 printer connectivity test
├── requirements.txt
└── README.md

Troubleshooting

Symptom	Fix
No printer found after scan	Make sure the printer is on and not connected to another device/phone
Bluetooth not available	Enable Bluetooth in system settings; on Linux check bluetoothctl
ModuleNotFoundError: catprinter	Run git clone https://github.com/rbaron/catprinter.git catprinter_lib
macOS permission denied	Go to System Settings → Privacy & Security → Bluetooth → enable Terminal
bleak.exc.BleakError: No adapter found	Plug in a USB Bluetooth adapter or enable BT in BIOS