PrinterWebSocket Framework

Introduction

PrinterWebSocket is a lightweight, open-source framework that enables web applications to communicate directly with POS printers through WebSocket connections. Built as a free alternative to commercial solutions like JSPM and QZ Tray, this framework allows silent printing without user prompts, making it perfect for automation and POS systems.

The framework consists of a Python WebSocket server with a built-in GUI for monitoring, and a vanilla JavaScript client that seamlessly integrates into any web application. It supports thermal POS printers using TSPL raw commands and provides real-time printer status monitoring.

⚠️ Development Phase: This project is actively being developed. While it works well with thermal POS printers, support for additional printer models is ongoing. Contributions are welcome!

Key Features

🖨️

Silent Printing

Print directly without user prompts or confirmation dialogs. Perfect for automated POS systems and kiosk applications.

🔌

WebSocket Communication

Real-time bidirectional communication between web apps and printers using WebSocket protocol.

📊

Real-Time Monitoring

Built-in GUI to monitor connected clients, server activity, and printer statuses in real-time.

🎯

Printer Discovery

Automatically list all available printers connected to the server with their current status.

⚡

TSPL Support

Native support for TSPL commands for thermal POS printers with raw command execution.

🌐

Cross-Platform

Works on Windows, macOS, and Linux. Currently optimized for Windows with pywin32.

Architecture

Server Components

printer_server.py - Main WebSocket server with printer handling
requirements.txt - Python dependencies
Built-in GUI for monitoring and client management
Real-time logging and error tracking

Client Components

PrinterWebSocket.js - Vanilla JavaScript client library
Promise-based API for async operations
Automatic connection management
Event-driven architecture

Installation & Setup

Prerequisites

Make sure you have the following installed:

Python 3.x
websockets - WebSocket communication
pywin32 - Windows printer handling
tkinter - GUI (usually included with Python)

Step 1: Install Dependencies

Step 2: Start the Server

Run the WebSocket server with the built-in GUI:

The server will start on port 8765 by default. You can modify this in the server code.

Step 3: Include Client Library

Add the JavaScript client to your web application:

Quick Start Guide

Initialize Connection

Establish a WebSocket connection to the printer server:

                // Initialize WebSocket connection
PrinterWebSocket.initialize("ws://localhost:8765")
    .then(() => {
        console.log('Connected to Printer Server');
        console.log('Server Address:', PrinterWebSocket.getServerAddress());
        
        // Fetch available printers
        return PrinterWebSocket.fetchPrinters();
    })
    .then((printers) => {
        console.log('Available Printers:', printers);
        populatePrinterDropdown(printers);
    })
    .catch((error) => {
        console.error("Connection Error:", error);
    });
            

Send a Print Job

Send TSPL commands to print a receipt or label:

                // Define paper size and TSPL commands
var paperSize = "80*40"; // 80mm x 40mm
var printerName = "Gprinter GP-3120TUC";

var tsplData = `
SIZE 80 mm, 40 mm
GAP 3 mm, 0 mm
CLS
TEXT 25,60,"4",0,1,1,"26 OCT T 07"
TEXT 25,120,"5",0,1,1,"105570553"
TEXT 25,180,"1",0,1,1,"Liopetra"
PRINT 1,1
`;

// Send print job
PrinterWebSocket.print(printerName, tsplData)
    .then(() => {
        console.log('Print job sent successfully');
    })
    .catch((error) => {
        console.error('Print error:', error);
    });
            

Complete Example

A full working example with printer selection:

                <!DOCTYPE html>
<html>
<head>
    <title>Printer WebSocket Demo</title>
    <script src="printerWebSocket.js"></script>
</head>
<body>
    <h1>POS Printer Demo</h1>
    
    <select id="printerSelect">
        <option>Select Printer...</option>
    </select>
    
    <button onclick="printReceipt()">Print Receipt</button>

    <script>
        // Initialize connection
        PrinterWebSocket.initialize("ws://localhost:8765")
            .then(() => PrinterWebSocket.fetchPrinters())
            .then(printers => {
                const select = document.getElementById('printerSelect');
                printers.forEach(printer => {
                    const option = document.createElement('option');
                    option.value = printer;
                    option.text = printer;
                    select.add(option);
                });
            });

        function printReceipt() {
            const printer = document.getElementById('printerSelect').value;
            const tspl = `
                SIZE 80 mm, 40 mm
                GAP 3 mm, 0 mm
                CLS
                TEXT 25,25,"4",0,1,1,"Test Print"
                PRINT 1,1
            `;
            PrinterWebSocket.print(printer, tspl);
        }
    </script>
</body>
</html>
            

API Reference

1. List Available Printers

Retrieve all printers connected to the server.

Request

Field	Value
`call`	"printers.find"
`uid`	"unique-request-id"

                { 
    "call": "printers.find", 
    "uid": "hHOIa02asXJ" 
}
            

Response

                { 
    "uid": "hHOIa02asXJ", 
    "result": ["Printer1", "Printer2", "Printer3"], 
    "status_code": 0 
}
            

2. Get Server Version

Check the current version of the printer server.

Request

                { 
    "call": "server.version", 
    "uid": "hHOIa02asXJ" 
}
            

Response

                { 
    "uid": "hHOIa02asXJ", 
    "result": "0.1.0", 
    "info": "serverVersion", 
    "status_code": 0 
}
            

3. Send Print Job

Send TSPL commands to a specific printer for printing.

Request

Field	Value
`call`	"print"
`uid`	"unique-request-id"
`params.printer.name`	"Gprinter GP-3120TUC"
`params.data`	Array of TSPL commands

                { 
    "call": "print", 
    "uid": "unique-request-id", 
    "params": { 
        "printer": { 
            "name": "Gprinter GP-3120TUC" 
        }, 
        "data": [ 
            "SIZE 100 mm, 150 mm", 
            "GAP 3 mm, 0", 
            "TEXT 100,100,\"TSS24.BF2\",0,1,1,\"Hello World\"", 
            "PRINT 1,1" 
        ] 
    } 
}
            

Success Response

                { 
    "uid": "unique-request-id", 
    "status": "success", 
    "message": "Printed on Gprinter GP-3120TUC", 
    "status_code": 0 
}
            

Error Response

                { 
    "uid": "unique-request-id", 
    "status": "error", 
    "message": "Invalid printer or TSPL data", 
    "status_code": 3 
}
            

4. Check Printer Status

⚠️ Experimental Feature: This feature is still in testing and may not work with all printers. There are limitations in the pywin32 library for retrieving real-time printer status.

Request

                { 
    "call": "printerStatus", 
    "uid": "unique-request-id", 
    "PrinterName": "Gprinter GP-3120TUC" 
}
            

Response Examples

Idle Printer:

                { 
    "uid": "unique-request-id", 
    "status": "Printer status retrieved", 
    "PrinterName": "Gprinter GP-3120TUC", 
    "status_code": 0 
}
            

Printing:

                { 
    "uid": "unique-request-id", 
    "status": "Printer status retrieved", 
    "PrinterName": "Gprinter GP-3120TUC", 
    "status_code": 1 
}
            

Error State:

                { 
    "uid": "unique-request-id", 
    "status": "Printer status retrieved", 
    "PrinterName": "Gprinter GP-3120TUC", 
    "status_code": 3 
}
            

Status Codes

Code	Status	Description
0	Success / Idle	Operation completed successfully or printer is idle
1	Printing	Printer is currently processing a print job
3	Error	Printer encountered an error or operation failed

Use Cases & Examples

Restaurant POS System

Print kitchen orders and customer receipts automatically:

                // Print kitchen order
function printKitchenOrder(orderData) {
    const tspl = `
        SIZE 80 mm, 100 mm
        GAP 3 mm, 0 mm
        CLS
        TEXT 25,25,"4",0,1,1,"KITCHEN ORDER #${orderData.id}"
        TEXT 25,80,"3",0,1,1,"Table: ${orderData.table}"
        TEXT 25,130,"2",0,1,1,"${orderData.items.join(', ')}"
        TEXT 25,180,"2",0,1,1,"Time: ${new Date().toLocaleTimeString()}"
        PRINT 1,1
    `;
    
    PrinterWebSocket.print("Kitchen Printer", tspl);
}

// Print customer receipt
function printReceipt(orderData) {
    const tspl = `
        SIZE 80 mm, 150 mm
        GAP 3 mm, 0 mm
        CLS
        TEXT 25,25,"4",0,1,1,"RECEIPT"
        TEXT 25,75,"2",0,1,1,"Order #${orderData.id}"
        TEXT 25,110,"2",0,1,1,"Total: ${orderData.total}"
        TEXT 25,145,"1",0,1,1,"Thank you for dining with us!"
        PRINT 1,1
    `;
    
    PrinterWebSocket.print("Receipt Printer", tspl);
}
            

Retail Label Printing

Generate product labels with barcodes:

                function printProductLabel(product) {
    const tspl = `
        SIZE 50 mm, 30 mm
        GAP 2 mm, 0 mm
        CLS
        TEXT 10,10,"3",0,1,1,"${product.name}"
        TEXT 10,50,"2",0,1,1,"Price: ${product.price}"
        BARCODE 10,90,"128",60,1,0,2,2,"${product.barcode}"
        PRINT 1,1
    `;
    
    PrinterWebSocket.print("Label Printer", tspl);
}
            

Shipping Label System

Create shipping labels with tracking information:

                function printShippingLabel(shipment) {
    const tspl = `
        SIZE 100 mm, 150 mm
        GAP 3 mm, 0 mm
        CLS
        TEXT 25,25,"4",0,1,1,"SHIP TO:"
        TEXT 25,70,"2",0,1,1,"${shipment.recipient}"
        TEXT 25,105,"2",0,1,1,"${shipment.address}"
        TEXT 25,140,"2",0,1,1,"${shipment.city}, ${shipment.zip}"
        BARCODE 25,190,"128",80,1,0,2,2,"${shipment.tracking}"
        TEXT 25,290,"1",0,1,1,"Tracking: ${shipment.tracking}"
        PRINT 1,1
    `;
    
    PrinterWebSocket.print("Shipping Printer", tspl);
}
            

Testing & Development

WebSocket Testing Tools

You can test the server using various WebSocket clients:

Browser DevTools: Use the WebSocket API in the browser console
Postman: Create WebSocket requests for testing
wscat: Command-line WebSocket client

Example Test with Browser Console

                // Open browser console and run:
const ws = new WebSocket('ws://localhost:8765');

ws.onopen = () => {
    console.log('Connected');
    
    // Test: Get printer list
    ws.send(JSON.stringify({
        call: "printers.find",
        uid: "test-123"
    }));
};

ws.onmessage = (event) => {
    console.log('Response:', JSON.parse(event.data));
};
            

Server GUI Features

The built-in GUI provides:

Real-time server activity logging
Connected clients list with details
Error tracking and diagnostics

Connection status monitoring
Print job history
Server configuration display

Troubleshooting

Common Issues

Connection Refused

Problem: Cannot connect to ws://localhost:8765

Solution:

Ensure the Python server is running
Check if port 8765 is not blocked by firewall
Verify the server address and port in your client code

Printer Not Found

Problem: Printer doesn't appear in the list

Solution:

Verify printer is connected and powered on
Check printer drivers are installed correctly
Ensure printer is set as online in Windows
Restart the printer server

Print Job Fails

Problem: Print command returns error

Solution:

Verify TSPL commands are correctly formatted
Check printer supports TSPL command set
Ensure printer has paper loaded
Review server logs for detailed error messages

Windows-Specific Issues

Problem: pywin32 installation errors

Solution:

Use pip install pywin32 with administrator privileges
Run python Scripts/pywin32_postinstall.py -install after installation
Ensure Visual C++ redistributables are installed

Known Limitations

Platform Compatibility

Currently optimized for Windows environments using pywin32. Support for macOS and Linux is planned but may require additional development for printer interactions.

Printer Status Retrieval

The printer status feature has limitations due to pywin32 library constraints. It can create print jobs successfully, but real-time status monitoring may not work with all printer models.

Printer Model Support

Tested primarily with thermal POS printers using TSPL commands. Support for other printer types and command languages is in development. Community testing and contributions are welcome!

Contributing

PrinterWebSocket is an open-source project and welcomes contributions! Here's how you can help:

🐛 Report Issues

Found a bug? Report it on our GitHub Issues page with details about your printer model and environment.

🔧 Submit Pull Requests

Have a fix or new feature? Fork the repository, make your changes, and submit a pull request for review.

📝 Improve Documentation

Help others by improving documentation, adding examples, or translating content.

🧪 Test with Different Printers

Test with various printer models and share your results to improve compatibility.

Downloads

Get the latest version of PrinterWebSocket from GitHub:

Download Latest Version View All Releases

Project Files

File	Description
`printer_server.py`	Main WebSocket server with printer handling and GUI
`PrinterWebSocket.js`	Vanilla JavaScript client library for web applications
`requirements.txt`	Python dependencies list
`README.md`	Project documentation and usage guide

Contact & Support

Have questions or need support? Get in touch with us:

📧

Email

gturabi201467@bscse.uiu.ac.bd

💬

GitHub

Open an Issue

📛

Facebook

@tawsiftorabi

Community Links

Connect with the PrinterWebSocket community

GitHub Issues LinkedIn Facebook

License & Credits

PrinterWebSocket is an open-source project created as a free alternative to commercial solutions like JSPM and QZ Tray.

Author: Tawsif Torabi
Repository: github.com/TawsifTorabi/PrinterWebsocket

This project is provided as-is for educational and commercial use. While it's free to use, contributions and support are always welcome to help improve the framework for everyone.