2.1 Raw Printing

Compatibility

• ✅ 2.1 | ⛔️ 2.0 | ⛔ 1.9 | ...

Contents

The following code can be used for raw printing only. If you are unsure what raw printing is, please refer to What is Raw Printing?

• Note: Some Windows drivers, such as Zebra's ZDesigner driver for Microsoft Windows, will support raw printing alongside pixel-based/PostScript printing. You may use those drivers or a raw-generic/text-only driver to send raw commands, but the generic driver will not be able to print images/PDF/HTML.

---

Prerequisites

• An attached printer is configured for raw printing: Windows | Mac | Linux

  • Raw printing output may be tested without hardware via a printer emulator

Languages

• Generic
• ZPL
• EPL
• ESC/POS
  • ESC/POS Barcode
  • ESC/POS QR Code
• DPL

Techniques

• Base64 Printing
• Base64 Raw Images
• PDF Printing
• HTML Printing
• XML Printing
• Printing from File
• Printing to File/Filesystem
• Printing to URL

Advanced

• Advanced Print Spooling
• Special Characters
• Right-To-Left Languages
• Combining Techniques
• Custom Job Name
• Unix/Linux Alternate Printing
• Chaining Print Requests
• Queuing Print Requests

Generic

Boilerplate code to send raw commands to any printer. See also ZPL, EPL, ESC/P for specific examples. If your raw language is missing, please contact support.

Note: Reminder to supply <meta content="text/html;charset=utf-8" http-equiv="Content-Type"> if printing Unicode.

function printStuff() {
   var config = qz.configs.create("Printer Name");

   var data = [
      'Raw Data\n',
      'More Raw Data\n',
      'Even More Raw Data\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

Note: The raw commands provided may not work with your printer. Please reference your printer's programming guide for more information.

• Albeit obvious, each example needs a trigger, such as a button, .e.g.

<input type="button" onclick="printStuff()" value="Print"></input>

---

ZPL

Example for sending raw ZPL commands to a printer

Note: language: "foo" is only required if providing a raw image type in the data stream. Note: Labels are too small? Try this experimental code to force a 203dpi label to 300dpi.

function printZPL() {
   var config = qz.configs.create("Printer Name");

   var data = [
      '^XA\n',
      '^FO50,50^ADN,36,20^FDPRINTED USING QZ TRAY PLUGIN\n',
      { 
       type: 'raw', format: 'image', flavor: 'file', data: 'assets/img/image_sample_bw.png', 
       options: { language: "ZPL" }
      }, 
      '^FS\n',
      '^XZ\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

EPL

Example for sending EPL commands to a printer.

Note: language: "foo" is only required if providing a raw image type in the data stream.

function printEPL() {
   var config = qz.configs.create("Printer Name");
   
   var data = [
      '\nN\n',
      { 
       type: 'raw', format: 'image', flavor: 'file', data: 'assets/img/image_sample_bw.png', 
       options: { language: "EPL", x: 20, y: 0 } 
      },
      '\nP1,1\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

ESC/POS

var config = qz.configs.create("Printer Name");

var data = [
   { type: 'raw', format: 'image', flavor: 'file', data: 'assets/img/image_sample_bw.png', options: { language: "escp", dotDensity: 'double' } },
   '\x1B' + '\x40',          // init
   '\x1B' + '\x61' + '\x31', // center align
   'Beverly Hills, CA  90210' + '\x0A',
   '\x0A',                   // line break
   'www.qz.io' + '\x0A',     // text and line break
   '\x0A',                   // line break
   '\x0A',                   // line break
   'May 18, 2016 10:30 AM' + '\x0A',
   '\x0A',                   // line break
   '\x0A',                   // line break    
   '\x0A',
   'Transaction # 123456 Register: 3' + '\x0A',
   '\x0A',
   '\x0A',
   '\x0A',
   '\x1B' + '\x61' + '\x30', // left align
   'Baklava (Qty 4)       9.00' + '\x1B' + '\x74' + '\x13' + '\xAA', //print special char symbol after numeric
   '\x0A',
   'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' + '\x0A',       
   '\x1B' + '\x45' + '\x0D', // bold on
   'Here\'s some bold text!',
   '\x1B' + '\x45' + '\x0A', // bold off
   '\x0A' + '\x0A',
   '\x1B' + '\x61' + '\x32', // right align
   '\x1B' + '\x21' + '\x30', // em mode on
   'DRINK ME',
   '\x1B' + '\x21' + '\x0A' + '\x1B' + '\x45' + '\x0A', // em mode off
   '\x0A' + '\x0A',
   '\x1B' + '\x61' + '\x30', // left align
   '------------------------------------------' + '\x0A',
   '\x1B' + '\x4D' + '\x31', // small text
   'EAT ME' + '\x0A',
   '\x1B' + '\x4D' + '\x30', // normal text
   '------------------------------------------' + '\x0A',
   'normal text',
   '\x1B' + '\x61' + '\x30', // left align
   '\x0A' + '\x0A' + '\x0A' + '\x0A' + '\x0A' + '\x0A' + '\x0A',
   '\x1B' + '\x69',          // cut paper
   '\x10' + '\x14' + '\x01' + '\x00' + '\x05',  // Generate Pulse to kick-out cash drawer**
                                                // **for legacy drawer cable CD-005A.  Research before using.
];

qz.print(config, data).catch(function(e) { console.error(e); });

ESC/POS Barcode

//barcode data
var code = '12345';

//convenience method
var chr = function(n) { return String.fromCharCode(n); };

var barcode = '\x1D' + 'h' + chr(80) +   //barcode height
    '\x1D' + 'f' + chr(0) +              //font for printed number
    '\x1D' + 'k' + chr(69) + chr(code.length) + code + chr(0); //code39

qz.websocket.connect().then(function() {
   var config = qz.configs.create("Epson TM88V");
   return qz.print(config, ['\n\n\n\n\n' + barcode + '\n\n\n\n\n']);
}).catch(function(err) { alert(err); });

ESC/POS QR Code

var config = qz.configs.create("Epson TM88V");

// The QR data
var qr = 'https://qz.io';

// The dot size of the QR code
var dots = '\x09';

// Some proprietary size calculation
var size1 = String.fromCharCode(qr.length + 3);
var size0 = '\x00'; // Always 0 unless qr > 256 characters
        
var data = [ 
   '\x1B' + '\x40' + 'John Doe' +'\x0A' + '\x0A' + '\x0A' + '\x0A' + '\x0A' + '\x0A', // Some text and a few line feeds to make sure the initiation and first line are coming through

   // <!-- BEGIN QR DATA -->
   '\x1D' + '\x28' + '\x6B' + '\x04' + '\x00' + '\x31' + '\x41' + '\x32' + '\x00',    // <Function 165> select the model (model 2 is widely supported)
   '\x1D' + '\x28' + '\x6B' + '\x03' + '\x00' + '\x31' + '\x43' + dots,               // <Function 167> set the size of the module
   '\x1D' + '\x28' + '\x6B' + '\x03' + '\x00' + '\x31' + '\x45' + '\x30',             // <Function 169> select level of error correction (48,49,50,51) printer-dependent
   '\x1D' + '\x28' + '\x6B' + size1 + size0 + '\x31' + '\x50' + '\x30' + qr,          // <Function 080> send your data (testing 123) to the image storage area in the printer
   '\x1D' + '\x28' + '\x6B' + '\x03' + '\x00' + '\x31' + '\x51' +'\x30',              // <Function 081> print the symbol data in the symbol storage area
   '\x1D' + '\x28' + '\x6B' + '\x03' + '\x00' + '\x31' + '\x52' +'\x30',              // <Function 082> Transmit the size information of the symbol data in the symbol storage area
   // <!-- END QR DATA -->

   'New York, NY' + '\x0A' + '\x0A' + '\x0A' + '\x0A' + '\x0A' + '\x0A'               // more line feeds and text to see if we messed up the QR Code syntax      
];

DPL

//barcode data
var code = '1234567890';

var text = 'Hello world';

//convenience method
var chr = function(n) { return String.fromCharCode(n); };

var data = [
   chr(02) + 'n\n',
   ' M0500\n',
   ' KcLW0422;\n',
   ' O0220\n',
   ' d\n',
   ' L\n',
   'D11\n',
   'ySPM\n',
   'A2\n',
   '1911A1200650118' + text +'\n',
   '1eA505401290091C' + code + '\n',
   '1911A1201090155'+ code + '\n',
   'Q0001\n',
   'E\n'
];

qz.websocket.connect().then(function() {
   var config = qz.configs.create("I-Class Mark II");
   return qz.print(config, data);
}).catch(function(err) { alert(err); });

---

Base64

With this function, you can send base64 encoded characters/raw commands to qz using "base64". This will automatically convert provided base64 encoded text into text/ascii/bytes, etc.

function printBase64() {
   var config = qz.configs.create("Printer Name");

   var data = [
      {
         type: 'raw', format: 'command', flavor: 'base64',
         data: 'Ck4KcTYwOQpRMjAzLDI2CkI1LDI2LDAsMUEsMyw3LDE1MixCLCIxMjM0IgpBMzEwLDI2LDAsMywx' +
            'LDEsTiwiU0tVIDAwMDAwIE1GRyAwMDAwIgpBMzEwLDU2LDAsMywxLDEsTiwiUVogUFJJTlQgQVBQ' +
            'TEVUIgpBMzEwLDg2LDAsMywxLDEsTiwiVEVTVCBQUklOVCBTVUNDRVNTRlVMIgpBMzEwLDExNiww'
      }
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

Base64 Images

With this function, you can send a base64 encoded image as a portion of a raw command. This will automatically convert provided base64 encoded text into raster graphics appropriate for the specified language, etc.

function printBase64Image() {
   var config = qz.configs.create("Printer Name");
   var data = [
      '^XA\n',
      '^FO50,50^ADN,36,20^FDPRINTED USING QZ TRAY PLUGIN\n',
      {
         type: 'raw', format: 'command', flavor: 'base64',
         data: 'iVBORw0KGgoAAAANSUhEUgAAAH[...]==', 
         options: { language: "ZPL" },
      }
      '^FS\n',
      '^XZ\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

PDF Printing

Print a PDF directly to a raw printer

EPL

function printRawPDF() {
   var config = qz.configs.create("Printer Name");
   var data = [
      '\nN\n',
      'q609\n',
      {
         type: 'raw', format: 'pdf', flavor: 'file',
         data: 'path/to/pdf_sample.pdf',
         // rendered pageWidth and pageHeight in pixels is required
         options: { language: "EPL", "pageWidth":"500", "pageHeight":"500" },
      }
      '\nP1,1\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

ZPL

function printRawPDF() {
   var config = qz.configs.create("Printer Name");
   var data = [
      '^XA\n',
      {
         type: 'raw', format: 'pdf', flavor: 'file',
         data: 'path/to/pdf_sample.pdf',
         // rendered pageWidth and pageHeight in pixels is required
         options: { language: "ZPL", "pageWidth":"500", "pageHeight":"500" },
      }
      '^XZ\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

ESCP

function printRawPDF() {
   var config = qz.configs.create("Printer Name");
   var data = [
      {
         type: 'raw', format: 'pdf', flavor: 'file',
         data: 'path/to/pdf_sample.pdf',
         // rendered pageWidth and pageHeight in pixels is required
         options: { language: "ESCP", "pageWidth":"500", "pageHeight":"500" },
      }
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

HTML Printing

Print HTML content directly to a raw printer

EPL

function printRawHTML() {
   var config = qz.configs.create("Printer Name");
   var data = [
      '\nN\n',
      'q609\n',
      {
         type: 'raw', format: 'html', flavor: 'file',
         data: 'path/to/sample.html',
         // rendered pageWidth and pageHeight in pixels is required
         options: { language: "EPL", "pageWidth":"500", "pageHeight":"500" },
      }
      '\nP1,1\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

ZPL

function printRawHTML() {
   var config = qz.configs.create("Printer Name");
   var data = [
      '^XA\n',
      {
         type: 'raw', format: 'html', flavor: 'file',
         data: 'path/to/sample.html',
         // rendered pageWidth and pageHeight in pixels is required
         options: { language: "ZPL", "pageWidth":"500", "pageHeight":"500" },
      }
      '^XZ\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

ESCP

function printRawHTML() {
   var config = qz.configs.create("Printer Name");
   var data = [
      {
         type: 'raw', format: 'html', flavor: 'file',
         data: 'path/to/sample.html',
         // rendered pageWidth and pageHeight in pixels is required
         options: { language: "ESCP", "pageWidth":"500", "pageHeight":"500" },
      }
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

File

This feature allows a raw file to be spooled directly to the printer.

function printFile() {
   var config = qz.configs.create("Printer Name");

   var data = [
      {
        type: 'raw', format: 'command', flavor: 'file', data: 'assets/raw-data.txt'
      }
   ];
  
   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

XML

The ability to read the contents of an XML file containing Base64 encoded commands and send these commands to the printer.

function printXML() {
   var config = qz.configs.create("Printer Name");

   var data = [
      {
        type: 'raw', format: 'command', flavor: 'xml', data: 'assets/zpl_sample.xml', 
        options: { xmlTag: 'v7:Image' }
      }
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

URL

Print directly to a HTTP url (such as a CUPS shared printer, or to a print server device).

function printToURL() {
   var config = qz.configs.create({ host: "192.168.254.254", port: 9100 }); // or http://<cups-server>/printers/<my-printer>

   var data = [
      'Raw Data\n',
      'More Raw Data\n',
      'Even More Raw Data\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

Filesystem

Print to local filesystem

function printToFile() {
   var config = qz.configs.create({ file: "/path/to/output.txt" }); // or "C:\\path\\to\\output.text", etc

   var data = [
      'Raw Data\n',
      'More Raw Data\n',
      'Even More Raw Data\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

Print to Win32 UNC Path

function printToUNC() {
   var config = qz.configs.create({ file: "\\\\server\\printer" });

   var data = [
      'Raw Data\n',
      'More Raw Data\n',
      'Even More Raw Data\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

Print to Win32 Device Namespace

Leverage printing API for writing to a Win32 Device Namespace physical device such as a Bematech/Logic Controls Pole Display mapped as \\.\LCLD9

function printToDevice() {
   var config = qz.configs.create({ file: "\\\\.\\LCLD9\\dummy" });

   var data = [
      '"\r\nMMM... COFFEE! :)\r\n"'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

Advanced Print Spooling

Spools jobs between specified endOfDoc delimiter. Useful for avoiding buffer overflows on unusually large quantity print jobs by spooling each raw job individually. Defaults to 1 job per spool, but can be overridden using perSpool option.

function advancedSpooling() {
   var config = qz.configs.create("Printer Name", { endOfDoc : '\n' });

   var data = [
      'First\n',
      'Second\n',
      'Third\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

Special Characters

Hex

function printHex() {
   var config = qz.configs.create("Printer Name");

   var data = [
      //short hand
      //defaults to 'type: raw' and 'format: command'
      { 
       flavor: 'hex', data: 'x1Bx00', // or data: '1B00'
       options: { language: "ZPL" } //or other languages
      }
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

Decimal

function printDecimal() {
   var config = qz.configs.create("Printer Name");

   var data = [
      String.fromCharCode(27) + String.fromCharCode(0) // e.g. CHR(27) CHR(0) or Hex x1Bx00
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

Code Page

Force Java to use a specific code-page for printing.

function printCodePage() {
   var config = qz.configs.create("Printer Name", { encoding: 'CP1253' }); // MS-DOS Greek

   var data = [
      "Σ β θ"
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

Combining Techniques

function printCombined() {
   var config = qz.configs.create("Printer Name", { language: "escp" });

   // Example only, not valid ESCP
   var data = [
      "My Raw Commands",
      String.fromCharCode(27) + String.fromCharCode(0),
      { flavor: 'hex', data: 'x1Bx00' },
      { type: 'raw', format: 'image', flavor: 'file', data: 'assets/img/image_sample_bw.png',  
        options: { dotDensity: 'double' } }, 
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

---

Copies

A config parameter copies can be provided to send the specified raw commands multiple times. This is a convenience function as most raw languages already have an internal copies command.

function copies() {
var config = qz.configs.create("Printer Name", { copies: 4 });

var data = [
   'Raw Data\n',
   'More Raw Data\n',
   'Even More Raw Data\n'
];

qz.print(config, data).catch(function(e) { console.error(e); });
}

---

Custom Job Name

A config parameter jobName can be provided to change the name listed in the print queue.

function customJobName() {
var config = qz.configs.create("Printer Name", { jobName: "Receipt #123456" });

var data = [
   'Raw Data\n',
   'More Raw Data\n',
   'Even More Raw Data\n'
];

qz.print(config, data).catch(function(e) { console.error(e); });
}

Alternate Printing

When using CUPS (Linux/Unix/Mac), the printer driver can be bypassed completely by executing a command-line option

lpr -o raw my-raw-file.txt

This may be useful when troubleshooting issues with non-raw printer drivers. QZ Tray can substitute the standard printing behavior with this technique by adding a config parameter altPrinting. This parameter has no effect in a Windows environment.

function alternatePrint() {
   var config = qz.configs.create("Printer Name", { altPrinting: true });

   var data = [
      'Raw Data\n',
      'More Raw Data\n',
      'Even More Raw Data\n'
   ];

   qz.print(config, data).catch(function(e) { console.error(e); });
}

Chaining Requests

Print requests can be chained together to print several raw items at once, or to print to several different printers.

var config = qz.configs.create();
var data = [{ type: 'raw', data: null, }];

data.data = 'Some Raw Data #1';                    ////// First raw item
config.setPrinter('First Printer');                ////// First printer
qz.print(config, data)

.then(function() {
   data.data = 'Some Raw Data #2';                 ////// Second raw item
   config.setPrinter('Second Printer');            ////// First printer
   return qz.print(config, data);
})

.then(function() {
   data.data = 'Some Raw Data #3';                 ////// Third raw item
   config.setPrinter('Third Printer');             ////// Third printer
   return qz.print(config, data);
})

.catch(function(e) {
   console.error(e);                // Exceptions throw all the way up the stack
});

Promise Loop

Looping multiple configs and multiple data objects is now built-in to the 2.1 API. More information here.

Filter Printers

As of 2.1, the sift library can be leveraged using qz.printers.details(); to filter the available printer listings. This can be used to exclude types of printers (virtual, raw, etc).

In this example, only raw printers attached to the system will be returned

function detailPrinters() {
  qz.printers.details().then(function(data) {
  data = sift.keep( data, { type: 'raw' });
  console.log(data);
});
}

Go to the sift repository for more examples on how the sift library can be utilized.