Programando un plugin para trabajar con una impresora térmica

He programado un plugin en C# 10 para una impresora térmica ESC/POS de 58mm.

Lo podrás ejecutar en Windows, Linux y MacOS.

Lo tengo empezado para Android y iOS, pero aún no lo he terminado.

El motivo por el cuál he desarrollado mi propio plugin, es porque los plugins que he usado hasta ahora no me han convencido al 100%. Cada uno por distintos motivos así que me decidí a hacer yo mismo uno que cubra con todo lo que necesito.

Empecemos por el principio.

¿Qué es una impresora ESC/POS?

Una impresora ESC/POS (Point of Sale) ESC es un tipo de impresora térmica utilizada en puntos de venta, restaurantes, supermercados, etc...

Estoy seguro que has tenido en tus manos algún ticket impreso por una de estas impresoras, ya que normalmente se utilizan en hostelería para imprimir el ticket de la cuenta o para imprimir las comandas a la cocina.

La abreviatura "ESC" se refiere al conjunto de comandos de escape utilizados por dichas impresoras.

Los comandos de escape son secuencias de caracteres que se envían a la impresora para controlar su comportamiento como cambiar el tamaño y el estilo de la fuente, alinear el texto, cortar el papel, etc...

En el siguiente enlace te dejo un pdf con dichos comandos.

Si no te quieres descargar el pdf, te dejo una imagen de algunos de los comandos.

Si aún no te ha quedado claro qué es una impresora ESC/POS te dejo un imagen de la mía.

¿Qué hace el plugin que he programado para impresora ESC/POS?

Básicamente, lo que hace es abrir una comunicación HTTP de forma que la máquina donde se está ejecutando el plugin acepte peticiones y se las pase a la impresora.

Actualmente, el plugin se ejecuta como una aplicación de consola.

Hasta ahora tengo programado en la raíz de la aplicación las respuestas a solicitudes GET y POST y hardcodeado el puerto de escucha 7878.

Más adelante programaré el plugin configurable para que el usuario pueda definir el puerto, pero eso ya será la segunda derivada.

Listando las impresoras (petición GET)

Estando ejecutándose el plugin, si le haces una petición al puerto 7878 te devolvéra el listado de impresoras configuradas en Windows.

Te dejo un screenshot de la petición desde Postman 👇

Enviando orden a imprimir (petición POST)

Si le haces una petición POST incluyendo en el cuerpo de la petición un JSON apropiado, el plugin le enviará la orden a la impresora térmica.

El JSON debe ser un array de objetos que te dejo a continuación para TypeScript

export interface MessageThermalPrinterInterface
{
    message:string
    justification?:JustificationEnum
    heightFont?:HeightFontEnum
    widthFont?:WidthFontEnum
    isQR?:Boolean
    printerName?:string
}

export enum JustificationEnum
{
    Left=0,
    Center=1
}

export enum HeightFontEnum
{
    Normal = 0,
}

export enum WidthFontEnum
{
    Normal = 0,
}
      

🚩 En el plugin no proceso la longitud de las palabras para evitar que la impresora las corte.

Lo que he hecho es considerarlo en la aplicación, que es quien le enviará la petición al plugin.

De esta forma el plugin es genérico para todas las impresoras y será en la aplicación que envía la petición al plugin donde se configurará las características de la impresora como:

• Número de caracteres por línea
• Nombre de la impresora
• Tipo de caracteres

Futuras modificaciones

A medida que lo vaya necesitando haré las siguiente modificaciones:

• Hacer que el plugin sea un servicio en lugar de una aplicación de consola y arranque con el Sistema Operativo.
• Haré configurable el puerto al que se exponer el servidor HTTP.
• Programar los caracteres acentuados. Ahora mismo lo que hago es normalizar los textos a ASCII antes de enviárselos a la impresora.
• Compilar para Linux y MAC.

¿Cómo hacer que funcione el plugin?

Instalar impresora ESC/POS

Utiliza los drivers facilitados por el fabricante de tu impresora para instalarla.

Una vez instalada comprueba que funciona correctamente imprimiendo un página de prueba.

Si la página se imprime correctamente puedas pasar al siguiente paso que es compartir la impresora en red.

Compartir impresora

Ve a las propiedades de tu impresora térmica y la compartes.

Descargar e instalar el plugin

Puedes descargarte el plugin de aquí.

Te descargarás un fichero comprimido, descomprímelo y ejecuta el programa ThermalPrinterPlugin.exe.

Añádelo a la lista de programas que se inician cuando arrancas Windows. Si te pide algún permiso dáselo, te aseguro que el fichero está libre de virus 🤞

Listando las impresoras para comprobar que el plugin funciona

Para probar que el plugin funciona correctamente puedes utilizar mi aplicación web 🚀 desarrollada con Angular o realizar una petición GET a http://localhost:7878 con cualquier cliente HTTP.

Te dejo una imagen de la petición GET con Postman.

¿Aplicación en Angular 16 para probar tu impresora?

Accede a la aplicación en línea

Para acceder a la aplicación en línea pulsa aquí.

Verás una pantalla como sigue:

Elige una impresora y pulsa en el botón de imprimir página de prueba.

Si toda ha ido bien deberás ver lo siguiente:

Y en tu impresora deberá salir lo siguiente:

Descárgate el código fuente

Te puedes descargar el código fuente de la aplicación aquí.

Funciones para una correcta impresión

Si envias un mensaje directamente a la impresora, te darás cuenta que obtendrás lo que espera.

Verás caracteres chinos y que las palabras se cortan.

El motivo es que tienes que pasarle el mensaje a la impresora térmica procesado para que se vea como quieres.

En el manual de instrucciones de mi impresora viene especificado como parámetro el número máximo de letras por línea y el las fuentes aceptadas.

Evitando que se corten palabras

Sabiendo que el número máximo de caracteres por línea de mi impresora son 32, haré una función que cuente los caracteres de las palabras y cuando llegue a 32 meteré un retorno de carro.

Te dejo el código en TypeScript.

const words = message.split(' ');
let currentLine = '';
let lines = '';

words.forEach((word) => {
  if (currentLine.length + word.length + 1 > MAX_CHARACTERS_BY_LINE) {
    lines += `${currentLine}\n`;
    currentLine = word + ' ';
  } else {
    currentLine += word + ' ';
  }
});
lines += `${currentLine}\n`;
return lines;
      

Normalizando mensajes para evitar los caracteres no aceptados por la impresora

Mi impresora acepta caracteres de la GB 18030, así que voy a normalizar el mensaje a la impresora para que no aparezcan caracteres chinos cuando se encuentre con un caracter que no conoce.

Te dejo el código en C#.

string normalized = input.Normalize(NormalizationForm.FormD); // Normalizar el string
StringBuilder stringBuilder = new();

foreach (char c in normalized)
{
    if (CharUnicodeInfo.GetUnicodeCategory(c) != UnicodeCategory.NonSpacingMark)
        stringBuilder.Append(c);
}

return stringBuilder.ToString();
      

Recursos de mi impresora

Te dejo enlaces de interés de mi impresora:

• Manual de instrucciones.
• Mi impresora en la web del fabricante.
• Drivers de mi impresora en la web del fabricante.
• Descarga desde mi repositorio toda la info de la impresora.

Configurando una Hoin POS-58-Series por Bluetooth

Me ha costado más de lo esperado conseguir que mi POS-58-Series funcione por Bluetooth.

El detalle clave para conseguir la conexión satisfactoria por Bluetooth es cuando consigues el emparejamiento de la impresora por Bluetooth mirar el puerto utilizado y cambiarlo en la configuración de la impresora térmica.

Como si fueran dos dispositivos distintos, uno la impresora térmica y otro el módulo Bluetooth.

Te dejo los pasos para que lo consigas:

1. Teniendo la impresora encendida, conectada y funcionando con el cable USB continua con los siguiente pasos.

2. Busca en tu Windows Configuración de Bluetooth y otros dispositivos

   

3. Pulsas en agregar nuevo dispositivo

   

4. Eliges el dispositivo BlueTooth Printer.

   Introduces el PIN de conexión y le das a conectar

   

5. Si no sabes el PIN de conexión de tu impresora, debe de aparecer cuando imprimees una página de prueba, te dejo la mía como ejemplo.

   

6. Si todo ha ido bien y el PIN es correcto el dispositivo se emparejará.

   

7. A continuación tenemos que ver qué puerto es por el que se ha conectado Windows a nuestra impresora Bluetooth.

   Para ello:

   1. Ve a dispositivos e impresoras del panel de control
   2. Selecciona tu impresora Bluetooth, en mi caso BlueTooth Printer
   3. Ve a propiedades y selecciona la pestaña de Hardware
   4. En las funciones del dispositivo selecciona el tipo de puerto
   5. Y verás en el título de la nueva ventana el puerto que usa para conectarse, en mi caso el COM12
   

8. Por último lo que tenemos que decirle a Windows es que use ese puerto para imprimir cuando seleccionemos la impresora térmica, en mi caso la POS-58-Series.

   Para ello:

   1. Abrimos las propiedades de la impresora térmica
   2. En la pestaña de puerto seleccionamos el puerto que se le asignó a la impresora Bluetooth, en mi caso el COM12
   

Si todo ha ido bien, si quitas el cable USB y seleccionas imprimir por la impresora térmica, en mi caso la POS-58-Series, se hará la impresión correctamente y lo habrás hecho por Bluetooth 🔥

Perdí bastante tiempo empeñado en imprimir por la impresora Bluetooth, así que ya sabes, lo que se hace es usar el puerto de la conexión de la impresora Bluetooth para imprimir por la impresora térmica.

Hasta aquí el artículo de esta semana.

Ha sido largo 😅

Hasta luego 🖖