adaptronic_label-printer/old_code/PRINTER_CONFIGURATION.md

# Thermal Printer Paper Size Configuration Guide

## Problem
When printing labels, the PDF is generated correctly at 35mm x 25mm, but SumatraPDF prints them scaled to the printer's currently configured paper size. This results in incorrectly sized labels.

## Root Cause
SumatraPDF's `noscale` mode preserves the PDF content but still uses the **Windows printer's configured paper size**. If the printer is set to A4, Letter, or continuous roll, the label will be scaled to that size.

## Solution
Configure your thermal printer in Windows with the correct paper size (35mm x 25mm).

---

## Quick Setup

### Step 1: Run Configuration Helper
```powershell
powershell -ExecutionPolicy Bypass -File configure_printer_paper_size.ps1
```

### Step 2: Manual Configuration

#### For Citizen CTS-310 Printers:
1. Open **Control Panel** → **Devices and Printers**
2. Right-click **Citizen CTS-310II** → **Printing Preferences**
3. Under **Page Layout** or **Paper Settings**:
   - **Paper Size**: Custom
   - **Width**: 35mm (1.38 inches)
   - **Height**: 25mm (0.98 inches)
   - **Orientation**: Landscape
4. Click **Apply** → **OK**

#### For Zebra ZD420/ZD421 Printers:
1. Open **Zebra Setup Utility** (ZSU) or Settings
2. Select your printer
3. Configure **Media**:
   - **Media Type**: Label Stock (NOT Continuous)
   - **Label Width**: 35mm
   - **Label Height**: 25mm
4. Configure **Print Quality**:
   - **Darkness**: 10-15
   - **Print Speed**: 4 ips
5. **Send to Printer**

---

## Critical Settings

### ⚠️ Media Type MUST be "Labels" or "Label Stock"
- **Correct**: Media Type = Labels (enables gap sensor)
- **Wrong**: Media Type = Continuous (prints entire roll, ignores gaps)

### Paper Dimensions
- **Width**: 35mm
- **Height**: 25mm  
- **Orientation**: Landscape (35mm is width, 25mm is height)

### Print Quality (Thermal Printers)
- **Darkness**: 10-15 (NOT DPI - thermal printers use darkness control)
- **Speed**: Medium (4 ips recommended)
- **Resolution**: 203-300 DPI (hardware fixed, not configurable)

---

## Verification

### Test Your Configuration:
1. Start the GUI:
   ```bash
   python label_printer_gui.py
   ```

2. Add test data to `C:\Users\Public\Documents\check.txt`:
   ```
   COM-001;ART-123;SN-001;0;1
   ```

3. Check the printed label:
   - ✅ Should be exactly 35mm x 25mm
   - ✅ Should fit the label perfectly (no scaling)
   - ✅ Should stop at label gap (not continue on roll)

### If Labels are Wrong Size:
- Too large → Printer paper size is too big (check Windows printer settings)
- Too small → PDF might be generated incorrectly (check pdf_backup/ folder)
- Continuous printing → Media Type is set to "Continuous" instead of "Labels"

---

## Windows Custom Paper Size (Advanced)

If your printer driver doesn't have 35mm x 25mm preset:

### Create Custom Form:
1. Open **Control Panel** → **Devices and Printers**
2. Select any printer → **Print Server Properties** (top menu)
3. Check **"Create a new form"**
4. Form name: **Label35x25**
5. Width: **3.50 cm** (35mm)
6. Height: **2.50 cm** (25mm)
7. Click **Save Form**
8. Now this form will be available in all printer settings

### Assign Form to Printer:
1. Right-click your thermal printer → **Printer Properties** (not Preferences)
2. **Device Settings** tab
3. **Form to Tray Assignment** → Select **Label35x25**
4. Apply → OK

---

## Troubleshooting

### Problem: Labels still wrong size after configuration
**Solution**: 
- Restart the printer
- Restart the print spooler: `net stop spooler && net start spooler`
- Check if driver supports custom sizes (some old drivers don't)

### Problem: Printer prints continuously without stopping
**Solution**: 
- Change Media Type from "Continuous" to "Labels"
- Enable gap sensor in printer settings
- Calibrate media (Zebra: hold feed button 2 seconds)

### Problem: Dotted or poor quality text
**Solution**: 
- Increase darkness setting (10-15 recommended)
- Clean printhead
- Check ribbon (thermal transfer) or label quality

---

## File Format (check.txt)

```
ARTICLE;NR_ART;SERIAL;TEMPLATE_TYPE;COUNT
```

Examples:
- `COM-001;ART-123;SN-001;0;1` = 1 OK label (green checkmark)
- `COM-002;ART-456;SN-002;1;2` = 2 NOK labels (red text + "NOK")

Template Types:
- **0** = OK template (green checkmark, "OK" text)
- **1** = NOK template (red text, red checkmark, "NOK" text)

---

## Technical Details

### PDF Generation Pipeline:
1. **SVG Template** (conf/label_template_*.svg)
   - Dimensions: `width="35mm" height="25mm"`
   - Variables: `{Article}`, `{NrArt}`, `{Serial}`

2. **CairoSVG Conversion**
   - Converts SVG → PDF at 300 DPI
   - Preserves SVG dimensions (35mm x 25mm)

3. **SumatraPDF Printing**
   - Uses `-print-settings noscale` (no scaling)
   - Sends PDF directly to printer
   - Uses printer's configured paper size

### Why Paper Size Configuration is Critical:
SumatraPDF's `noscale` tells it "don't scale the PDF content", but the **printer driver** still needs to know what paper size to use. If the driver thinks it's printing on A4 paper, it will center the 35mm label on an A4 page.

By configuring the printer with 35mm x 25mm paper, the driver knows to feed labels of that size, and SumatraPDF will print the PDF content unscaled to match.

---

## Support

For issues:
1. Check printer configuration: `configure_printer_paper_size.ps1`
2. Verify PDF dimensions: Open file from `pdf_backup/` in Adobe Reader
3. Check logs: `logs/print_log_YYYYMMDD.csv`
4. Test with Microsoft Print to PDF first (configure it for 35mm x 25mm)