Public API

The Thermal_Printer library does not contain a C++ class, but is structured as a set of C-style functions. The main purpose is to simplify printing text and graphics on inexpensive thermal printers. The basic usage flow goes like this:

• Scan for supported BLE devices (matching the supported device names)
  
• Connect to a supported device
  
• Print text or graphics
  
• Disconnect
  

Please see the code examples for a clearer understanding of the individual steps. Here are the exposed functions:

int tpScan(void)
Initiates a BLE scan for supported devices for 5 seconds. This version of the scan function will only succeed if it finds a printer name from the supported printers list (e.g. MTP-2). You may have a printer that is supported, but presents an unrecognized bLE name. In this case, use the other tpScan function which allows you to specify the name.
Returns true for success, false for failure.

int tpScan(char *szName, int iSeconds)
Initializes a BLE scan for the named device for a duration of iSeconds.
Returns true for success, false for failure.

int tpConnect(void)
After a successful scan, this starts a BLE connection to the printer. While connected, other computers cannot interact with the printer. The information gathered during the scan (BLE MAC address) is kept internally and can be used to repeatedly connect/disconnect to the same printer if desired until a new scan is done.

void tpDisconnect(void)
Disconnects the current BLE connection. If not connected, this is ignored.

int tpIsConnected(void)
Returns true if currently connected to a printer, false if not.

void tpSetWriteMode(uint8_t bWriteMode)
Bluetooth Low Energy data transfer allows for writing data "withResponse" and without. The difference is that withResponse will take much longer because the sender has to wait for acknowledgement of each packet transmitted. Some printers can handle receiving data as fast as you can send it and others cannot. The default value is set to enable writes withResponse. You can pass it the values MODE_WITH_RESPONSE or MODE_WITHOUT_RESPONSE to control this behavior.

void tpSetBackBuffer(uint8_t *pBuffer, int iWidth, int iHeight)
To generate and print graphics, it's necessary to define an area of RAM to hold onto the image before sending it to the printer. Since the printer uses 1 bit per pixel, the amount of memory isn't very large. 57mm printers have a maximum width of 384 pixels and for 80mm printers, it's 576 pixels. This translates into 48 and 72 bytes respectively. To work on a square image of 384x384 pixels requires 48x384 = 18432 bytes of RAM. Use this function to pass a buffer you allocate to facilitate printing graphics. Since you provide the pointer, you can allocate this buffer statically or dyanmically. This isn't necessary to know to use this library, but if you want direct access to the pixels, they are laid out internally in a horizontal orientation with the MSB (0x80) on the left. For example, if pixels (0,0),(1,0) and (4,0) (3 pixels on scanline 0) are set, the byte value at offset 0 will be 0xc8.

void tpSetFont(int iFont, int iUnderline, int iDoubleWide, int iDoubleTall, int iEmphasized)
For printers which support ASCII text printing, this allows you to set the text size and attributes. iFont can be one of FONT_12x24 or FONT_9x17.

void tpQRCode(char *string)
Print a 2D (QR) code from the given zero-terminated ASCII string. Not all printers support barcode printing. The text alignment setting will affect the position the barcode is printed on the paper.

void tp1DBarcode(int iType, int iHeight, char *szData, int iTextPos)
Print a 1D barcode. Not all printers support barcode printing and even if supported, not all code types are supported on all printers. The human readable text encoded in the barcode can be printed above, below, both or not at all. Not all printers support all of these options. The iType specifies the barcode type. It can be one of:
BARCODE_UPCA
BARCODE_UPCE
BARCODE_EAN13
BARCODE_EAN8
BARCODE_CODE39
BARCODE_ITF
BARCODE_CODABAR
BARCODE_CODE93
BARCODE_CODE128
BARCODE_GS1_128
BARCODE_GS1_DATABAR_OMNI
BARCODE_GS1_DATABAR_TRUNCATED
BARCODE_GS1_DATABAR_LIMITED
BARCODE_GS1_DATABAR_EXPANDED
BARCODE_CODE128_AUTO

The height is the the number of pixels tall the barcode is printed. szData points to a zero-terminated ASCII string containing the barcode to print and finally iTextPos can be one of BARCODE_TEXT_NONE, BARCODE_TEXT_ABOVE, BARCODE_TEXT_BELOW, BARCODE_TEXT_BOTH.

void tpAlign(uint8_t ucAlignment)
Set the text and barcode alignment. Valid values are ALIGN_LEFT, ALIGN_CENTER, and ALIGN_RIGHT. This is only supported on printers that support text and barcode mode (e.g. the cat printer does not).

void tpFeed(int iLines)
Feed the paper forward 1-255 scan lines (a single pixel line of graphics). A normal line feed defaults to 1/6" which is about 28 pixels.

int tpGetWidth(void)
Returns the currently connected printer's max width in pixels. If a printer is not connected, it returns 0. The supported values so far are 384 (for 57mm printers) and 576 (for 80mm printers).

int tpPrint(char *pString)
Passes a zero terminated C-string to a connected printer that supports ASCII printing. If the string does not exceed 1 line length and does not contain a carriage return, it will sit in the printer's internal buffer until the printer needs to move to the next line. Because the printer prints a scanline of pixels at a time, it can't print a partial line and will wait until the line finishes.

int tpPrintLine(char *pString)
The same as tpPrint(), but adds a carriage return to force the line to print and advance to the next line.

int tpPrintCustomText(GFXfont *pFont, int x, char *szMsg)
This function prints a single line of text (C-string) using a custom font in Adafruit_GFX format and advances the line. The x value is the starting pixel column. Any pixels which go beyond the right edge (max printing width) will be truncated.

void tpGetStringBox(GFXfont *pFont, char *szMsg, int *width, int *top, int *bottom)
Gets the bounding rectangle of a C-string printed in the given font. Use this with the tpPrintCustomText() function to know how large your string is. The top and bottom values can be (and usually are) negative numbers since this refers to the space above the 'baseline' of the character.

int tpDrawCustomText(GFXfont *pFont, int x, int y, char *szMsg)
Like the tpPrintCustomText() function, this draws the text with the given font into a graphics buffer previously specified by tpSetBackBuffer(). The x,y coordinate is the starting point of the text baseline; remember that the text is drawn mostly above the baseline. For example, telling it to draw at 0,0 will result in nearly nothing visible since most of the text will lie above 0.

int tpDrawText(int x, int y, char *pString, int iFontSize, int bInvert)
Draws text with one of the built-in fonts into the graphics buffer starting at the given x,y coordinate. For this text, the x,y represents the upper left corner of the bounding box of the fixed sized characters. The font can be specified as FONT_SMALL (8x8) or FONT_LARGE (16x24).

int tpLoadBMP(uint8_t *pBMP, int bInvert, int iXOffset, int iYOffset)
Loads a Windows format BMP (1-bit per pixel) at the given x,y coordinates. The pointer passed should point to the start of the BMP file data (the BMPHEADER). The invert flag allows you to invert black/white pixels.

void tpFill(unsigned char ucData)
Fill the graphics buffer with the given byte pattern. Normally you would use this to set all of the bytes to white (0x00).

int tpSetPixel(int x, int y, uint8_t ucColor)
Set (color 1) or clear (color 0) a single pixel of the graphics buffer.

void tpDrawLine(int x1, int y1, int x2, int y2, uint8_t ucColor)
Draw a straight line in the graphics buffer of the given color (1 = black, 0 = white).

void tpPrintBuffer(void)
Send the current graphics buffer to the currently connected printer. This will print the entire graphics buffer in a single pass.
void tpWriteRawData(uint8_t *pData, int iLen)
Send your own raw data directly to the connected printer. Useful for experimenting with unique functions on your particular device.