ESC/POS Thermal Printer for Home Assistant

Print receipts, labels, QR codes, and more from Home Assistant automations. Connect any ESC/POS capable network, USB, bluetooth, or serial thermal printer and start printing in minutes.

Why Use This?

• Print door access logs, temperature alerts, todo lists, daily reports, or shopping lists automatically
• Works with any $30+ thermal printer (network, USB, Bluetooth, or serial) that supports ESC/POS
• Connects via TCP/IP, USB, Bluetooth, or a serial (UART/RS-232) cable or ESPHome serial proxy
• Set up as many printers as you need and target them individually or broadcast to all
• Direct connection to your printers, no cloud required and everything stays local

Features

• Print text with formatting (bold, underline, alignment, font sizes)
• Print QR codes, barcodes, and images from URLs, files, camera/image entities, or base64 (guide)
• Text effects: boxes, multi-column tables, and custom-font / rotated text (guide)
• Paper feed and cut control
• Paper status sensor (network/USB): automate on paper low / paper out
• Image-print diagnostics sensor: success/failure counts and last-print details for tuning image options (guide)
• Buzzer/beeper support
• UTF-8 text with automatic character conversion
• 35+ printer profiles with automatic feature detection, plus 23 rebadged/clone models available directly as "(compatible)" dropdown entries
• Guided calibration wizard: prints test pages to measure image implementation, paper width, columns, and codepage, then saves them for you (guide)
• Device page offers Feed / Cut / Beep / Sample test print buttons, and new printers get a Settings → Repairs suggestion linking to the calibration wizard
• Full UI configuration, no YAML required

Quick Start

Requirements

• Home Assistant 2026.5 or later (serial support needs the SerialPortSelector introduced in HA 2026.5, and the integration tracks HA core's bundled Pillow / dbus-fast pins; 0.4.x of this integration still works on HA 2024.8+ if you're stuck there)
• Thermal printer with ESC/POS support (most receipt printers)
• Network printers: Accessible on your network (typically port 9100)
• USB printers: Connected directly to your Home Assistant host (requires libusb)
• Bluetooth printers: Linux host with kernel AF_BLUETOOTH support; printer paired on the host before adding to HA. See Bluetooth printers.
• Serial printers: Linux host with serial port access (dialout group); or use an ESPHome serial proxy over the network. See Serial printers.

Install via HACS

This integration is in the HACS default store. No custom repository needed.

1. Open HACS in Home Assistant
2. Search for "ESC/POS Thermal Printer" and install it
3. Restart Home Assistant

Configure Your Printer

1. Go to Settings > Devices & services > Add Integration
2. Search for "ESC/POS Thermal Printer"
3. Select your connection type:
   • Network: Enter your printer's IP address and port (default: 9100)
   • USB: Select from auto-discovered printers or enter VID:PID manually
4. Select your printer model, or "Generic (no profile)" if it isn't listed
5. Done! Your printer is ready to use

Note: USB printers may be auto-discovered when connected. Check your Home Assistant notifications.

Automatic discovery

Every network printer setup or reconfigure asks the printer to identify itself (ESC/POS GS I); Epson printers typically answer with their real model name, which fills in the device page. Printers that don't answer are configured exactly as before.

Epson TM-series and Rongta network printers additionally announce recognizable DHCP hostnames; Home Assistant will offer to set them up automatically when they appear on your network (Settings → Devices & Services → Discovered), with the host prefilled and the matching profile preselected. Manual setup still runs the GS I query, but the profile dropdown is already on the same form when you submit it, so there's no discovered result yet to preselect a profile from — you pick the profile yourself, same as before. Discovered printers are tracked by MAC address, so a DHCP lease change updates the existing entry instead of offering a duplicate.

Upgrading? Printers configured before this feature pick up their detected model the next time you run Reconfigure on the entry.

Basic Examples

Print a Message

service: escpos_printer.print_text
data:
  text: "Hello from Home Assistant!"
  align: center
  cut: partial

Print a QR Code

service: escpos_printer.print_qr
data:
  data: "https://www.home-assistant.io"
  size: 8
  align: center
  cut: partial

Target a Specific Printer

When you have multiple printers, use target to pick which one:

service: escpos_printer.print_text
target:
  device_id: your_printer_device_id
data:
  text: "Sent to a specific printer"
  cut: partial

Since 1.2.0 the print services use Home Assistant's standard target picker, so you can also target entities, areas, floors, or labels — and the services appear in the entity/device "Add to… → Create as a new action" pickers. The device_id form above (and device_id passed directly in data:) keeps working unchanged; existing automations need no migration.

To print to every configured printer at once, set broadcast: true in data. (Omitting the target entirely also broadcasts, kept for backward compatibility, but logs a warning when more than one printer is configured — this implicit fallback is deprecated and will be removed in 2.0.0.)

Print a Bordered Header

service: escpos_printer.print_box
data:
  text: DAILY REPORT
  style: auto         # → single-line ┌─┐ on CP437; ASCII otherwise
  padding: 1
  align: center
  feed: 1

Print a Receipt-Style Table

service: escpos_printer.print_table
data:
  rows:
    - ["Item", "Qty", "Price"]
    - ["Coffee", "2", "$6.00"]
    - ["Bagel",  "1", "$3.50"]
  style: single
  header: true
  column_aligns: ["left", "center", "right"]

Print Receipt Totals (Label/Value Pairs)

service: escpos_printer.print_kvtable
data:
  items:
    - ["Subtotal", "$10.00"]
    - ["Tax",      "$0.80"]
    - ["Total",    "$10.80"]

See the Text effects guide for the full reference (boxes, tables, kv-tables, separators, custom-font / rotated text via print_text_image, and the previewing workflow). For ready-to-import scripts and automations see the Blueprints directory.

Available Services

Service	Description
escpos_printer.print_text	Print formatted text in the device encoding
escpos_printer.print_text_utf8	Print UTF-8 text with automatic character conversion
escpos_printer.print_message	Print formatted message via notify entity (supports all text formatting + UTF-8)
escpos_printer.print_qr	Print QR codes
escpos_printer.print_barcode	Print barcodes (EAN13, CODE128, etc.)
escpos_printer.print_image	Print images from URL, file, camera/image entity, or base64. See Images guide
escpos_printer.print_image_url	Focused convenience service for HTTP(S) URLs (UI gets a URL field). See Images guide
escpos_printer.print_image_path	Focused convenience service for local file paths. See Images guide
escpos_printer.print_camera_snapshot	Print a live snapshot from a camera.<id> entity (UI gets an entity picker)
escpos_printer.print_image_entity	Print the current frame from an image.<id> entity
escpos_printer.print_box	Wrap text in a printable border (cp437 / ASCII / asterisk / hash). See Text effects guide
escpos_printer.print_table	Print multi-column rows (receipts, logs). See Text effects guide
escpos_printer.print_kvtable	Print two-column label/value pairs (receipt totals, sensor readings). See Text effects guide
escpos_printer.print_separator	Print a single decorative rule (line of repeated characters)
escpos_printer.print_text_image	Render text with a TTF/OTF font and optional 90/180/270° rotation. See Text effects guide
escpos_printer.preview_image	Run the image pipeline and write the resulting 1-bit PNG to disk (no paper). See Images guide
escpos_printer.preview_box	Render a print_box layout to a .txt file (no paper)
escpos_printer.preview_table	Render a print_table layout to a .txt file (no paper)
escpos_printer.calibration_print	Print a ruler + threshold sweep strip so you can pick dither/threshold without burning a roll
escpos_printer.feed	Feed paper
escpos_printer.cut	Cut paper
escpos_printer.beep	Sound the buzzer

Supported Printers

This integration works with any printer supported by python-escpos, including:

• Epson TM series (TM-T20, TM-T88, TM-U220, etc.)
• Star Micronics (TSP100, TSP650, TSP700, etc.)
• Citizen (CT-S2000, CT-S310, CT-S601, etc.)
• Most generic 58mm and 80mm thermal receipt printers

Bluetooth (RFCOMM) printers

Cheap thermal printers (Netum, MUNBYN, POS-58 generics, Phomemo Classic line, etc.) connect over Bluetooth Classic / RFCOMM. Pair the printer on the host first, then add it in HA; the integration opens a raw RFCOMM socket to an already-paired device but does not handle pairing itself. Bluetooth Classic is plaintext by default, so don't route sensitive content (OTPs, 2FA codes, door logs) to a BT printer.

See docs/bluetooth.md for the full pairing walkthrough, container deployment notes, the socat host-bridge fallback, and security considerations.

Serial (UART/RS-232) printers

For printers connected via a physical serial cable or a network-based serial proxy. Supports direct device paths (/dev/ttyUSB0), ESPHome UART proxies (esphome://host:port), RFC2217 serial servers, and raw TCP sockets. On Linux, the HA user needs to be in the dialout group.

See docs/serial.md for setup instructions, ESPHome YAML examples, write-chunking options for ESP32 buffer overruns, and troubleshooting.

Blueprints

The blueprints/ directory ships 13 ready-to-import Home Assistant scripts and automations that exercise the text-effects services. They cover the common day-to-day workflows so you don't need to write YAML from scratch.

Blueprint	Type	Use case
Shopping List	Script	Print a todo entity as a bordered grocery list.
TODO List	Script	Generic todo printer: any list, optional completed items, optional numbering.
Daily Agenda	Automation	Print today's calendar events at a fixed time each day.
Weather Forecast	Script	Print an N-day forecast table.
Receipt	Script	Itemised receipt with subtotal / tax / total.
Recipe Card	Script	Kitchen card: name, servings, ingredients, numbered steps.
Guest Wi-Fi QR	Script	Print a scannable Wi-Fi join QR code for guests.
Sensor Alert	Automation	Print a bordered alert when a sensor reaches a target state.
TODO Item	Automation	Print a card per item added to a todo entity (fridge-printer style).
TODO Ticket	Automation	Print a ticket (with QR) per item added to a todo entity.
Doorbell Snapshot	Automation	Print a camera snapshot when the doorbell is pressed.
Morning Briefing	Automation	Print a combined weather + agenda briefing each morning.
Trash Reminder	Automation	Print a bin / recycling reminder on collection eve.

See blueprints/README.md for import instructions, per-blueprint inputs, and troubleshooting notes.

Documentation

Document	Description
Installation	HACS / manual install, removal
Configuration	Common settings reference (codepage, line width, defaults)
Calibration	Guided wizard that measures and saves your printer's settings
Network printers	TCP/IP setup
USB printers	USB setup, permissions, container pass-through
Bluetooth printers	Pairing, RFCOMM, container caveats
Serial printers	Serial/UART setup, ESPHome proxy, write chunking
Services	Service parameter reference
Images	Image printing: sources, processing, reliability, recipes
Text effects	Boxes, multi-column tables, and custom-font / rotated text
Automations	Automation examples
Notifications	Notify entity and print_message service
Multi-printer targeting	target: blocks, area / entity / device targeting
Limitations	Known limitations
Troubleshooting	Common issues and solutions
Contributing	Contributing, testing, and local development
Contributors	People who have contributed to this project

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

MIT License - see LICENSE for details.