Saltar al contenido
P4 Software P4 Software / BarcoderX Español

Agrega esta documentación a Claude

Hazle preguntas a Claude sobre esta documentación. Claude lee las páginas publicadas y te enlaza a ellas. Copia esta dirección:

https://p4-software.opendocs.page/mcp

En claude.ai o Claude Desktop: abre Configuración, luego Conectores, elige Agregar conector personalizado y pega la dirección.

En Claude Code, ejecuta:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

Salida ZPL

Salida ZPL

Aplica a: BarcoderX Basic y Ultimate

Estado: Construido, aún sin publicar. El escritor que convierte una imagen en blanco y negro de una etiqueta en comandos ZPL existe y está probado, y ahora está unido al motor de etiquetas: una plantilla se convierte en los comandos de una etiqueta, y el servicio web sin estado tiene una dirección que los devuelve. Todavía no se ha publicado nada y no hay nada que descargar. No hay ningún paquete publicado. La única vía pública para producir comandos toma una etiqueta creada por el motor con licencia, y nada más. Ninguna codificación de los comandos se ha probado todavía en una impresora física, ni la simple ni la comprimida; el registro del laboratorio está pendiente. Todo lo que está marcado como "planificado" todavía no se puede usar.

ZPL es un lenguaje de impresora. Consulte Lenguajes de impresora para ver los lenguajes que BarcoderX planea escribir y para qué sirve cada uno. ZPL es un nombre que pertenece a su propietario, y BarcoderX lo usa solo para indicar qué lenguaje escribe. Esta página describe el primer escritor de ZPL, el que envía una etiqueta completa a la impresora como una imagen, y cómo le llega una plantilla.

Qué hace

El escritor toma la imagen en blanco y negro de una etiqueta, a la resolución de la impresora, y escribe los comandos ZPL que hacen que la impresora imprima exactamente esa imagen. No envía texto propio ni comandos propios de códigos de barras. Todo lo que hay en la etiqueta, texto y códigos de barras incluidos, forma parte de la imagen, de modo que la impresora imprime exactamente la imagen que recibe el escritor. La marca de evaluación, si la etiqueta la lleva, ya está en la imagen, porque el motor la dibuja junto con el resto de la etiqueta, y el escritor no le agrega nada.

La imagen llega al escritor solo a través del motor. El texto residente en la impresora, los comandos propios de códigos de barras de la impresora, la configuración de la impresora y la impresión de varias etiquetas en un trabajo están planificados. Consulte Lenguajes de impresora.

Qué se escribe

Para una etiqueta, el escritor escribe estos comandos, en este orden:

ComandoQué haceCuándo se escribe
^XAInicia el formato de la etiqueta.Siempre, primero.
^PWFija el ancho de impresión, en puntos.Solo cuando usted indica un ancho de impresión. Los comandos creados a partir de una plantilla siempre lo indican: el ancho de la etiqueta.
^LLFija el largo de la etiqueta, en puntos.Solo cuando usted indica un largo de etiqueta. Los comandos creados a partir de una plantilla siempre lo indican: el alto de la etiqueta.
^LHFija el origen de la etiqueta, la posición de su esquina superior izquierda, en puntos.Siempre, porque la impresora conserva el último origen que recibió hasta que se apaga.
^FO y ^GFAColocan una banda de la imagen y dan sus puntos.Un par por cada banda, de arriba hacia abajo.
^FSTermina el campo de una banda.Después de cada banda.
^PQFija el número de copias.Siempre, justo antes del final.
^XZTermina el formato de la etiqueta, y la etiqueta se imprime.Siempre, al final.

La etiqueta más pequeña que escriben las pruebas, una imagen de 8 puntos de ancho y 1 punto de alto cuyos puntos son los dígitos hexadecimales A5, da estos comandos:

^XA
^LH0,0
^FO0,0^GFA,1,1,1,A5^FS
^PQ1
^XZ

Los números de ^GFA,1,1,1,A5 son el número de bytes de la banda, el mismo número otra vez, el número de bytes de una fila, y después los datos.

La imagen

  • Codificación simple. Cada byte de la imagen se escribe como dos dígitos hexadecimales. El punto de la izquierda de una fila es el bit más alto de su primer byte, y un punto activado es negro. Una fila se rellena hasta un byte completo, y el relleno siempre se escribe como blanco, sea lo que sea que la imagen tenga en su relleno.
  • Codificación comprimida. El atajo de la guía de programación de ZPL que repite un dígito, rellena el resto de una fila con ceros o con unos, o repite la fila anterior. Nunca es más larga que la codificación simple. Una letra de la G a la Y repite el dígito que sigue de 1 a 19 veces, una letra de la g a la z lo repite de 20 a 400 veces, una coma rellena el resto de la fila con ceros, un signo de exclamación la rellena con unos y los dos puntos repiten la fila anterior. La codificación comprimida está desactivada de forma predeterminada, y no se ha verificado en una impresora física. La guía describe el atajo para los comandos que descargan gráficos, y dice que el campo gráfico sigue el mismo formato. Un perfil de impresora debería activarla solo para una impresora de la que se sepa que la acepta. Hay dos puntos abiertos: el signo de exclamación se usa para los bytes finales que son todos unos, que es la lectura de este proyecto de la guía, y las letras del 60 y del 120 se leen por su lugar en el alfabeto.
  • Bandas. Un campo gráfico contiene como máximo 99,999 bytes, de modo que una imagen alta se escribe como varias bandas, una debajo de otra. Por ejemplo, una imagen de 812 puntos de ancho y 1,218 puntos de alto se escribe como dos bandas, la primera con las filas de la 0 a la 979 y la segunda con las filas de la 980 a la 1,217. Las bandas juntas contienen cada fila exactamente una vez.

Para el tablero de 80 por 8 puntos de la guía de programación, las ocho filas son, en la codificación simple y en la comprimida:

FilaCodificación simpleCodificación comprimida
1FFFFFFFFFFFFFFFFFFFF!
28000FFFF0000FFFF00018I0JFJ0JFI01
3 y 4Igual que la fila anterior: cada una
5FFFF0000FFFF0000FFFFJFJ0JFJ0!
6 y 7Igual que la fila anterior: cada una
8FFFFFFFFFFFFFFFFFFFF!

Los comandos y sus rangos siguen la guía de programación de ZPL II (número de parte P1134473-11EN, revisión A).

Qué recibe

EntradaQué es
La imagenLa etiqueta como una imagen en blanco y negro, con un bit por cada punto de impresora.
La resoluciónLa resolución de la impresora, en puntos por pulgada, de 96 a 1,200. ZPL en sí no lleva resolución, de modo que el escritor solo comprueba que esté dentro de este rango.
El ancho de impresiónOpcional. Desde 2 puntos. Si no indica ninguno, la impresora conserva su propio ancho.
El largo de la etiquetaOpcional. Desde 1 punto. Si no indica ninguno, la impresora conserva su propio largo. La guía dice que el largo se aplica de forma predeterminada a los medios que no están divididos en etiquetas separadas, de modo que en otros medios la impresora puede conservar su propio largo.
El origen de la etiquetaLa posición horizontal y la vertical de la etiqueta, en puntos. El valor predeterminado es 0 y 0.
El número de copiasDe 1 a 99,999,999. El valor predeterminado es 1.
La codificación de la imagenSimple o comprimida. El valor predeterminado es simple.
El límite de la salidaLa mayor cantidad de bytes que puede ocupar una etiqueta.

Un valor que está fuera de su rango se rechaza con un mensaje y nunca se ajusta. El límite de la salida es la única excepción: un valor menor que 1 cuenta como 1, y un valor mayor que 64 MiB cuenta como 64 MiB.

Límites

BarcoderX comprueba cada límite antes de escribir nada. Una etiqueta que rompe un límite recibe un mensaje y ningún comando. El límite del tamaño de la salida protege al programa que aloja el escritor.

LímiteValor
Tamaño de la imagenDe 1 a 32,000 puntos por lado (elección del constructor, pendiente de la confirmación del propietario)
Ancho de impresión, largo de la etiqueta y origenLos rangos de la guía de programación: 2 o más para el ancho, de 1 a 32,000 para el largo, de 0 a 32,000 para el origen. El límite superior del ancho, 32,000, es una elección del constructor, pendiente de la confirmación del propietario.
Número de copiasDe 1 a 99,999,999
Bytes de los comandos de una etiqueta16 MiB de forma predeterminada, y no más de 64 MiB (elección del constructor, pendiente de la confirmación del propietario)
Bytes de una banda99,999 como máximo

El tamaño de la salida se calcula a partir de la codificación simple y se comprueba antes de escribir nada. La codificación comprimida nunca es mayor. Los 16 MiB predeterminados contienen la codificación simple de una imagen de 64 megapíxeles. El límite es por etiqueta, de modo que un programa que escribe muchas etiquetas en un trabajo debería dar a cada etiqueta el presupuesto que queda del trabajo.

Algunas cifras, medidas en una revisión de seguridad en un equipo de desarrollo. Una etiqueta de 4 por 6 pulgadas a 300 puntos por pulgada (1,200 por 1,800 puntos) ocupa unos 540,000 bytes de comandos, y una a 600 puntos por pulgada (2,400 por 3,600 puntos) unos 2,160,000 bytes, sea lo que sea que lleve en la codificación simple: cada byte de la imagen se convierte en dos caracteres. La codificación comprimida nunca es mayor. Escribir una etiqueta así tardó menos de 3 milisegundos en la codificación simple, y menos de 50 milisegundos en la comprimida con el peor contenido. Para la imagen más grande que admiten los límites, escribir tardó unos 0.1 segundos en la codificación simple y hasta unos 1.5 segundos en la comprimida con contenido con mucho ruido.

Si usted aloja el escritor

  • Descarte los comandos de una etiqueta que se rechazó o se canceló. Si la salida no acepta los comandos a la mitad de una etiqueta (BX5113), o se cancela el trabajo, lo que se escribió puede contener un formato que se inició y no se cerró (^XA sin ^XZ). Una impresora lo toma como el inicio de la siguiente etiqueta. Escriba cada etiqueta en un búfer propio, o vuelva al tamaño que tenía el búfer antes de la llamada, y nunca envíe los bytes de una etiqueta que no terminó.
  • Cuente usted las copias. El escritor acepta hasta 99,999,999 copias para una etiqueta. Compare las copias con los límites del trabajo antes de pasarlas.
  • Permita cancelar una escritura larga. El escritor comprueba un token de cancelación antes de escribir el primer byte y una vez por cada fila.
  • Pase un presupuesto para el trabajo. Cada etiqueta tiene su propio límite de salida, de modo que dé a cada etiqueta lo que queda del presupuesto del trabajo.

De una plantilla a los comandos

El motor de etiquetas entrega la etiqueta que creó al compositor de ZPL, y el compositor devuelve los comandos de esa etiqueta. El motor distribuye la etiqueta en puntos a la resolución que usted pida. El compositor la dibuja en una superficie en blanco y negro, de la misma manera que se dibuja la imagen PNG en blanco y negro, y el escritor de arriba escribe esa superficie como comandos. Por eso los puntos que recibe la impresora son los de la imagen en blanco y negro, uno por uno. Una prueba lee ambas con código escrito para ella y las compara punto por punto, para varias etiquetas y resoluciones.

Los comandos de una etiqueta, en orden: ^XA; ^PW con el ancho de la etiqueta en puntos (se omite para una etiqueta de un punto de ancho, porque el comando acepta 2 o más); ^LL con el alto de la etiqueta en puntos; ^LH0,0; un par ^FO y ^GFA por cada banda; ^PQ1; ^XZ. Se usa la codificación simple, nunca la comprimida. El comienzo de los comandos de la etiqueta de ejemplo (100 por 50 mm a 203 puntos por pulgada, 799 por 400 puntos):

^XA
^PW799
^LL400
^LH0,0
^FO0,0^GFA,...

Un aviso por etiqueta. El compositor envía toda la etiqueta como una sola imagen, por lo que informa un solo aviso para la etiqueta, BX5130, y no uno por cada texto, código de barras o cuadro. En esta versión no se usan las fuentes ni los comandos de código de barras propios de la impresora. Los comandos para ellos están planificados, y se usarán solo donde se demuestre que son iguales a la imagen.

Límites. El anfitrión que ejecuta el compositor fija dos límites: la mayor cantidad de puntos de una etiqueta y la mayor cantidad de bytes de los comandos (16 MiB de forma predeterminada, y no más de 64 MiB). Ambos se comprueban antes de dibujar o reservar nada, y una etiqueta que supera un límite recibe un mensaje y ningún comando. Una etiqueta cuyo dibujo no puede terminar recibe el código de la biblioteca de dibujo y ningún comando, porque un código de barras dibujado a medias nunca debe llegar a una impresora.

La dirección de comandos del servicio

El servicio web sin estado tiene una dirección para los comandos de una etiqueta. Es el mismo manejador que la dirección de la imagen (POST /api/v1/render/png), de modo que se aplican los mismos controles: la clave, el tamaño del cuerpo, los límites de frecuencia, los lugares para dibujar etiquetas (compartidos por ambas direcciones), el límite de tiempo y el plazo de escritura. Sus valores y los ajustes que los cambian están en El servicio de etiquetas.

ParteQué es
DirecciónPOST /api/v1/commands?dialect=zpl
CuerpoLa plantilla como JSON, hasta 262,144 bytes, con el tipo de contenido application/json.
dialectObligatorio. zpl es el único valor, en minúsculas.
dpiOpcional. La resolución en puntos por pulgada, dentro del rango del servicio (de 96 a 600 de forma predeterminada). Sin ella se usa la resolución escrita en la plantilla. ZPL en sí no lleva resolución, así que use la resolución de su impresora.
RespuestaEstado 200 con el tipo de contenido text/plain; charset=utf-8: los comandos, como texto ASCII simple. El encabezado BarcoderX-Warnings enumera los códigos de los avisos sobre la etiqueta, y BX5130 siempre está.
Un problemaUn documento de problema en inglés o en español, como en la dirección de la imagen. Los comandos de una etiqueta que se detuvo nunca se devuelven en parte.
Límitelimits.maxCommandsBytes en settings.json: 16,777,216 bytes de forma predeterminada, de 1,024 hasta 67,108,864. GET /api/v1/meta/limits lo muestra como maxCommandsBytes. La mayor cantidad de puntos de una etiqueta es el límite de la imagen en blanco y negro.

Una llamada con curl, desde una carpeta que contenga label.json:

curl -X POST "http://127.0.0.1:5187/api/v1/commands?dialect=zpl&dpi=203" -H "Content-Type: application/json" --data-binary @label.json -o label.zpl

El cliente de .NET con tipos que está construido para la ruta de la imagen también pide los comandos. Recibe el texto de la plantilla y las opciones (el lenguaje de impresora, la resolución y el idioma de los mensajes), y devuelve los comandos y los códigos de las advertencias, o el documento de problema y el número de segundos que hay que esperar. Solo lanza una excepción por una falla de red o una solicitud cancelada, nunca por un problema que informa el servicio. Consulte El servicio de etiquetas.

La marca de evaluación en los comandos

El motor de etiquetas dibuja la marca de evaluación junto con el resto de la etiqueta, de modo que la marca forma parte de los puntos que llevan los comandos. Es la misma marca que en la imagen PNG, punto por punto: una prueba compara los puntos de los comandos con los puntos de la imagen en blanco y negro de una etiqueta marcada. Cuando ninguna licencia válida cubre la etiqueta, o cuando falla la propia comprobación de la licencia, la etiqueta se imprime igual y sus comandos llevan la marca. Una ejecución con licencia produce comandos sin marca, que es el producto. Consulte Marca de evaluación y claves de licencia.

  • Nada de la licencia está en los comandos. Ni el identificador de la licencia ni el nombre del titular se escriben en un flujo de comandos de impresora, y no se usa ningún comentario ni campo para ello.
  • Un flujo ZPL es texto simple, de modo que la marca en él disuade, pero no es una cerradura.
  • Cómo saberlo. El resultado del compositor tiene un indicador Marked, y el servicio web enumera el aviso BX9001 ("No hay ninguna licencia registrada") en el encabezado BarcoderX-Warnings de una respuesta que está marcada porque no hay ninguna licencia registrada (cuando falla la propia comprobación de la licencia, el aviso es BX9030 y los comandos se marcan igualmente). El campo de pruebas gratuito siempre devuelve comandos marcados.

Lo que todavía no está construido

  • ZPL desde una plantilla guardada o con datos. La dirección de comandos recibe una plantilla completa en la solicitud. Las plantillas guardadas y los datos llegan con el servidor.
  • Los comandos propios de texto y de códigos de barras de la impresora. BarcoderX planea usarlos donde se demuestre que son iguales a la imagen. Consulte Lenguajes de impresora.
  • Los comandos de configuración, como el seguimiento del medio, el modo de impresión, la velocidad, la intensidad y la orientación. Hoy solo se escriben el ancho, el largo, el origen y el número de copias.
  • Los comandos RFID, la serialización y las fuentes TrueType en la impresora.
  • Verificar los comandos en una impresora física, la codificación simple y la comprimida. La dirección de comandos no ofrece la codificación comprimida.

Los códigos de diagnóstico del escritor y del compositor son BX5101 a BX5113, BX5120, BX5121 y BX5130 a BX5133. Consulte Códigos de diagnóstico.


BarcoderX es un producto de P4 Software.

¿Te resultó útil esta página?