Silent Kitchen & Receipt Printing · Field-Tested

QZ Tray — Installation & Setup Guide

The complete, from-scratch guide to installing and configuring QZ Tray for silent kitchen (KOT) and receipt printing. Written from real on-site experience on a live restaurant (shome.rp1.in), including every real-world trap — so you don't have to rediscover them.

🖨️ KOT + Receipts🖥️ Windows POS PC☁️ Works with waiter phones

0How It Works — read this first, it decides everything

Your web browser (the POS) does not print directly to the printer. It sends the print job to QZ Tray — a small Windows program running on the cash/order PC — and QZ Tray hands it to the Windows printer the app asked for.

Browser (POS)

Builds the print job and sends it securely to QZ Tray.

QZ Tray

A desktop program on the cash PC that receives and dispatches the job.

Windows Printer

Receives the job from QZ Tray and prints the paper.

The #1 rule

RMS prints by the Windows printer name. If the name inside the app doesn't match the name Windows sees, nothing prints — silently. This one rule is the source of most field problems.

Two different print paths — and two different drivers

What is printing	Format	Windows driver you need
KOT / kitchen tickets	Raw ESC/POS (bytes)	Generic / Text Only
Bills / invoices / receipts	HTML (logo + barcode)	The manufacturer's driver (e.g. Epson)

Don't unify them

If one printer does both jobs (ticket + bill), install it twice in Windows under two names — once with the manufacturer driver, once with Generic/Text Only. "Unifying" them is how you get garbage on tickets or missing barcodes on bills.

1Ground-Truth Example (a live working setup)

This is a configuration that works every day on shome. Use it as your pattern for printer names and routing.

The printers (reached through QZ Tray on the POS PC)

Purpose	Windows name	Driver
Receipt / cash drawer	RECP1	manufacturer (Epson)
Main kitchen ticket	KOT1	Generic / Text Only
Juice counter ticket	KOT2	Generic / Text Only
Shawarma station ticket	KOT3	Generic / Text Only
BBQ station ticket	KOT4	Generic / Text Only

Kitchen stations inside the app

Station name	Printer Name (QZ)	Printer IP
MAIN KITCHEN	KOT1	(blank — routes via QZ)
JUICE COUNTER	KOT2	(blank)
SHAWARMA STATION	KOT3	(blank)
BBQ STATION	KOT4	(blank)

Here the kitchen printers are USB/desk printers on the POS PC, so everything routes through QZ Tray by name. Giving them an IP would require a raw network endpoint that doesn't exist and would not make them print.

QZ Host on shome 192.168.70.137 — the POS PC's Wi-Fi address, the network the order-taking phones also use. (See the trap in step 6.)

2What You Need Before Starting

A Windows computer that will be the cash/order PC, with internet (for downloads).
The printer drivers (from the printer maker).
QZ Tray — download from https://qz.io/download/ (Windows version).
Two files from your support team (already set up for your site):
digital-certificate.txt and private-key.pem
The IP address of any network printer you plan to use.

3Step 1 — Install the printer in Windows

Do this before touching the app.

3A. A printer connected directly to the PC (USB / cable)

Plug the printer in and turn it on; let Windows detect it (or install the maker's driver).
Open Control Panel → Devices and Printers (or Settings → Bluetooth & devices → Printers & scanners).
Confirm the printer appears. Right-click → Printer properties → Print Test Page.
If the test page comes out, note the exact printer name.

3B. A network printer (kitchen printers with their own IP)

Connect the printer to the network (LAN or Wi-Fi) and note its IP.
Make sure the POS PC and the printer are on the same network.
Settings → Printers & scanners → Add device → Add manually → Add using a TCP/IP address or hostname → enter the printer IP.
Install the correct driver → finish → print a Windows test page.
Note the exact Windows printer name.

3C. Critical — driver & name rules

KOT tickets → Generic / Text Only driver (raw ESC/POS).
Receipt bills → manufacturer's driver.
Give every printer a simple, exact name and use the same name on every POS PC.
Copy-paste, don't retype (avoid spaces/typos). e.g. RECP1, KOT1–KOT4.

4Step 2 — Install QZ Tray on the POS computer

Open https://qz.io/download/ → download the Windows installer → run → finish.
Open QZ Tray; confirm its icon appears in the system tray (bottom-right, near the clock).
Keep it running all day. If QZ Tray is closed, silent printing stops with no obvious error.

Make QZ Tray stay alive (important!)

Set the POS PC to never sleep (Control Panel → Power Options → put it to Never).
Add QZ Tray to Startup so it's there whenever the PC is turned on.
Keep the POS browser tab open on the device.

5Step 3 — Set up QZ in the app (one-time, per site)

Log in as Admin.
Go to Management → QZ Tray Settings.
Tick Enable Silent KOT Printing (QZ Tray).
Tick Enable Silent Bill/Receipt Printing (QZ Tray) if you want receipts silent too.
Upload digital-certificate.txt and private-key.pem.
Save, and confirm it shows Certificate: Uploaded and Private key: Uploaded.
Set the QZ Tray Host (see the next section — this is where the field traps live).
Click Connect → wait for it to show Connected.
Click List Printers → confirm your Windows printer names appear. This proves QZ Tray can see them.

6The QZ Tray Host field — the #1 field trap

QZ Tray Host tells the browsers where QZ Tray is listening. One value is read by every surface — the counter POS, the receipt popup, the cash drawer, and every waiter phone.

The rule that fixes most site failures

Set the host to an address that is on the same network as the devices that print — not the server's LAN, and not "whatever looks nice."

Real shome case — the dual-homed PC

The POS PC had a wired address 192.168.1.100 (printer-only network) and a Wi-Fi address 192.168.70.137 (the hotspot the waiter phones joined). Setting the host to the wired IP made waiter-mode printing fail. Pointing it at the Wi-Fi IP (192.168.70.137) put the counter PC and the phones on one reachable network — and it worked.

How to find the right value

On the POS PC, run in a command prompt:
```
ipconfig
```
and note every IPv4 address.
If waiters take orders from phones, check a phone's IP (Settings → Wi-Fi → tap the network → IP address) and make sure the host is on that same network.
If only ONE PC prints (no phones/tablets), you can leave the host blank — QZ Tray uses localhost on that same PC and it works with zero network setup.
Do not clear it if you have waiter phones — they'd look for QZ Tray on themselves and fail.

The one-value trap

A single host setting is read by every device. Don't assume "one fix fits all" — if you have both a counter PC and waiter phones, the host must be reachable by both.

7Step 4 — The certificate step every device needs

The field gotcha that causes "prints only sometimes".

Why it fails silently

QZ Tray serves its WebSocket on a secure port (8181). Its cert is self-signed, and every browser, on every device, must accept it once — separately. There is no popup window for a WebSocket — it just fails silently until the host has been accepted. The counter PC accepting it does not help the waiter phones.

The fix (do this on EVERY device that prints)

On that device's browser, open:
```
https://<QZ-Tray-Host>:8181
```
e.g. https://192.168.70.137:8181
Click through / accept the certificate warning (on a "Your connection is not private" page, click Advanced → Proceed).
You should land on the QZ Tray About page (shows version, uptime, ports). That page loading = the host is reachable and the certificate is now accepted.

The single most common cause

A waiter phone that has never had this page opened cannot print, ever, until someone taps through it once. That is the most common reason "the counter prints but the waiter phone doesn't." It costs one URL to check.

8Step 5 — Set up Kitchen Stations in RMS

Log in as Admin → Management → Kitchen Stations.
Add a station for each production area (shome: MAIN KITCHEN, JUICE COUNTER, SHAWARMA STATION, BBQ STATION).
Fill the fields like this:
- Station Name: the area name (e.g. MAIN KITCHEN).
- Printer Name (QZ): the exact Windows printer name (e.g. KOT1). This is the field silent QZ printing actually uses.
- Printer IP: leave blank when the printer is a USB/desk printer reached through QZ by name (this is how shome works). Fill only if you rely on a raw network send path for that printer.
- Printer Type: network / usb / bluetooth.
- Auto Cut: keep On if the thermal printer supports paper cutting.
- Status: Active.
Save Station.

9Step 6 — Route menu categories to the correct station

Management → Categories → add or edit a category.
Set Kitchen Station (Routing for KOT) to the correct station.
Save.

Example (shome-style):

a main-dish category → MAIN KITCHEN
a juice category → JUICE COUNTER
a shawarma category → SHAWARMA STATION
a BBQ category → BBQ STATION

If a category isn't linked, its KOT may print in the wrong place or not route at all.

10Step 7 — Full test (paper coming out is the only proof)

Printer powered on, installed in Windows, Windows test page prints.
QZ Tray is open (tray icon) with the certificate files uploaded in RMS.
RMS Connect returns Connected. and List Printers shows the names.
Kitchen Stations have the exact names in Printer Name (QZ).
Categories point at the right stations.
Place a test order → confirm the KOT prints at the right printer and the receipt prints.

Read this symptom correctly

If the browser pops open a normal KOT print window/new tab instead of printing silently, that means silent QZ printing did not complete — recheck QZ Tray is open, the host, and the printer names.

11Quick Setup Summary (shortest correct path)

Install the printer in Windows; print a test page; note the exact name.
Use the Generic / Text Only driver for KOT printers; the manufacturer driver for bills.
Install and open QZ Tray on the POS PC.
Management → QZ Tray Settings: enable silent KOT + receipt, upload digital-certificate.txt + private-key.pem, set a host the printing devices can all reach.
Connect + List Printers to verify.
Accept the certificate once on every printing device by opening https://<host>:8181.
Management → Kitchen Stations: exact printer names in Printer Name (QZ).
Link each Category to its station.
Place a test order → it prints.

12Troubleshooting (real symptoms we've solved)

Problem	Cause / Fix
Printer doesn't show in "List Printers"	Not installed in Windows, or QZ Tray not running. Install / print a test page / start QZ Tray / Connect / List Printers again.
KOT doesn't print, but printer is visible	Wrong name in Printer Name (QZ), category not linked, or QZ Tray closed. Copy the name exactly from List Printers, paste into the station, check mapping, confirm QZ Tray is open.
Prints on counter PC but NOT on waiter phone	Almost always the certificate was never accepted on the phone (open `https://<host>:8181` on the phone) or the phone isn't on the host's network.
Works on PC 1 but not PC 2	The printer is installed with a different name on PC 2. Make the Windows names identical and keep QZ Tray running on both.
Network printer stopped printing	The printer IP probably changed or it's offline. Confirm on, check the IP, re-add in Windows, test page.
"Error printing on KOT — couldn't print QZ Tray Raw Print"	This is QZ Tray's own notification (not the app's). Appears when a print lands during a brief reconnection. Rare (~1% of prints), usually recovers. Keep the PC awake and the tab open.
Certificate / key shows "Missing"	Re-upload `digital-certificate.txt` and `private-key.pem` in QZ Tray Settings and Save.
A browser permission warning appears	First use or after reinstalling QZ Tray. Accept/allow per your policy, then retry.

13Best Practices (keeps printing stable)

Use simple, exact printer names; keep them identical on every POS PC.
Use the Generic / Text Only driver for raw KOT printers, the manufacturer driver for bills — don't mix them up.
Keep QZ Tray running all day; add it to Startup; set the PC to never sleep.
Keep the POS tab open.
Put network printers on a stable/reserved IP so a DHCP change doesn't break them.
Accept the certificate once on each device as it's added.
Test printing after any driver, Windows, or network change.

14Reference — a working site's exact values (your starting template)

shome.rp1.in (live, verified)

QZ Tray version	2.2.6 client-side
Receipt printer	`RECP1` (manufacturer driver, auto-cut on)
Kitchen stations → names	`KOT1` (main), `KOT2` (juice), `KOT3` (shawarma), `KOT4` (BBQ) — all Generic/Text Only, no Printer IP (routed through QZ by name)
QZ host	`192.168.70.137` (the POS PC's Wi-Fi address — reachable by the waiter phones)
Certificate files	`digital-certificate.txt` (public cert) + `private-key.pem` (private key)

A note on the JS library (why the CDN may not be needed) The RMS POS loads QZ Tray's JavaScript from a self-hosted copy on the server (/assets/vendor/qz-tray/qz-tray.js) rather than the public CDN. In the UAE/OM/BH region the CDN can be slow or intermittently unreachable, which makes QZ features do nothing. If you ever change this setting, make sure the file physically exists at that path or you'll get a 404 and silent printing won't initialize. You shouldn't need to touch this in a normal install — it's already correct on your site.