Thermy

Python library and CLI for X5-10CD thermal printers via Bluetooth Low Energy.

What This Is

A command-line tool and Python library for X5/cat thermal printers. Works out of the box - no code required for basic printing.

Key features:

• CLI tool - Just type thermy --local photo.jpg instead of writing Python scripts
• Google Docs printing - Print public Google Docs directly from URL
• Protocol fixes applied - Uses community-discovered intensity commands for better print quality
• Handles large images - Automatically chunks images to avoid firmware limits

Built because existing libraries required writing code for simple tasks, and had print quality issues we wanted to fix.

Installation

git clone https://github.com/ellinglien/thermy.git
cd thermy
pip install -e .

Usage

CLI

thermy --local photo.jpg         # Print an image
thermy --gdoc YOUR_DOC_ID        # Print a Google Doc (must be public)
thermy --photo                   # Random Unsplash photo to draw
thermy --photo "lighthouse"      # Search Unsplash photos by keyword
thermy --draw                    # Random Unsplash illustration to draw
thermy --draw "cat"              # Search Unsplash illustrations by keyword
thermy --icon "coffee"           # Search Noun Project icons to draw
thermy --battery                 # Check battery level
thermy --help                    # See all options

Python

import asyncio
from thermy import X5Printer

async def main():
    async with X5Printer() as printer:
        await printer.print_image("photo.jpg")

asyncio.run(main())

Environment Variables

Variable	Purpose
THERMY_PRINT_TOKEN	Helpyy auth token (for --journal, --todo)
UNSPLASH_ACCESS_KEY	Unsplash API key (for --photo, --draw). Free at unsplash.com/developers
NOUNPROJECT_API_KEY	Noun Project API key (for --icon). Free at thenounproject.com/developers
NOUNPROJECT_API_SECRET	Noun Project API secret (for --icon)

Protocol Fixes

Applies fixes from rbaron/catprinter#36:

• Uses DEEPEN intensity instead of FADED
• Omits energy commands that reduce darkness
• Chunks large images (firmware ~950 row limit)
• Polls for completion instead of delays

Finding Your Printer

python scan.py  # Find BLE address

Update DEFAULT_ADDRESS in thermy/printer.py with your device address.

Related Projects

• rbaron/catprinter - Python library for cat printers
• NaitLee/Cat-Printer - Multi-platform cat printer app
• catprinter#36 - Protocol fixes discussion

License

MIT - See LICENSE file

Author

Elling Lien (@ellinglien)

Development

This project was developed with assistance from Claude (Anthropic).