API: Print to Star Micronics Printer

Print specific HTML elements, full webpages, barcodes &/or QR codes to a connected Star Micronics thermal printer. Return information about the results of a specific printing job and the status of the connected printer.

In this article

Requirements

Kiosk Pro Enterprise

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
    • Printing
      • Enable Star Micronics Printer = On
      • Star Micronics Printer Settings > Select Printer = select your printer or enter Port Name:
        • if connecting via Wi-Fi = 'TCP:' + the IP address of the printer
        • if connecting via Bluetooth = 'BT:' + name assigned to printer
      • Star Micronics Printer Settings > Port Settings = 9100, unless specifically changed during printer set-up
  • iOS/iPadOS Permissions
    • Bluetooth (if using a Bluetooth-connected printer) - more on enabling specific iOS/iPadOS permissions here
  • Physical Hardware
    • Star Micronics thermal kiosk printer. For a list of supported printers, click here.

Triggers via API Functions

Check if Printing Is Enabled

This function checks whether the printing to a Star Micronics printer is enabled in Kiosk Pro's settings.

Format 
kp_StarPrinter_requestStateOfSupporting();
Triggers Kiosk Pro will immediately trigger kp_StarPrinter_stateOfSupportingDidChange with the current status

Check the Status of Printer

This function requests the status of the Star Micronics printer currently selected in Kiosk Pro's settings.

Format 
kp_StarPrinter_requestStatusOfPrinter();
Triggers Kiosk Pro will immediately trigger kp_StarPrinter_statusOfPrinterDidChange once for each of the six possible error states

Print HTML Element

This function renders and prints the content of the HTML element specified, including all child elements.

Format 
kp_StarPrinter_printHtml(elementId,cutPaper);
Parameters
  • elementId - [string] the id of the HTML element to print
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Print HTML String

This function renders and prints a string of HTML markup.

Format 
kp_StarPrinter_printHTMLString(htmlString,cutPaper);
Parameters
  • htmlString - [string] HTML markup to be printed
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Print HTML Document

This function renders and prints an HTML document located at the specified URL or filepath. This file can be remote (in which case, the full URL should be passed) or locally stored in Kiosk Pro's Documents folder (in which case the path passed should be relative to the root Kiosk Pro Documents folder, not the file making the call).

As this call requires rendering a full HTML document in the background, it is generally the most resource-intensive (and therefore the slowest) of the printing methods documented here.

Format 
kp_StarPrinter_printDocumentAtURL(URL,cutPaper);
Parameters
  • URL - [string] the URL or filepath of the document to be printed
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Print QR Code

This function renders and prints a text string as a formatted QR code.

Related QR code settings determine the correction level, version, cell size, and alignment of the printed QR code.

Format 
kp_StarPrinter_printQRCode(codeText,cutPaper);
Parameters
  • codeText - [string] the text to print in QR code format
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Print Code 39 Barcode

This function renders and prints a text string as a formatted Code 39 barcode.

Related barcode settings determine the height, width, and alignment of the printed barcode, as well as whether the text should be printed below the barcode.

Format 
kp_StarPrinter_printCode39(codeText,cutPaper);
Parameters
  • codeText - [string] the text to print in Code 39 format
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Print Code 93 Barcode

This function renders and prints a text string as a formatted Code 93 barcode.

Related barcode settings determine the height, width, and alignment of the printed barcode, as well as whether the text should be printed below the barcode.

Format 
kp_StarPrinter_printCode93(codeText,cutPaper);
Parameters
  • codeText - [string] the text to print in Code 93 format
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Print Code 128 Barcode

This function renders and prints a text string as a formatted Code 128 barcode.

Related barcode settings determine the height, width, and alignment of the printed barcode, as well as whether the text should be printed below the barcode.

Format 
kp_StarPrinter_printCode128(codeText,cutPaper,codeSet);
Parameters
  • codeText - [string] the text to print in Code 128 format
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
  • codeSet - [string] determines the code set to represent the ASCII values. Must be "A", "B", or "C".
    • A - ASCII characters 00 to 95 (0–9, A–Z and control codes), special characters, and FNC 1–4
    • B - ASCII characters 32 to 127 (0–9, A–Z, a–z), special characters, and FNC 1–4
    • C - 00–99 (encodes two digits with a single code point) and FNC1
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Select Code Page

By default, Kiosk Pro uses Star Micronics' ‘Windows Latin-1’ character set for translating text into barcode or QR code format. This function allows you to define another character set if you need to include characters or symbols not included in the ‘Windows Latin-1’ character set.

You can view the full Star Micronics character code table on our site here.

Format 
kp_StarPrinter_selectCodePage(reference);
Parameters reference - reference number of the preferred character set, as string. The following character sets are supported (shown following the reference number used to identify that character set):
  • 0 - Normal
  • 1 - code page 437 (USA, Std. Europe)
  • 2 - Katakana
  • 3 - code page 437 (USA, Std. Europe)
  • 5 - code page 852 (Latin-2)
  • 6 - code page 869 (Portuguese)
  • 7 - code page 861 (Icelandic)
  • 8 - code page 863 (Canadian French)
  • 9 - code page 865 (Nordic)
  • 10 - code page 866 (Cyrillic Russian)
  • 11 - code page 855 (Cyrillic Bulgarian)
  • 12 - code page 857 (Turkey)
  • 13 - code page 862 (Israel, Hebrew)
  • 14 - code page 864 (Arabic)
  • 15 - code page 737 (Greek)
  • 16 - code page 851 (Greek)
  • 17 - code page 869 (Greek)
  • 21 - code page 874 (Thai)
  • 32 - code page 1252 (Windows Latin-1, default)
  • 33 - code page 1250 (Windows Latin-2)
  • 34 - code page 1251 (Windows Cyrillic)
Triggers Nothing directly, however if Kiosk Pro isn’t able to convert the requested source text for printing using the current character set, the app will return the callback kp_StarPrinter_printDidFailWithError(errorCode) with the error code -999.

Batch Multiple Requests to the Printer

This function merges multiple printer functions into one print command to send to the printer. This is helpful if you need to construct a single print call or need to merge a print command with a call to open a connected cash drawer.

Format 
kp_StarPrinter_startBatchPrinting(JSON.stringify(batch));
Parameters

JSON-scheme representing the following API functions:

  • Print HTML Element: {"htmlElementId":{"id":"htmlElement", "cutPaper":false}}
  • Print HTML String: {"htmlString":{"content":"<html><body><h1>HTML String</h1></body></html>", "cutPaper":false}}
  • Print Document: {"documentURL":{"url":"https://docs.kioskgroup.com/test.html", "cutPaper":true}}
  • Print QR Code: {"qrcode":{"code":"1234567890", "cutPaper":false}}
  • Print Barcode: {"barcode":{"symbology":"code39", "code":"1234567890", "cutPaper":false}}
  • Print Line Feed: {"newLF":{"cutPaper":false}}
  • Open Cash Drawer: {"openCashDrawer":{"number":1}}
Example 
function startBatchPrinting() {
	var batch = [
		{"htmlElementId":{"id":"htmlContent", "cutPaper":false}},
    	{"newLF":{"cutPaper":false}},
    	{"qrcode":{"code":"1234567890", "cutPaper":false}},
    	{"newLF":{"cutPaper":true}}, 
	 	{"openCashDrawer": {"cashDrawerId":1}}
    ];
	kp_StarPrinter_startBatchPrinting(JSON.stringify(batch));
}
startBatchPrinting();
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the request:

Notifications via API Callbacks

When the Printer is Enabled or Disabled in App Settings

This callback is triggered when user calls kp_StarPrinter_requestStateOfSupporting() and each time 'Enable Star Micronics Printer' is updated in Kiosk Pro's settings.

Format 
kp_StarPrinter_stateOfSupportingDidChange(supported);
Return values supported state - [boolean integer] representing the state of the printer in the app's settings:
  • 1 - if Star Micronics Printer is enabled in Kiosk Pro's settings.
  • 0 - if Star Micronics Printer is disabled in Kiosk Pro's settings.

When the Printer Status Changes

This callback is triggered once for each of the possible status types before sending data to the printer, after printing, or as the result of kp_StarPrinter_requestStatusOfPrinter() being called.

Format 
kp_StarPrinter_statusOfPrinterDidChange(typeOfStatus, isStatusError, beforePrinting);
Return values
  • typeOfStatus - [integer] representing the type of status being returned in the call. The following are possible:
    • 1 - offline
    • 2 - overflow
    • 3 - cut
    • 4 - out of paper
    • 5 - paper jam
    • 6 - paper near end of roll
  • isStatusError - [boolean integer] representing whether the status is an error:
    • 1 - specified status is in an error state
    • 0 - specified status is not in an error state
  • beforePrinting - [boolean integer] representing whether the status is an error:
    • 1 - the callback has been triggered before sending data to the printer
    • 0 - the callback has been triggered after sending data to the printer or as a result of kp_StarPrinter_requestStatusOfPrinter

When Printing is Successful

This callback is triggered when printing has been successful.

Format 
kp_StarPrinter_printDidFinish();

When Printing Fails

This callback is triggered if the printing could not be completed or if an error occurred during printing.

Format 
kp_StarPrinter_printDidFailWithError(errorCode);
Return values errorCode - [integer] representing the code of the error. The following are possible:
  • -1001 - Star Micronics Printer is not enabled in Kiosk Pro settings
  • -999 - unable to convert the requested source text for printing using the current character set
  • 1 - failure to open port
  • 2 - write port timed out

When a Batch Request to the Printer is Successful

This callback is triggered when a batch request to the printer has been successful.

Format 
kp_StarPrinter_batchPrintingDidFinishSuccessfully();

When a Batch Request to the Printer Fails

Format 
kp_StarPrinter_batchPrintingDidFailWithError(error);
Return values error - [integer] indicating the current error state:
  • 0 - no error specified
  • 1 - failure to open port
  • 2 - command to port timed out
  • 3 - cash drawer is offline

No Longer Supported

Print Text

Removed in version 8.4 due to underlying change from line printing to raster. We recommend replacing any calls to this function with Print HTML Element or Print HTML String.

This function prints the text parameter defined as simple text.

Format 
kp_StarPrinter_printText(codeText,cutPaper);
Parameters
  • codeText - [string] the text to be printed
  • cutPaper - [boolean integer] determines whether to trigger a paper cut after the call. For this to be applied, the Cut Paper setting must be set to Using JavaScript Parameter
    • 1 - printer will perform a cut immediately after print job finishes
    • 0 - printer will not perform a cut
Triggers Kiosk Pro will immediately trigger one of the following callbacks depending on the status of the print job:

Sample Code

  • This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
  • To run sample code, set the app's homepage to kioskgroup.com/star-micronics-api
  • To download a .zip of sample code, click here.

Change Log

  • Included in the initial version of Enterprise. Added ability to check the status of the printer in version 3.3.1. Added support for raster mode printing & call to print HTML document, as well as removed call to print text in version 8.4

Related Articles

Still stuck? How can we help? How can we help?