Help & Setup Guide - Epson Thermal Print Bridge

1. System Architecture & Hardware Setup

Architecture

This application acts as a high-performance, cross-platform local printing bridge between Odoo 17 Point of Sale (or any custom web app) and Epson TM-T20X-058 thermal printers over Ethernet (TCP Port 9100).

Thermal Printer Connection: Connect your Epson printer via Ethernet cable to your local network router or switch.
Paper Size: Optimized for 58mm thermal paper rolls (32 columns per line).
Port 9100 Raw Socket: Directly transmits ESC/POS byte buffers to the printer head with sub-10ms latency.

2. Odoo 17 POS Module Installation

Odoo Integration

Copy the custom addon folder pos_local_escpos/ into your Odoo 17 custom_addons/ directory.
In Odoo, navigate to Apps, click Update Apps List, and install POS Local ESC/POS Direct Thermal Printer.
Go to Point of Sale ➔ Configuration ➔ Settings, enable Use Local ESC/POS Printer, and set the bridge URL:
http://127.0.0.1:3000/print
Click Save. In POS, receipts will automatically send directly to your thermal printer!

3. Multi-Printer SQLite Routing (Caisse vs. Kitchen)

SQLite Database

You can manage multiple printers (e.g. caisse, kitchen, bar) in your establishment:

Registering Printers: Go to the Dashboard and click + Add Printer. Register names like caisse (192.168.3.242) and kitchen (192.168.3.243).
Targeting in Request JSON: Pass "printer_name": "kitchen" in your JSON payload to direct the print job to that printer.
Default Printer Fallback: If printer_name is omitted, the bridge automatically prints to the Default Printer marked in SQLite.

4. Supported JSON Payload Examples

API Reference

A. POS Customer Order Receipt

{
  "printer_name": "caisse",
  "title": "BON DE COMMANDE",
  "order_name": "SO00053",
  "customer_name": "Rania BOULHOUACHE",
  "logo": true,
  "items": [
    { "name": "CHICKEN BOWL", "quantity": 1, "price": 1300, "subtotal": 1300 }
  ],
  "total": 1300
}
            

B. Kitchen Preparation Ticket

{
  "printer_name": "kitchen",
  "title": "TICKET DE CUISINE",
  "order_name": "SO00053",
  "items": [
    { "name": "PIZZA MARGHERITA", "quantity": 2 }
  ]
}
            

C. Generic Text Report

{
  "text": "RAPPORT DE CAISSE DU 12/08/2026\n================================\nTOTAL: 195 000 DA"
}
            

D. Custom Base64 Logo Image

{
  "title": "OLA RESTAURANT",
  "logo": "data:image/png;base64,iVBORw0KGgoAAA...",
  "items": [ ... ],
  "total": 1500
}
            

5. Troubleshooting & FAQ

Diagnostic

Paper feeds but remains blank? Turn off printer, open roll cover, flip thermal paper roll upside down (thermal side facing heating head), close cover, and re-test.
Special characters (!@#$) instead of logo? The bridge uses ESC * 33 24-dot bit-image mode with zero line spacing reset, eliminating text dumps on Epson firmware.
Connection timeout to IP? Ensure PC and printer share the same LAN subnet (e.g. 192.168.3.x) and port 9100 is open.