Receipt printing with ESC/POS | a javascript cross-platform library

receipt printing with xml-escpos-helper | npm library

At TILL, receipt printing for our customers is one of the most critical functionality which cannot go wrong to enable smooth operations within their stores to give their customers the best experience.

Receipt printing is not just bill prints for our hospitality customers. It includes kitchen docket printing which allows different items to be printed to different kitchen stations at different times as the front of house staff take the order or when the customer orders using our in-store ordering apps.

Kitchen Docket Printing

Different kitchen stations at times need different receipt templates which will enable the stations to have different layout, sizes, fonts etc to suit their requirements.

To provide this flexibility, we provide our customers the capability to design their own receipt template in our back-office which renders the template preview in HTML as they design it.

Different receipt templates can be configured to different printers.

Thermal printers use ESC/POS commands to print.

ESC/POS®

ESC/POS is a proprietary printer command system. Which enables POS systems to send commands to printers and print data, in form of a stream of bytes.

EPSON took the initiative by introducing ESC/POS, a proprietary POS printer command system, which includes patented or patent pending commands and enables versatile POS system construction with high scalability. Compatible with all types of EPSON POS printers and displays, this proprietary control system also offers the flexibility to easily make future upgrades. Its popularity is worldwide.

— source: epson-biz.com

How did we achieve this

Visual representation of the flow

Printer templates are constructed using xml with placeholders for fields to be replaced by the data passed to it in JSON format using xml-escpos-helper package.

What is xml-escpos-helper ?

Well, this is an npm package, written in typescript and an original fork from escpos-xml, where xml-escpos-helper can support react-native too.

This package will combine json data with the template which is defined in xml format, and produces a buffer (stream of bytes), which will works on terminal or shell, web or mobile applications written in javascript.

Steps involved

1. Provide JSON data and templates, to xml-escpos-helper.
2. The xml-escpos-helper library will produce the bytes with help of mustache.js
3. The generated byte stream can be sent to any thermal printer which supports TCP connections using any third-party printer communication library.

Lets look at an example below

We will build a sample console based application to print receipts using a thermal printer which is connected to network via TCP.

Prerequisites:

1. 🖨️ — A thermal receipt printer that supports TCP connections (connected to the internet)
2. 🧻 — POS roll
3. 🖥️ — with Node.js installed
4. Basic understanding of Javascript
5. Basic knowledge of ESC/POS command

Sample Output:

output

Let's start with the implementation

Create a directory calledreceipt_printing and open it in your favorite editor.

1. Initialize a Nodejs app by running the following command

$ yarn init
# or 
$ npm init

2. Install the xml-escpos-helper library

$ yarn add @tillpos/xml-escpos-helper
# or 
$ npm install @tillpos/xml-escpos-helper --save

3. Create a javascript file example.js that will import the xml-escpos-helper and has a basic blueprint which looks like below

4. To test our application easily open package.json add the below to scripts section

4. We will define the XML template, which holds the base layout. Few of the most used XML tags in this library are, small, bold, text, text-line, line-break, paper-cut. All supported tags can be found here. Now let's create a basic template sample.xmlwith the following content

5. To be able to read this XML document, we need to use Nodejs built-in fs module readFileSync . i.e,

6. We need to provide the input data which can be substituted within the template while generating a buffer with getBufferFromTemplate method available on xml-helper-library. i.e,

7. Now we have generated the byte stream which can be understood by thermal printers. To send this data to the printer we can use third-party utilities which can be able to deliver data to a printer based on host IP and port number. In this example, we will use the net module.

8. Call the connectToPrinter function from the main function

9. Now navigate to the terminal and issue following command

yarn print (or) npm run print

🎉 Your first receipt will be printed!

Complete source code :

GitHub - lakshmaji-till/basic-escpos-recept-printing: An console based application to illustrate…

For additional information refer to the following resources

Introduction

@tillpos/xml-escpos-helper

JavaScript | MDN

Net | Node.js v16.6.1 Documentation