quality_recticel/old code/documentation/INSTALLATION_GUIDE.md

Quality Recticel Windows Print Service - Installation Guide

📋 Overview

The Quality Recticel Windows Print Service enables silent PDF printing directly from the web application through a Chrome extension. This system eliminates the need for manual PDF downloads and provides seamless label printing functionality.

🏗️ System Architecture

Web Application (print_module.html)
         ↓
Windows Print Service (localhost:8765)
         ↓
Chrome Extension (Native Messaging)
         ↓
Windows Print System

📦 Package Contents

windows_print_service/
├── print_service.py           # Main Windows service (Flask API)
├── service_manager.py         # Service installation & management
├── install_service.bat        # Automated installation script
├── chrome_extension/          # Chrome extension files
│   ├── manifest.json         # Extension configuration
│   ├── background.js         # Service worker
│   ├── content.js           # Page integration
│   ├── popup.html           # Extension UI
│   ├── popup.js            # Extension logic
│   └── icons/              # Extension icons
└── INSTALLATION_GUIDE.md     # This documentation

🔧 Prerequisites

System Requirements

• Operating System: Windows 10/11 (64-bit)
• Python: Python 3.8 or higher
• Browser: Google Chrome (latest version)
• Privileges: Administrator access required for installation

Python Dependencies

The following packages will be installed automatically:

• flask - Web service framework
• flask-cors - Cross-origin resource sharing
• requests - HTTP client library
• pywin32 - Windows service integration

🚀 Installation Process

Step 1: Download and Extract Files

1. Download the windows_print_service folder to your system
2. Extract to a permanent location (e.g., C:\QualityRecticel\PrintService\)
3. Do not move or delete this folder after installation

Step 2: Install Windows Service

Method A: Automated Installation (Recommended)

1. Right-click on install_service.bat
2. Select "Run as administrator"
3. Click "Yes" when Windows UAC prompt appears
4. Wait for installation to complete

Method B: Manual Installation

If the automated script fails, follow these steps:

# Open Command Prompt as Administrator
cd C:\path\to\windows_print_service

# Install Python dependencies
pip install flask flask-cors requests pywin32

# Install Windows service
python service_manager.py install

# Add firewall exception
netsh advfirewall firewall add rule name="Quality Recticel Print Service" dir=in action=allow protocol=TCP localport=8765

# Create Chrome extension registry entry
reg add "HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.qualityrecticel.printservice" /ve /d "%cd%\chrome_extension\manifest.json" /f

Step 3: Install Chrome Extension

1. Open Google Chrome
2. Navigate to chrome://extensions/
3. Enable "Developer mode" (toggle in top-right corner)
4. Click "Load unpacked"
5. Select the chrome_extension folder
6. Verify the extension appears with a printer icon

Step 4: Verify Installation

Check Windows Service Status

1. Press Win + R, type services.msc, press Enter
2. Look for "Quality Recticel Print Service"
3. Status should show "Running"
4. Startup type should be "Automatic"

Test API Endpoints

Open a web browser and visit:

• Health Check: http://localhost:8765/health
• Printer List: http://localhost:8765/printers

Expected response for health check:

{
  "status": "healthy",
  "service": "Quality Recticel Print Service",
  "version": "1.0",
  "timestamp": "2025-09-21T10:30:00"
}

Test Chrome Extension

1. Click the extension icon in Chrome toolbar
2. Verify it shows "Service Status: Connected ✅"
3. Check that printers are listed
4. Try the "Test Print" button

🔄 Web Application Integration

The web application automatically detects the Windows service and adapts the user interface:

Service Available (Green Button)

• Button text: "🖨️ Print Labels (Silent)"
• Functionality: Direct printing to default printer
• User experience: Click → Labels print immediately

Service Unavailable (Blue Button)

• Button text: "📄 Generate PDF"
• Functionality: PDF download for manual printing
• User experience: Click → PDF downloads to browser

Detection Logic

// Automatic service detection on page load
const response = await fetch('http://localhost:8765/health');
if (response.ok) {
    // Service available - enable silent printing
} else {
    // Service unavailable - fallback to PDF download
}

🛠️ Configuration

Service Configuration

The service runs with the following default settings:

Setting	Value	Description
Port	8765	Local API port
Host	localhost	Service binding
Startup	Automatic	Starts with Windows
Printer	Default	Uses system default printer
Copies	1	Default print copies

Chrome Extension Permissions

The extension requires these permissions:

• printing - Access to printer functionality
• nativeMessaging - Communication with Windows service
• activeTab - Access to current webpage
• storage - Save extension settings

🔍 Troubleshooting

Common Issues

1. Service Not Starting

Symptoms: API not accessible at localhost:8765 Solutions:

# Check service status
python -c "from service_manager import service_status; service_status()"

# Restart service manually
python service_manager.py restart

# Check Windows Event Viewer for service errors

2. Chrome Extension Not Working

Symptoms: Extension shows "Service Status: Disconnected ❌" Solutions:

• Verify Windows service is running
• Check firewall settings (port 8765 must be open)
• Reload the Chrome extension
• Restart Chrome browser

3. Firewall Blocking Connection

Symptoms: Service runs but web page can't connect Solutions:

# Add firewall rule manually
netsh advfirewall firewall add rule name="Quality Recticel Print Service" dir=in action=allow protocol=TCP localport=8765

# Or disable Windows Firewall temporarily to test

4. Permission Denied Errors

Symptoms: Installation fails with permission errors Solutions:

• Ensure running as Administrator
• Check Windows UAC settings
• Verify Python installation permissions

5. Print Jobs Not Processing

Symptoms: API accepts requests but nothing prints Solutions:

• Check default printer configuration
• Verify printer drivers are installed
• Test manual printing from other applications
• Check Windows Print Spooler service

Log Files

Check these locations for troubleshooting:

Component	Log Location
Windows Service	print_service.log (same folder as service)
Chrome Extension	Chrome DevTools → Extensions → Background page
Windows Event Log	Event Viewer → Windows Logs → System

Diagnostic Commands

# Check service status
python service_manager.py status

# Test API manually
curl http://localhost:8765/health

# List available printers  
curl http://localhost:8765/printers

# Check Windows service
sc query QualityRecticelPrintService

# Check listening ports
netstat -an | findstr :8765

🔄 Maintenance

Updating the Service

1. Stop the current service:

python service_manager.py stop

2. Replace service files with new versions

3. Restart the service:

python service_manager.py start

Uninstalling

Remove Chrome Extension

1. Go to chrome://extensions/
2. Find "Quality Recticel Print Service"
3. Click "Remove"

Remove Windows Service

# Run as Administrator
python service_manager.py uninstall

Remove Firewall Rule

netsh advfirewall firewall delete rule name="Quality Recticel Print Service"

📞 Support Information

API Endpoints Reference

Endpoint	Method	Purpose
/health	GET	Service health check
/printers	GET	List available printers
/print/pdf	POST	Print PDF from URL
/print/silent	POST	Silent print with metadata

Request Examples

Silent Print Request:

POST /print/silent
{
    "pdf_url": "http://localhost:5000/generate_labels_pdf/123",
    "printer_name": "default",
    "copies": 1,
    "silent": true,
    "order_id": "123",
    "quantity": "10"
}

Expected Response:

{
    "success": true,
    "message": "Print job sent successfully",
    "job_id": "print_20250921_103000",
    "printer": "HP LaserJet Pro",
    "timestamp": "2025-09-21T10:30:00"
}

📚 Technical Details

Service Architecture

• Framework: Flask (Python)
• Service Type: Windows Service (pywin32)
• Communication: HTTP REST API + Native Messaging
• Security: Localhost binding only (127.0.0.1:8765)

Chrome Extension Architecture

• Manifest Version: 3
• Service Worker: Handles background print requests
• Content Script: Integrates with Quality Recticel web pages
• Native Messaging: Communicates with Windows service

Security Considerations

• Service only accepts local connections (localhost)
• No external network access required
• Chrome extension runs in sandboxed environment
• Windows service runs with system privileges (required for printing)

---

📋 Quick Start Checklist

• Download windows_print_service folder
• Right-click install_service.bat → "Run as administrator"
• Install Chrome extension from chrome_extension folder
• Verify service at http://localhost:8765/health
• Test printing from Quality Recticel web application

Installation Time: ~5 minutes
User Training Required: Minimal (automatic detection and fallback)
Maintenance: Zero (auto-starts with Windows)

For additional support, check the log files and diagnostic commands listed above.