Introduction

Documentation Status Discord Build Status

CircuitPython module for control of various small serial thermal printers.

Dependencies

This driver depends on:

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-thermal_printer

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-thermal_printer

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-circuitpython-thermal_printer

Usage Example

See examples/thermal_printer_simpletest.py for a demo of basic printer usage.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Documentation

For information on building library documentation, please check out this guide.

Table of Contents

Simple test

Ensure your device works with this simple test.

examples/thermal_printer_simpletest.py
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# Simple demo of printer functionality.
# Author: Tony DiCola
import board
import busio

import adafruit_thermal_printer

# Pick which version thermal printer class to use depending on the version of
# your printer.  Hold the button on the printer as it's powered on and it will
# print a test page that displays the firmware version, like 2.64, 2.68, etc.
# Use this version in the get_printer_class function below.
ThermalPrinter = adafruit_thermal_printer.get_printer_class(2.69)

# Define RX and TX pins for the board's serial port connected to the printer.
# Only the TX pin needs to be configued, and note to take care NOT to connect
# the RX pin if your board doesn't support 5V inputs.  If RX is left unconnected
# the only loss in functionality is checking if the printer has paper--all other
# functions of the printer will work.
RX = board.RX
TX = board.TX

# Create a serial connection for the printer.  You must use the same baud rate
# as your printer is configured (print a test page by holding the button
# during power-up and it will show the baud rate).  Most printers use 19200.
uart = busio.UART(TX, RX, baudrate=19200)

# For a computer, use the pyserial library for uart access.
# import serial
# uart = serial.Serial("/dev/serial0", baudrate=19200, timeout=3000)

# Create the printer instance.
printer = ThermalPrinter(uart, auto_warm_up=False)

# Initialize the printer.  Note this will take a few seconds for the printer
# to warm up and be ready to accept commands (hence calling it explicitly vs.
# automatically in the initializer with the default auto_warm_up=True).
printer.warm_up()

# Check if the printer has paper.  This only works if the RX line is connected
# on your board (but BE CAREFUL as mentioned above this RX line is 5V!)
if printer.has_paper():
    print("Printer has paper!")
else:
    print("Printer might be out of paper, or RX is disconnected!")

# Print a test page:
printer.test_page()

# Move the paper forward two lines:
printer.feed(2)

# Print a line of text:
printer.print("Hello world!")

# Print a bold line of text:
printer.bold = True
printer.print("Bold hello world!")
printer.bold = False

# Print a normal/thin underline line of text:
printer.underline = adafruit_thermal_printer.UNDERLINE_THIN
printer.print("Thin underline!")

# Print a thick underline line of text:
printer.underline = adafruit_thermal_printer.UNDERLINE_THICK
printer.print("Thick underline!")

# Disable underlines.
printer.underline = None

# Print an inverted line.
printer.inverse = True
printer.print("Inverse hello world!")
printer.inverse = False

# Print an upside down line.
printer.upside_down = True
printer.print("Upside down hello!")
printer.upside_down = False

# Print a double height line.
printer.double_height = True
printer.print("Double height!")
printer.double_height = False

# Print a double width line.
printer.double_width = True
printer.print("Double width!")
printer.double_width = False

# Print a strike-through line.
printer.strike = True
printer.print("Strike-through hello!")
printer.strike = False

# Print medium size text.
printer.size = adafruit_thermal_printer.SIZE_MEDIUM
printer.print("Medium size text!")

# Print large size text.
printer.size = adafruit_thermal_printer.SIZE_LARGE
printer.print("Large size text!")

# Back to normal / small size text.
printer.size = adafruit_thermal_printer.SIZE_SMALL

# Print center justified text.
printer.justify = adafruit_thermal_printer.JUSTIFY_CENTER
printer.print("Center justified!")

# Print right justified text.
printer.justify = adafruit_thermal_printer.JUSTIFY_RIGHT
printer.print("Right justified!")

# Back to left justified / normal text.
printer.justify = adafruit_thermal_printer.JUSTIFY_LEFT

# Print a UPC barcode.
printer.print("UPCA barcode:")
printer.print_barcode("123456789012", printer.UPC_A)

# Feed a few lines to see everything.
printer.feed(2)

adafruit_thermal_printer.thermal_printer - Thermal Printer Driver

Thermal printer control module built to work with small serial thermal receipt printers. Note that these printers have many different firmware versions and care must be taken to select the appropriate module inside this package for your firmware printer:

  • thermal_printer = The latest printers with firmware version 2.68+
  • thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
  • thermal_printer_legacy = Printers with firmware version before 2.64.
  • Author(s): Tony DiCola

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_thermal_printer.thermal_printer.ThermalPrinter(uart, *, byte_delay_s=0.00057346, dot_feed_s=0.0021, dot_print_s=0.03, auto_warm_up=True)[source]

Thermal printer for printers with firmware version 2.68 or higher.

feed(lines)[source]

Advance paper by specified number of blank lines.

feed_rows(rows)[source]

Advance paper by specified number of pixel rows.

flush()[source]

Flush data pending in the printer.

has_paper()[source]

Return a boolean indicating if the printer has paper. You MUST have the serial RX line hooked up for this to work. NOTE: be VERY CAREFUL to ensure your board can handle a 5V serial input before hooking up the RX line!

inverse

Set the inverse printing mode boolean to enable or disable inverse printing.

justify

Set the justification of text, must be a value of JUSTIFY_LEFT, JUSTIFY_CENTER, or JUSTIFY_RIGHT.

offline()[source]

Put the printer into an offline state. No other commands can be sent until an online call is made.

online()[source]

Put the printer into an online state after previously put offline.

print(text, end='\n')[source]

Print a line of text. Optionally specify the end keyword to override the new line printed after the text (set to None to disable the new line entirely).

print_barcode(text, barcode_type)[source]

Print a barcode with the specified text/number (the meaning varies based on the type of barcode) and type. Type is a value from the datasheet or class-level variables like UPC_A, etc. for convenience. Note the type value changes depending on the firmware version so use class-level values where possible!

reset()[source]

Reset the printer.

send_command(command)[source]

Send a command string to the printer.

set_defaults()[source]

Set default printing and text options. This is useful to reset back to a good state after printing different size, weight, etc. text.

size

Set the size of text, must be a value of SIZE_SMALL, SIZE_MEDIUM, or SIZE_LARGE.

tab()[source]

Print a tab (i.e. move to next 4 character block). Note this is only supported on more recent firmware printers!

test_page()[source]

Print a test page.

underline

Set the underline state of the text, must be None (off), UNDERLINE_THIN, or UNDERLINE_THICK.

warm_up(heat_time=120)[source]

Initialize the printer. Can specify an optional heat_time keyword to override the default heating timing of 1.2 ms. See the datasheet for details on the heating time value (duration in 10uS increments). Note that calling this function will take about half a second for the printer to intialize and warm up.

adafruit_thermal_printer.thermal_printer_264.ThermalPrinter

Thermal printer control module built to work with small serial thermal receipt printers. Note that these printers have many different firmware versions and care must be taken to select the appropriate module inside this package for your firmware printer:

  • thermal_printer = The latest printers with firmware version 2.68+
  • thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
  • thermal_printer_legacy = Printers with firmware version before 2.64.
  • Author(s): Tony DiCola
class adafruit_thermal_printer.thermal_printer_264.ThermalPrinter(uart, byte_delay_s=0.00057346, dot_feed_s=0.0021, dot_print_s=0.03)[source]

Thermal printer for printers with firmware version 2.64 up to (but NOT including) 2.68.

adafruit_thermal_printer.thermal_printer_legacy.ThermalPrinter

Thermal printer control module built to work with small serial thermal receipt printers. Note that these printers have many different firmware versions and care must be taken to select the appropriate module inside this package for your firmware printer:

  • thermal_printer = The latest printers with firmware version 2.68+
  • thermal_printer_264 = Printers with firmware version 2.64 up to 2.68.
  • thermal_printer_legacy = Printers with firmware version before 2.64.
  • Author(s): Tony DiCola
class adafruit_thermal_printer.thermal_printer_legacy.ThermalPrinter(uart, byte_delay_s=0.00057346, dot_feed_s=0.0021, dot_print_s=0.03)[source]

Thermal printer for printers with firmware version before 2.64.

feed(lines)[source]

Advance paper by specified number of blank lines.

has_paper()[source]

Return a boolean indicating if the printer has paper. You MUST have the serial RX line hooked up for this to work.

Note

be VERY CAREFUL to ensure your board can handle a 5V serial input before hooking up the RX line!

print_barcode(text, barcode_type)[source]

Print a barcode with the specified text/number (the meaning varies based on the type of barcode) and type. Type is a value from the datasheet or class-level variables like UPC_A, etc. for convenience. Note the type value changes depending on the firmware version so use class-level values where possible!

reset()[source]

Reset the printer.

Indices and tables