How to Print labels with TSPL and JavaScript

Label printers can support programming languages like TSPL, ZPL, EPL, and so on. Today we are going to overview the TSPL language. We can build labels using TSPL commands like TEXT, BARCODE and QRCODE. For instance, if we want to print a label with a text and barcode, we use these commands with their properties like position or size, and send these commands to the label printer over Bluetooth or Serial connection.

On the left side, you can see the TSPL commands and the printed label on the right side. You can find all the available commands , but let’s look at some of them to understand how to use the TSPL.

Coordinates and size in dots

Whether it is a TEXT, BARCODE or BITMAP, generally, the coordinates and size are in dots. The number of dots per inch depends on the printer's DPI.

For instance, if the printer is

• 203 DPI → means there are 203 dots in one inch, or there are 8 dots in 1 mm.
• 300 DPI → means there are 300 dots in one inch, or there are 11.8 dots in 1 mm.

According to this, if we want to add a barcode with a height of 10mm, and the printer is 203DPI, then we should set the height as 80 (10mm x 8 = 80 dots).

Size and gap of the label

We need to tell the printer the size of the label like this:

SIZE 4,1

Here we said that size of the label is 4x1 inches.

We can also set it in a metric system (mm):

SIZE 50 mm,25 mm

We can set the gap which is the space between labels (GAP m,n).

GAP 0,0

Here the gap is zero inches which means it is a continuous label.

Text

We can use TEXT command to print a text on the label. We can give the position, font size, rotation, and so on:

TEXT x,y,“font”,rotation,x-multiplication,y-multiplication,[alignment,] “content”

Parameter	Description
x, y	x and y-coordinate
font	Generally, we can set 1-8 (1-small, 2-bigger… 8-biggest)
rotation	0, 90, 180, 270 in clockwise direction
x and y-multiplication	Scale factor 1-10
alignment	1-left, 2-center, 3-right (optional)
content	Text content

Sample commands	Result
TEXT 10,20,"1",0,1,1,"FONT 1" TEXT 10,70,"2",0,1,1,"FONT 2" TEXT 10,120,"3",0,1,1,0,"FONT 3"

Barcode

We can add a barcode to the label with the BARCODE command:

BARCODE X,Y,”code type”,height,human-readable,rotation,narrow,wide,[alignment,]”content”

Parameter	Description
x, y	x and y-coordinate
code type	128, EAN128, EAN13…
height	Height in dots
human-readable	0 - barcode value (text) is not visible 1 - text is left-aligned 2 - center-aligned 3 - right-aligned
rotation	0, 90, 180, 270 in clockwise direction
narrow	Width of the narrow element in dots
wide	Width of the wide element in dots
alignment	1-left, 2-center, 3-right (optional)
content	Content of barcode

Sample commands:

TEXT 10,10, "2",0,1,1, "Human readable alignment"
BARCODE 10,50, "128",100,1,0,2,2,"left"
BARCODE 310,50, "128",100,2,0,2,2,"center"
BARCODE 610,50, "128",100,3,0,2,2,"right"

Result:

PRINT and END commands

After building the label we need to tell the printer that the label is ready to print. We use PRINT m[,n] command to do this:

Commands	Description
SIZE 50 mm,25 mm CLS TEXT 10,10, "2",0,1,1, "Text 1" PRINT 1 CLS TEXT 10,10, "2",0,1,1, "Text 2" PRINT 2 END	- Set the size of the label - Clear the buffer - Add text - Print the buffer once - Clear the buffer - Add text - Print the buffer two times - End of program

It prints three labels; one label with “Text 1“ and two labels with “Text 2“.

We add END command at the end, to tell the printer that we’ve finished printing. Without this command, the printer may not print the last image in the buffer.

Printing with JavaScript (Node.js)

Generated commands can be sent to the printer over Serial or Bluetooth. To demonstrate this I created a simple code using Node.js. I used the ‘’ package to connect and send the commands (On Windows, you may need to install a driver, ).

const usb = require('usb');

const cmds = [
  'SIZE 48 mm,25 mm',
  'CLS',
  'TEXT 10,10,"4",0,1,1,"HackerNoon"',
  'BARCODE 10,60,"128",90,1,0,2,2,"altospos.com"',
  'PRINT 1',
  'END',
];

// you can get all available devices with usb.getDeviceList()
let device = usb.findByIds(/*vid*/8137, /*pid*/8214);
device.open();
device.interfaces[0].claim();
const outEndpoint = device.interfaces[0].endpoints.find(e => e.direction === 'out');
outEndpoint.transferType = 2;
outEndpoint.transfer(Buffer.from(cmds.join('\r\n')), (err) => {
  device.close();
});

And the result:

---

I had to gather information piece by piece about printing labels when I implement this feature on project. So I wrote this article in hope that it will be the starting point for someone in a similar situation.

No War! ✋🏽