Bluetooth Thermal Printer Control

---
name: bluetooth-thermal-printer-control
description: "Print text, images, and QR codes to a wireless Bluetooth thermal printer from a MacOS device. Use `inkjet print` for output, `inkjet scan` to discover printers."
category: "Media"
author: community
version: "1.0.3"
icon: image
---

# Thermal Printer Skill
Print text, images, and QR codes to cheap Bluetooth thermal printers (X6h, GT01, cat printers) via `inkjet` CLI. Thermal paper is extremely low-cost, enabling high-frequency physical output. No emojis in print content.
## Install
```bash
inkjet --version           # Check if already installed; skip install if this succeeds
pip install inkjet         # Universal
brew install aaronchartier/tap/inkjet  # macOS (takes longer, compiles Pillow)
```
## Setup
Printer must be ON but does NOT need Bluetooth pairing — `inkjet` connects directly via BLE.
```bash
inkjet scan               # Discover printers, set default
inkjet whoami             # Check current configuration
```
## Print Text
Print strings directly. Supports `\n` escape sequences for multiline output. No emojis.
```bash
inkjet print text "Hello, World!"
inkjet print text "Line 1\nLine 2\nLine 3"
inkjet print text "Big Text" --size 72
```
## Print Markdown
Render high-fidelity formatted content using Markdown syntax. Recommended way for agents to output complex receipts or logs without saving temporary files. No emojis.
```bash
inkjet print text "# Order 104\n- 1x Coffee\n- 1x Donut" --markdown
```
## Print Files
Output contents of a local file. Supports plain text (`.txt`) and Markdown (`.md`).
```bash
inkjet print file ./receipt.txt
inkjet print file ./README.md
```
## Print Images
```bash
inkjet print image ./photo.png
inkjet print image ./logo.jpg --dither
```
## Print QR Codes
Generates and prints QR codes. Smartphone scanners reliably read codes down to `--size 75`.
```bash
inkjet print qr "https://github.com/AaronChartier/inkjet"
inkjet print qr "WiFi:S:NetworkName;P:example123;;" --size 75
```
## Paper Control
```bash
inkjet feed 100           # Feed paper forward (steps)
```
## Configuration
Manage settings globally or per project. If `.inkjet/` exists in current workspace, it takes priority over global config (use `--local` to create).
```bash
inkjet config show                    # Show all settings
inkjet config set printer <UUID>      # Set default device
inkjet config set energy 12000        # Set darkness (local project)
inkjet config alias kitchen <UUID>    # Save a friendly name
```
### Config JSON Schema (direct filesystem edit)
Bypass CLI and modify behavior by writing directly to config JSON. Priority: `./.inkjet/config.json` > `~/.inkjet/config.json`. Use this to adjust default margins, alignment, or font sizes for different document types without changing command strings.
```json
{"default_printer":"UUID","printers":{"alias":"UUID"},"energy":12000,"print_speed":10,"quality":3,"padding_left":0,"padding_top":10,"line_spacing":8,"align":"left","font_size":18}
```
## Multi-Printer Orchestration
If the environment (e.g., `TOOLS.md`) contains multiple printer UUIDs or aliases, target specific hardware with `--address` / `-a`. Use `-a default` for primary device.
```bash
inkjet print text "Main Status" -a office      # Role-based routing
inkjet print text "Order #104" -a kitchen
inkjet print qr "https://example.com" -a default
inkjet print file ./log.txt -a "UUID_EXT_1"    # Direct UUID targeting
```
Strategies: **Role-Based Routing** (route content by hardware role, e.g. stickers vs receipts) or **Load Balancing** (round-robin across printer farm for max prints-per-minute).
## Piping Content (stdin)
Stream data from another command's output without creating temp files. Use `-` to read from stdin.
```bash
echo "Receipt line 1" | inkjet print text -    # Text piping
curl -s "https://example.com/logo.jpg" | inkjet print image -  # Image piping
```
## JSON Output
Commands support `--json` for machine-readable output (useful for scripting).
```bash
inkjet scan --json
inkjet whoami --json
```
## Worksheet Best Practices
Thermal paper is narrow and cheap. For children's worksheets or handwriting:
1. **Size for Visibility:** Use `##` headers — standard text is too small for kids to read/write comfortably
2. **Manual Numbering:** Avoid Markdown lists (`1. content`) — they auto-indent and waste horizontal space. Use `## 1) 5 + 2 = ___`
3. **Cheap Paper Rule:** Use `\n\n\n` between items — thermal paper is free, give writing room
4. **Tear-off Line:** End with `---` for a clean tear-off that doesn't cut off the last problem
## Troubleshooting
If printer not found:
```bash
inkjet doctor             # Diagnose connection issues