Configurar tamaño de etiqueta Zebra GX420t con PowerShell y ZPL

Automatizar la instalación de una impresora térmica Zebra GX420t desde PowerShell es solo la mitad del trabajo: para evitar errores de corte, textos desplazados o desperdicio de material debes fijar el ancho y alto exactos de la etiqueta durante el mismo despliegue.

Índice

Resumen del escenario

Tu script ya crea el port y la cola de impresión con Add-PrinterPort y Add-Printer, pero necesitas que cada estación reciba las dimensiones correctas de la etiqueta sin abrir la GUI de Windows.

Dónde está la traba

El módulo nativo PrintManagement de Windows PowerShell (Get-Printer, Set-Printer, etc.) no ofrece ningún parámetro para las Preferences del controlador (ancho, alto, velocidad, intensidad). Esa información vive dentro del controlador Zebra y solo puede manipularse:

En forma interactiva (Propiedades de impresora → Preferencias).
Mediante comandos ZPL enviados directamente a la impresora.
Con utilidades de Zebra (Setup Utilities, Set‑Get‑Do, SDKs o WS APIs).

Comparativa de opciones

Opción	¿Qué hace?	¿Cuándo usarla?
GUI del controlador	Ajuste manual de Preferencias → Papel/Calidad	Lotes pequeños o una única PC
ZPL en bruto	Envía `^PW` (ancho) y `^LL` (largo) junto con otros parámetros	Despliegues masivos, CI/CD de impresoras
Herramientas Zebra	Aplicaciones para Windows y APIs REST/CLI	Necesitas un frontend amigable o funciones avanzadas

Por qué ZPL es la vía más fiable

Zebra Programming Language II es entendido por virtualmente todos los modelos térmicos de la marca (GK, GX, ZD, ZT, etc.). Ajustar una vez el valor del ancho (^PW) y la longitud (^LL) los hace persistentes en memoria FLASH hasta que los cambies de nuevo o restablezcas la configuración de fábrica.

Cálculo exacto de los parámetros

Las dimensiones se expresan en dots. Convierte así:

dots = milímetros × (dpi ÷ 25,4)

Por ejemplo, para una etiqueta de 100 mm × 50 mm en una GX420t (203 dpi):

ancho = 100 mm × (203 ÷ 25,4) ≈ 800 dots
largo =  50 mm × (203 ÷ 25,4) ≈ 400 dots

Redondea al entero más próximo. Usar dimensiones exactas evita la “calibración fantasma” que consume etiquetas.

Script de envío ZPL en PowerShell

$ip  = "192.168.1.50"          # IP o hostname de la impresora
$pw  = 800                     # ancho en dots  (100 mm a 203 dpi)
$ll  = 400                     # largo en dots (50 mm  a 203 dpi)
$zpl = "^XA^PW$pw^LL$ll^XZ"    # bloque ZPL

\$client = New-Object System.Net.Sockets.TcpClient
\$client.Connect(\$ip, 9100)     # Puerto RAW TCP
\$stream = \$client.GetStream()
\$writer = New-Object System.IO.StreamWriter(\$stream)
\$writer.Write(\$zpl)
\$writer.Flush()
\$writer.Dispose()
\$client.Close()

Buenas prácticas en el envío

Agrupa todos los comandos de configuración entre ^XA y ^XZ.
Si cambias densidad (^MD) o velocidad (^PR), inclúyelos en la misma ráfaga.
Usa Try / Catch para atrapar fallos de red y dejar un log legible.
Firma digitalmente tu script (Set-AuthenticodeSignature) si la política de ejecución lo requiere.

Pipeline completo de automatización

Add‑PrinterPort – Crea el puerto RAW TCP.
Add‑Printer – Instala la cola con el driver Zebra.
Enviar ZPL – Fija ^PW, ^LL y demás preferencia.
(Opcional) Add‑Printer –ShareName – Publica la impresora.
Probar – Imprime una etiqueta demo.

Código combinado: instalar + configurar

param(
    [string]$PrinterName   = "Zebra GX420t",
    [string]$IP            = "192.168.1.50",
    [string]$PortName      = "GX420t_9100",
    [int]   $DPI           = 203,
    [double]$WidthMM       = 100,
    [double]$HeightMM      = 50
)

function ConvertTo-Dots {
param(\$mm, \$dpi)
return \[math]::Round(\$mm \* (\$dpi / 25.4))
}

Paso 1: Puerto

if (-not (Get-PrinterPort -Name \$PortName -ErrorAction SilentlyContinue)) {
Add-PrinterPort -Name \$PortName -PrinterHostAddress \$IP
}

Paso 2: Cola

if (-not (Get-Printer -Name \$PrinterName -ErrorAction SilentlyContinue)) {
Add-Printer -Name \$PrinterName -DriverName "ZDesigner GX420t" -PortName \$PortName
}

Paso 3: Parámetros ZPL

\$pw = ConvertTo-Dots -mm \$WidthMM  -dpi \$DPI
\$ll = ConvertTo-Dots -mm \$HeightMM -dpi \$DPI
\$zpl = "^XA^PW\$pw^LL\$ll^XZ"

\[byte\[]]\$bytes = \[Text.Encoding]::ASCII.GetBytes(\$zpl)
\$socket = New-Object System.Net.Sockets.TcpClient(\$IP, 9100)
\$stream = \$socket.GetStream()
\$stream.Write(\$bytes, 0, \$bytes.Length)
\$stream.Close()
\$socket.Close()

Write-Host "Configuración aplicada: \${WidthMM}x\${HeightMM} mm a \$DPI dpi"

Cómo verificar que la impresora aceptó los valores

Envía ~HS y captura la respuesta:

$socket = New-Object System.Net.Sockets.TcpClient($IP, 9100)
$stream = $socket.GetStream()
$writer = New-Object System.IO.StreamWriter($stream)
$writer.Write("~HS")
$writer.Flush()
$reader = New-Object System.IO.StreamReader($stream)
$response = $reader.ReadToEnd()
$writer.Dispose(); $reader.Dispose(); $socket.Close()
$response -split "`n" | Select-String -Pattern "LABEL LENGTH|PRINT WIDTH"

Deberías ver líneas semejantes a:

PRINT WIDTH:  800 dots
LABEL LENGTH: 400 dots

Consejos de producción

Perfil de red mínimo: limita el acceso al puerto 9100 a los servidores que ejecutan el script.
Sustentabilidad: documenta las dimensiones por SKU en tu repositorio Git, así podrás auditar cambios.
Rollback rápido: conserva un script de “valores por defecto” para revertir si las etiquetas salen truncadas.
Monitorización: agrega un test con Test-Connection -Quiet antes de abrir el socket para marcar impresoras apagadas.
Driver v8 vs v5: si tu organización migra a ZebraDesigner Driver Version 8, vuelve a validar que los comandos ZPL permanezcan persistentes; algunas revisiones reinician el buffer al actualizar firmware.
WinRM / PSRemoting: firma y codifica el script para enviarlo como una constrained endpoint y ejecutar sin credenciales de dominio en texto claro.

Preguntas frecuentes

¿Puedo cambiar el tamaño con `Set‑PrintConfiguration`?

No. Ese cmdlet manipula márgenes y orientación genéricos de Windows, no las preferencias propietarias del controlador Zebra.

¿Es mejor usar la API REST de Zebra?

Las impresoras Link‑OS modernas exponen un endpoint REST que ejecuta comandos Set‑Get‑Do. Si tu parque es heterogéneo (GX420t + ZD620), la combinación ZPL + REST es ideal: envías el mismo ^XA^PW…^XZ en JSON y recibes un 2xx de confirmación.

¿Qué sucede si la impresora está en pausa?

Los comandos ZPL se almacenan en el búfer hasta que se pulse Feed o se libere la pausa. Por eso conviene enviar primero la configuración y luego la etiqueta de prueba, evitando que el usuario crea que “no imprime”.

Check‑list antes de clonar tu script en todo el dominio

📶 Ping estable: < 1 % de pérdida de paquetes.
🖥️ Controladores instalados en todos los nodos RDS.
🔒 GPO que prohíbe cambiar Preferencias manualmente.
📝 Documentación de los códigos de error ZPL (^ERROR).
📤 Job de backup que exporta Get-Printer a CSV para auditoría mensual.

Conclusión

Al integrar el envío de comandos ZPL dentro del mismo script que crea la cola de impresión, obtienes un proceso reproducible, sin intervención manual y sin sorpresas de desalineación. Esta técnica funciona desde Windows 7 hasta Windows 11 y cubre cualquier modelo Zebra compatible con ZPL II.