Fix Odoo POS Receipt Printing Not Working: Printer Setup and Troubleshooting

The POS Printing Problem

Receipt printing is fundamental to point of sale operations. When the printer stops working — no output, blank receipts, garbled text, or connection errors — checkout lines back up and customers get frustrated. Odoo POS supports several printing methods, and each has its own failure modes.

Printing Methods in Odoo POS

Odoo POS can print receipts through:

1. IoT Box (recommended): Dedicated hardware that connects to USB/network printers
2. Direct browser printing: Uses the browser's print dialog
3. ePos (Epson ePOS SDK): Direct network printing to Epson TM-series printers
4. CUPS printing: Linux printing system via the server

Cause 1: IoT Box Not Connected

# Symptoms:
# - "No IoT Box found" in POS settings
# - Printer icon shows disconnected
# - "Could not connect to IoT Box" error

# Fix:
# 1. Check IoT Box is powered on and has a green LED
# 2. Find IoT Box IP: check your router's DHCP table
#    Or connect a monitor to the IoT Box to see its IP
# 3. Access IoT Box interface: http://IoT-BOX-IP:8069
# 4. In Odoo: IoT → IoT Boxes → verify the box appears
# 5. If not found: re-pair the IoT Box
#    IoT → IoT Boxes → Connect → Enter token from IoT Box screen

Cause 2: Printer Not Detected by IoT Box

# Fix:
# 1. Access IoT Box web interface: http://IoT-BOX-IP:8069
# 2. Go to Printers section — your printer should be listed
# 3. If not listed:
#    - Unplug and replug the USB printer
#    - Wait 30 seconds for detection
#    - Restart the IoT Box (unplug power, wait 10 seconds, replug)
# 4. For network printers:
#    - Ensure printer is on same network as IoT Box
#    - Printer must support ESC/POS or Star protocol
# 5. Check IoT Box logs for driver errors

Cause 3: Wrong Printer Driver or Protocol

Receipt printers use specific protocols. Using the wrong one produces garbled output or no output.

# Common receipt printer protocols:
# - ESC/POS (Epson, most compatible)
# - StarPRNT (Star Micronics)
# - CPCL/ZPL (Zebra label printers — not for receipts)

# In Odoo POS configuration:
# Point of Sale → Configuration → Point of Sale → Select POS
# Connected Devices section:
# Receipt Printer: Select your printer from the IoT device list
# Ensure the correct printer type is selected

# For Epson printers without IoT Box (ePos):
# 1. Enable ePos in printer settings
# 2. Enter printer IP address
# 3. Printer must have ePOS SDK enabled in its web configuration

Cause 4: Browser Print Dialog Issues

When using browser-based printing (no IoT Box), the browser's print dialog interferes.

# Symptoms:
# - Browser print dialog appears for every receipt
# - Print goes to the wrong printer (office printer instead of receipt printer)
# - Receipt formatting is wrong (too wide, cut off)

# Fix Option 1: Set default printer in OS
# Set the receipt printer as the system default printer
# Windows: Settings → Printers → Set as default
# macOS: System Preferences → Printers → Default printer
# Linux: lpadmin -d receipt_printer_name

# Fix Option 2: Use Chrome's silent printing
# Chrome flag: --kiosk-printing
# This skips the print dialog and prints to the default printer
# Launch Chrome: chrome --kiosk-printing https://your-odoo.com/pos/ui

Cause 5: Receipt Template Errors

Custom receipt templates with syntax errors produce blank or partial receipts.

# Check for template errors:
# Point of Sale → Configuration → Point of Sale
# Receipt section → check "Receipt Header" and "Receipt Footer"
# Remove any HTML tags or special characters that may cause issues

# If using a custom receipt template module:
# Check the QWeb template for XML syntax errors
# Common issue: unclosed tags, invalid expressions
# Test by reverting to the default template first

Cause 6: HTTPS and Mixed Content

If Odoo runs on HTTPS but the IoT Box or printer uses HTTP, the browser blocks the connection.

# Symptoms:
# - Printer found in settings but fails during actual printing
# - Browser console shows: "Mixed Content: ... was loaded over HTTPS
#   but requested an insecure resource"

# Fix Option 1: Enable HTTPS on IoT Box
# IoT Box web interface → Settings → Enable HTTPS
# Upload or generate an SSL certificate

# Fix Option 2: Use IoT Box through Odoo's IoT proxy
# The IoT integration routes through Odoo's server
# avoiding direct browser-to-IoT communication

# Fix Option 3 (development only):
# Access Odoo via HTTP instead of HTTPS

Cause 7: Paper or Hardware Issues

# Check these physical issues:
# 1. Paper roll empty or jammed — open printer, check paper path
# 2. Paper loaded backwards — thermal paper only prints on one side
#    Test: scratch the paper with a fingernail, the printing side darkens
# 3. Print head dirty — clean with isopropyl alcohol and cotton swab
# 4. Printer in error state — turn off, wait 10 seconds, turn on
# 5. USB cable loose — reseat both ends
# 6. Power adapter disconnected — check power LED on printer

Cause 8: Cash Drawer Connected Through Printer

Many setups run the cash drawer signal through the receipt printer. If the printer is not working, the cash drawer will not open either.

# In POS settings:
# Connected Devices → Cash Drawer → ensure it is linked to the printer
# The cash drawer receives an open command through the printer's RJ11 port
# If the printer is disconnected, the cash drawer command fails silently

Testing Receipt Printing

# 1. Test printer independently:
# - Print a self-test page (usually hold Feed button while powering on)
# - If self-test prints, printer hardware is fine

# 2. Test from IoT Box:
# - Access IoT Box web interface
# - Click "Print test page" next to the printer

# 3. Test from Odoo POS:
# - Open POS session
# - Make a test sale
# - Click Print Receipt

# 4. Check browser console (F12) for JavaScript errors:
# - Look for connection refused, timeout, or CORS errors