Una impresora de tickets parece un periférico sencillo hasta que aparece una ñ convertida en otro símbolo, el logo sale cortado, el cajón se abre dos veces o un reintento genera dos recibos. La dificultad de ESC/POS no es aprender tres bytes: es controlar la frontera entre documento, encoder, transporte y estado físico del dispositivo.
En este artículo analizamos la familia de comandos ESC/POS con referencia a la documentación oficial de Epson. El foco es diseño de drivers y recuperación operacional para POS. No se presupone que todos los equipos de 58 u 80 mm soporten las mismas funciones. El laboratorio propuesto es conceptual y los casos de hardware están pendientes de ejecución. La compatibilidad de una secuencia depende de fabricante, modelo, firmware, interfaz y configuración.
ESC/POS no equivale a una única especificación universal
ESC/POS es una familia de comandos usada por impresoras de recibos. Una combinación de bytes puede expresar «alinear al centro», «imprimir un símbolo QR» o «consultar el estado». Pero incluso cuando dos dispositivos dicen ser compatibles, sus conjuntos de comandos, parámetros, tablas de caracteres, modos de gráfico y estados pueden diferir.
La matriz de impresoras compatibles de Epson muestra qué comandos aplica cada modelo. Fabricantes como Star y Bixolon también publican especificaciones propias. Por tanto, no existe base suficiente para la afirmación «ESC @, GS V y todos los códigos QR funcionan en cualquier impresora térmica». La capacidad debe consultarse o probarse para el modelo concreto.
| Capa | Pregunta de compatibilidad | Ejemplo |
|---|---|---|
| Comando | ¿Existe en este modelo y firmware? | GS V para corte, GS ( k para QR |
| Parámetros | ¿Qué rangos y variantes acepta? | Tamaño de módulo QR, tipo de corte |
| Codificación | ¿Qué página se selecciona con cada n? | ESC t n y CP858/CP850 |
| Transporte | ¿Hay canal de lectura de status? | USB, TCP raw, spooler/driver de OS |
| Estado físico | ¿Cortó, imprimió y tiene papel? | Sensores, cutter, buffer de impresión |
Separar estas capas permite versionar un perfil de dispositivo y evitar una clase con cientos de excepciones condicionales dispersas.
El pipeline del ticket: de datos a bytes
Un ticket suele comenzar como una estructura de dominio: identificador, líneas de venta, cantidades, impuestos, moneda y un pie. En esa etapa no deberían existir comandos ESC/POS ni cortes manuales de strings según el número fijo de caracteres. Después vienen layout, encoding y transporte.
Venta confirmada / número de documento
↓
Modelo de ticket (datos tipados, importes y orden de líneas)
↓
Layout (ancho imprimible, columnas, estilos y desbordes)
↓
Encoder por perfil (code page, QR, imagen, comandos soportados)
↓
Payload de bytes inmutable + checksum/hash
↓
Transport adapter (USB, TCP, spooler) + observación de estado
↓
Job ledger (resultado confirmado, fallido o ambiguo)
Esto es importante: un write() exitoso sobre un socket puede significar que el sistema operativo aceptó bytes, no que la impresora los haya convertido en papel. Tampoco equivale a un commit de transacción en la aplicación que creó el pedido. Conservar un identificador único de trabajo es más útil que registrar solamente «print success».
Caracteres españoles: ESC t no activa UTF-8
El código original de este artículo mostraba ESC t 16 seguido de text.encode('utf-8'). Esa combinación era conceptualmente incorrecta: ESC t n selecciona una tabla de caracteres, mientras que UTF-8 es una codificación multibyte. Un valor n asociado a CP858 en determinados modelos no convierte automáticamente el parser del dispositivo en un decodificador UTF-8.
La referencia ESC t de Epson especifica que el rango de n y la tabla correspondiente dependen del modelo. Incluso una página de códigos disponible puede no estar seleccionada con el mismo identificador en equipos de fabricantes distintos.
Supongamos que el perfil del modelo confirma una tabla compatible con cp858 y conoce su valor n. Entonces el encoder podría ser:
from dataclasses import dataclass
ESC = b"\x1b"
GS = b"\x1d"
@dataclass(frozen=True)
class PrinterProfile:
model: str
codepage_number: int # Valor verificado en documentación del equipo.
python_codec: str # Ej.: "cp858", NO implica soporte UTF-8.
supports_cut: bool
supports_qr: bool
def select_codepage_and_encode(profile: PrinterProfile, text: str) -> bytes:
if not 0 <= profile.codepage_number <= 255:
raise ValueError("Número de tabla ESC t fuera de rango")
encoded = text.encode(profile.python_codec, errors="strict")
return ESC + b"t" + bytes([profile.codepage_number]) + encoded
El punto decisivo no es adivinar codepage_number=16. Es verificar la correspondencia entre n y python_codec para un modelo/firmware y probar caracteres como á é í ó ú ñ Ñ €. errors="strict" permite detectar letras no representables en lugar de corromper silenciosamente el recibo. Para scripts y caracteres no soportados, algunas arquitecturas convierten la región a una imagen, siempre que el perfil de gráficos lo permita; esto aumenta el tamaño del payload y exige medir legibilidad.
También hay que tratar el ancho físico con cuidado: una letra acentuada no es necesariamente un byte en UTF-8, ni una celda monoespaciada equivale siempre a un ancho en milímetros. El formato depende de fuente, modo doble ancho, resolución y papel imprimible. Un layout robusto calcula medidas con los parámetros reales de la impresora.
QR: función definida, compatibilidad condicionada
Epson utiliza funciones de la familia GS ( k para configurar, almacenar y renderizar QR. Los identificadores exactos de funciones son importantes: seleccionar el modelo (165), tamaño (167), corrección de errores (169), almacenar bytes (180) e imprimir (181). No hay una única «secuencia universal de QR» que se pueda enviar sin consultar el modelo.
El siguiente encoder ilustra el formato para dispositivos Epson que hayan confirmado soporte de esas funciones. No controla USB/TCP ni verifica el resultado físico.
# Fragmento autocontenido para probar el formato de las funciones QR.
GS = b"\x1d"
def gs_k(body: bytes) -> bytes:
n = len(body)
if not 1 <= n <= 65535:
raise ValueError("Longitud GS ( k fuera del rango de 16 bits")
return GS + b"(k" + bytes([n & 0xFF, n >> 8]) + body
def encode_qr(data: bytes, *, module_size: int = 4) -> bytes:
if not data:
raise ValueError("El QR no puede estar vacío")
if len(data) + 3 > 65535:
raise ValueError("Contenido demasiado grande para este framing")
if not 1 <= module_size <= 16:
raise ValueError("Tamaño de módulo fuera del rango de este ejemplo")
return b"".join((
gs_k(b"\x31\x41\x32\x00"), # Función 165: modelo 2
gs_k(b"\x31\x43" + bytes([module_size])), # Función 167: tamaño
gs_k(b"\x31\x45\x31"), # Función 169: corrección M
gs_k(b"\x31\x50\x30" + data), # Función 180: datos
gs_k(b"\x31\x51\x30"), # Función 181: imprimir
))
Las validaciones de longitud, tamaño y modelo de QR deben ajustarse al rango del equipo; los valores mostrados no garantizan que todos los modelos admitan 16 como tamaño de módulo. En un driver real, supports_qr y los límites forman parte del perfil. El contenido binario debe definirse según el contrato del documento: un identificador, una URL o un QR fiscal pueden tener codificaciones y requisitos propios.
Antes de imprimir un QR en producción, una prueba de papel debería comprobar que un lector independiente recupera exactamente el payload, incluso tras redimensionar, imprimir en condiciones térmicas reales y acercarse a los límites de capacidad. Que el comando no produzca un error de escritura no demuestra que el símbolo sea legible.
Logotipos, imágenes y el problema de lo «obsoleto»
La impresión de gráficos admite diferentes familias de comandos: bitmaps raster, gráficos almacenados en memoria del dispositivo, variantes NV y comandos más recientes. En la lista de Epson, GS v 0 aparece marcado como obsolete. Esto no significa que ningún dispositivo actual lo acepte; significa que no debería presentarse como único método recomendado para desarrollos nuevos sin contrastar la matriz de comandos.
Una ruta de imagen debe definir, para cada modelo: ancho máximo en puntos, conversión a monocromo/halftone, dithering, límites del buffer, rotación, recorte y velocidad. Los logos guardados en memoria NV tienen requisitos de aprovisionamiento y actualización distintos de imágenes enviadas en cada ticket. Las capturas del navegador no son equivalentes a la salida binaria; hay que probar ambos artefactos por separado.
Diseñar el driver como render_logo(bitmap, capabilities) permite elegir la estrategia y registrar una degradación aceptable (por ejemplo, imprimir texto alternativo si faltan gráficos), sin acoplar la lógica del POS a un opcode particular.
Corte y estado: no confundir comandos con confirmaciones
GS V selecciona modos de corte en modelos con cutter y compatibilidad para el parámetro elegido. El comando no certifica por sí solo que el corte haya concluido. Similarmente, DLE EOT puede solicitar determinados estados en tiempo real, mientras que GS a habilita Automatic Status Back (ASB). La disponibilidad, semántica y recepción de esas señales dependen de modelo e interfaz.
El problema aparece cuando se mezclan canales unidireccionales con protocolos de estado bidireccionales. Una cola de impresión del sistema operativo puede aceptar el trabajo y no transmitir respuestas de la misma forma que una conexión TCP raw. En otros casos hay notificaciones ASB asíncronas que necesitan un parser separado del stream de trabajo. No se debe asumir que una llamada a status certifica la emisión completa de un recibo concreto. La guía Epson de comandos distingue explícitamente esas familias.
Una tabla de compatibilidad, fechada por firmware, debería identificar si el equipo ofrece:
| Capacidad | Decisión de driver | Prueba física |
|---|---|---|
ESC t | Página y número n configurados | Impresión y lectura de caracteres ES |
QR GS ( k | Funciones y límites permitidos | Escaneo de contenido exacto |
| Gráficos | Modo raster/NV/graphics seleccionado | Logo completo, márgenes y contraste |
GS V | Corte activado solo si está soportado | Corte real en modo elegido |
DLE EOT, ASB | Parser de estado por interfaz | Papel retirado/tapa abierta/reconexión según fabricante |
Los tests deben identificar modelo y firmware concretos, no solo «impresora ESC/POS de 80 mm».
El fallo más difícil: el resultado ambiguo de un envío
Pensemos en el siguiente recorrido: la aplicación acepta el pago, genera el recibo y comienza a escribir bytes por TCP. La conexión se corta después del envío. El cliente sabe que ocurrió un error de transporte, pero no sabe si la impresora recibió todo, una parte o si llegó a imprimir. Reintentar automáticamente puede producir un ticket duplicado; no reintentar puede dejar al operador sin papel.
No existe una transacción distribuida automática entre sale.commit() y el cabezal térmico. Por eso conviene modelar el trabajo como estado explícito:
| Estado | Qué se sabe | Siguiente acción |
|---|---|---|
QUEUED | Payload fijado, aún no enviado | Enviar una vez por política |
SENDING | Intento iniciado | Registrar intento y transporte |
ACK_TRANSPORT | El canal/spooler aceptó datos, no prueba impresión | Esperar evidencia adicional si existe |
CONFIRMED | Evidencia de confirmación definida por el perfil/operación | Cerrar job, conservar auditoría |
FAILED | Fallo confirmado antes de entrega | Reintentar con idempotencia controlada |
AMBIGUOUS | Puede haber existido entrega/impresión parcial | Reconciliar con operador o señal fiable; evitar duplicado silencioso |
Esta máquina de estados es una propuesta de diseño, no un feature nativo de ESC/POS. En la práctica, CONFIRMED debe definirse con precisión: puede indicar una observación operacional externa y no un acknowledgement transaccional de la impresora.
Un ledger útil guarda job_id, document_number, modelo, transporte, payload_sha256, timestamps, número de intentos, error de transporte y evidencia de resolución. No se debería incluir en los logs el contenido íntegro de tickets con datos personales. El número visible de documento ayuda a distinguir una reimpresión autorizada de un duplicado accidental.
Reintentos: idempotencia de API no implica exactly-once en papel
Una API puede rechazar dos envíos del mismo job_id; una cola puede deduplicar solicitudes; un worker puede usar un lock para evitar concurrencia. Son controles valiosos, pero no revierten la incertidumbre después de que una impresora recibió bytes sin una confirmación vinculada inequívocamente a ese trabajo. Si se decide reimprimir, la UI debería mostrar que se trata de una reimpresión y registrar quién la autorizó, de acuerdo con las reglas del negocio y fiscales aplicables.
La recuperación requiere tratar por separado estado de venta, generación de bytes, estado del trabajo y estado físico. Resolver el fallo imprimiendo de nuevo sin verificar los dos últimos puede multiplicar el problema.
Testabilidad: separar encoder y transporte
Un driver diseñado como función pura permite probar bytes sin hardware. Podemos comprobar la codificación, la cabecera QR y los límites de longitud antes de probar impresoras reales:
# Extracto de tests del encoder (suponiendo importados los helpers anteriores).
def test_cp858_espaniol():
profile = PrinterProfile("modelo-verificado", 16, "cp858", True, True)
payload = select_codepage_and_encode(profile, "Niño €")
assert payload[:3] == b"\x1b\x74\x10"
assert payload[3:] == "Niño €".encode("cp858")
def test_qr_framing():
payload = encode_qr(b"pedido-001", module_size=4)
assert payload.startswith(b"\x1d\x28\x6b\x04\x00\x31\x41\x32\x00")
assert b"\x31\x50\x30pedido-001" in payload
Atención: el valor 16 aparece aquí para verificar el framing del encoder, no para declarar que todas las impresoras identifican CP858 con ese número. El test de compatibilidad real necesita el perfil documentado y una impresión física.
El transporte se prueba con un fake que simula escritura parcial, timeout y reconexión. Esto solo valida nuestra política de software; el resultado físico sigue requiriendo hardware. No generamos aquí una secuencia de status fija para cualquier modelo porque su interpretación y mecanismo de recepción varían por interfaz.
Protocolo de aceptación para impresoras reales
Estado: propuesto, NO EJECUTADO en esta revisión. El entorno se especifica con fabricante/modelo/firmware, interfaz, versión del driver, ancho de papel, DPI y configuración de red. Una matriz mínima:
- Impresión de ASCII, tildes,
ñ,Ñ,€y caracteres no representables; registrar sustitución o error esperado. - Ticket de 58/80 mm con tablas, importes, fuentes y márgenes; medir desbordes visuales sin inferirlos solo del string.
- QR con distintos tamaños de módulo, un payload conocido y lectura de retorno.
- Logo por comandos gráficos soportados, dithering, alineación y persistencia de NV cuando exista.
- Corte: completo/parcial únicamente si el modelo lo permite, con comprobación de fin físico.
- Estado: papel vacío, tapa abierta, desconexión y reconexión; indicar qué se observa mediante el transporte real.
- Pérdida de conexión antes/durante/después del envío: registrar cuándo puede marcarse
FAILEDy cuándo debe quedarAMBIGUOUS. - Envíos largos, jobs consecutivos y reintentos autorizados; comprobar que el ledger corresponde a los documentos físicos.
Las pruebas de estado, hardware y desconexión quedan pendientes de impresora disponible. No se presentan resultados ni porcentajes inventados. Un encoder que supera tests unitarios todavía puede fallar ante buffer, firmware y mecanismos de spooler reales.
Integración con un POS, Odoo y Flutter
La aplicación puede estar escrita en Python, Dart, JavaScript o cualquier otro lenguaje. El diseño útil no consiste en abrir un socket dentro de la vista de facturación. Conviene crear un servicio de impresión que acepte un ticket tipado, produzca un payload inmutable y entregue el resultado a una cola con estados recuperables. El frontend necesita mostrar QUEUED, AMBIGUOUS y CONFIRMED según evidencia, sin identificar automáticamente «HTTP 200 del servicio» con «papel impreso».
En Odoo 18, el addon que define el flujo debería mantener las extensiones en su propio módulo, respetar ACL/record rules y no modificar vistas ni modelos core. Esa frontera de extensibilidad se desarrolla en Odoo 18: herencia y seguridad.
Para Flutter, si existe un SDK propietario de impresión, quizás convenga un plugin mediante Platform Channels o Pigeon; un encoder binario puro podría permanecer en Dart. El acceso nativo solo se justifica por API, fiabilidad o rendimiento medidos. En los dispositivos con spooler de sistema, la confirmación debe seguir distinguiendo lo que informa el SDK de lo que ocurre en el mecanismo físico.
Conclusión
El error más costoso en ESC/POS no es memorizar mal un opcode: es suponer que todos los modelos lo aceptan, que UTF-8 se activa con ESC t o que un write() completado certifica un ticket físico. Un driver fiable mantiene un perfil de capacidades por modelo, codifica de manera comprobable, separa transporte de resultado e incorpora un estado de envío ambiguo para recuperarse sin duplicados silenciosos.
Lo que debe probarse primero es el encoder; lo que debe comprobarse después, en hardware, es todo lo que el encoder no puede observar.
Referencias primarias
- Epson: ESC/POS Command Reference.
- Epson: comandos por modelo, ESC t, QR mediante GS ( k.
- Epson: listado de comandos y marcación de obsolescencia.