# Manual completo del modulo de impresion

Este manual explica la pestaña `Impresion` de Omega POS, la configuracion por
computadora y el uso de Omega Print Agent 1.3 en Windows y Linux.

## 1. Idea principal

Omega POS vive en la web, pero el navegador no puede enviar comandos RAW a una
impresora local de forma silenciosa. Omega Print Agent resuelve ese limite:

```text
Omega POS web -> http://127.0.0.1:17890 -> impresora de esta computadora
```

La venta se guarda primero. Despues, si corresponde, el POS envia el ticket al
agente local. Si el agente o la impresora fallan, la venta no se pierde.

### Configuracion del negocio

Estas preferencias siguen a la empresa:

- Cantidad de copias.
- Imprimir automaticamente al cerrar una venta.
- Mostrar logo.
- Usar QR, codigo de barras o solo texto para buscar la factura.

### Configuracion de esta computadora

Estos datos se guardan localmente en cada PC:

- Windows, Linux o deteccion automatica.
- Impresora de tickets y de etiquetas.
- Tipo de conexion y destino.
- Papel, perfil, margenes y calibracion.
- URL del agente local.

Por eso dos cajas del mismo negocio pueden usar impresoras diferentes sin
sobrescribirse.

## 2. Centro de impresion

En la pestaña `Impresion` aparecen estas descargas:

- `Omega-Print-Agent-Windows-1.3.0.zip`: solo herramientas Windows.
- `Omega-Print-Agent-Linux-1.3.0.zip`: solo herramientas Linux.
- `Omega-Print-Agent-1.3.0.zip`: paquete universal con ambos sistemas.
- `Descargar para esta caja`: elige el ZIP segun el sistema seleccionado.

Cada computadora que imprima necesita su propia copia del agente.

## 3. Paso 1: detectar computadora e impresoras

### Sistema de esta caja

- `Detectar automaticamente`: recomendado si aun no conoces el sistema.
- `Windows`: usa el spooler de Windows, impresoras instaladas, compartidas,
  puertos USB/LPT o COM.
- `Linux`: usa CUPS, red TCP, dispositivos `/dev/usb/lp*` o seriales
  `/dev/ttyUSB*`.

La seleccion se guarda solo en esa computadora.

### Detectar ahora

Busca el agente y consulta sus impresoras. Esta accion no imprime papel.

Los resultados muestran:

- `Sistema`: sistema real donde corre el agente.
- `Computadora`: nombre de la caja.
- `Agente`: version instalada.
- Mensaje con cantidad de impresoras y posibles problemas de CUPS.

Si el POS esta configurado para Linux pero detecta Windows, o al contrario,
mostrara `Revisar sistema`.

## 4. Paso 2: preferencias del negocio

### Copias por venta

Cantidad de tickets enviados al completar una venta. Usar `1` normalmente.

### Codigo para reportes

- `QR escaneable`: recomendado para camaras y lectores QR.
- `Codigo de barras`: recomendado para lectores lineales.
- `Solo numero de venta`: no imprime un codigo grafico.

El contenido corresponde al numero de venta, por ejemplo `VENTA-00014`.

### Imprimir al cerrar cada venta

Si esta marcado, una venta completada envia el ticket silenciosamente.
Si esta desmarcado, la venta se guarda sin imprimir automaticamente.

### Mostrar logo si existe

Incluye el logo configurado para la empresa. Si no existe logo, el ticket
continua normalmente.

## 5. Paso 3: impresora de tickets

Los tickets termicos usan comandos `ESC/POS`.

### Impresora detectada

Lista de impresoras devuelta por el agente. Selecciona una y pulsa
`Usar para tickets`; Omega completara nombre, conexion, destino y perfil
recomendado.

### Nombre en esta caja

Nombre descriptivo local. Ejemplos:

```text
Ticket caja principal
Ticket mostrador
Xlife P82 USB
```

### Conexion

- `Detectar automaticamente`: Omega interpreta el destino.
- `Instalada en esta computadora`: `printer:Nombre` en Windows o
  `cups:Nombre` en Linux.
- `Red / IP`: impresora accesible por IP, normalmente puerto `9100`.
- `Compartida en Windows`: recurso `share:Nombre` o ruta UNC.
- `USB serial / RS232`: puerto COM o `/dev/ttyUSB0`.
- `Destino avanzado`: dispositivo directo como `/dev/usb/lp0`.

### Destino

Ejemplos:

```text
192.168.1.120
tcp://192.168.1.120:9100
printer:Omega Ticket USB
share:Omega_Ticket_USB
\\localhost\Omega_Ticket_USB
cups:Omega_Ticket_USB
/dev/usb/lp0
COM3
COM3:9600
/dev/ttyUSB0
serial:///dev/ttyUSB0?baud=9600&parity=N&data=8&stop=1
```

### Puerto

Para red RAW se usa normalmente `9100`. Para `printer:`, `cups:`, recursos
compartidos o dispositivos `/dev`, este valor no controla la conexion.

### Papel y perfil

- `80 mm / 48 caracteres`: ancho completo de impresoras de 80 mm y punto de
  partida recomendado para Xlife P82.
- `80 mm compacto / 42 caracteres`: contenido mas estrecho.
- `58 mm / 32 caracteres`: impresoras pequenas de 58 mm.
- `Personalizado`: se activa al modificar la calibracion avanzada.

### Lenguaje

Los tickets deben usar `ESC/POS`. No seleccionar TSPL o ZPL para una impresora
de tickets.

### Modo

- `Silencioso por Omega Print Agent`: imprime directamente.
- `Desactivado en esta caja`: no envia tickets desde esta computadora.

## 6. Calibracion avanzada

Usar esta seccion solo despues de imprimir una prueba segura.

### Caracteres por linea

Controla el reparto del texto:

- 80 mm: empezar con `48`.
- 80 mm compacto: empezar con `42`.
- 58 mm: empezar con `32`.

### Margen izquierdo

Desplaza todo el ticket hacia la derecha en puntos. Empezar con `0`. Si el
contenido sale hacia la izquierda, subir poco a poco: `8`, `12`, `16`.

### Ancho imprimible

Ancho usado por texto, logo y codigos:

- 80 mm: empezar con `576`.
- 58 mm: usar el perfil de 58 mm antes de personalizar.

Reducirlo si el lado derecho se corta. No compensar un papel de 58 mm usando
un perfil de 80 mm.

### Ancho del logo

Tamaño horizontal del logo. Para 80 mm comenzar cerca de `280`. Reducir si el
logo se recorta; aumentar con moderacion si queda demasiado pequeno.

### Espacio antes del encabezado

Agrega papel antes del logo y evita que el cabezal o cortador anterior tape el
inicio. Empezar con `2`.

### Lineas antes del corte

Agrega espacio al final para que el codigo QR o de barras no quede dentro del
cortador. Empezar con `8` y subir si el final se recorta.

### Calibrar ancho

Imprime una tira corta con referencias. Gasta papel, aunque mucho menos que un
ticket completo.

### Imprimir ticket seguro

Envia una prueba ESC/POS corta usando exactamente la configuracion actual. No
abre el dialogo del navegador.

## 7. Paso 4: impresora de etiquetas

Esta seccion puede quedar desactivada si el negocio no usa etiquetas.

### Lenguaje

- `TSPL`: Xprinter, TSC y muchas etiquetadoras termicas compatibles.
- `ZPL`: Zebra y equipos compatibles con ZPL.

Enviar el lenguaje equivocado puede imprimir comandos como texto o no imprimir.

### Tamaños disponibles

- `50 x 30 mm`
- `60 x 40 mm`
- `80 x 50 mm`

El tamaño seleccionado debe coincidir con la etiqueta real.

### Modo

- `Desactivado en esta caja`
- `Directo TSPL`
- `Directo ZPL`

`Imprimir etiqueta segura` envia una sola etiqueta de prueba.

## 8. Diagnostico avanzado

La URL normal es:

```text
http://127.0.0.1:17890
```

No cambiarla salvo que el puerto haya sido personalizado.

Botones:

- `Diagnostico completo`: consulta agente, sistema, CUPS/spooler, impresoras,
  USB y seriales sin imprimir.
- `Probar ticket`: genera una prueba de ticket.
- `Probar etiqueta`: genera una prueba de etiqueta.
- `Guardar esta estacion`: guarda preferencias comerciales y configuracion
  fisica local.

Direcciones utiles:

```text
http://127.0.0.1:17890/health
http://127.0.0.1:17890/printers
http://127.0.0.1:17890/diagnostics
```

## 9. Instalacion en Windows

1. Instalar Node.js LTS.
2. Descomprimir `Omega-Print-Agent-Windows-1.3.0.zip`.
3. Ejecutar `Reiniciar-Omega-Print-Agent.bat`.
4. Ejecutar `Probar-Omega-Print-Agent.bat`.
5. Opcional: ejecutar `Instalar-Inicio-Con-Windows.bat`.
6. En Omega POS seleccionar `Windows` y pulsar `Detectar ahora`.

Para USB, usar primero una impresora instalada:

```text
printer:NOMBRE EXACTO EN WINDOWS
```

Si esta compartida:

```text
share:NOMBRE_COMPARTIDO
```

## 10. Instalacion en Linux

En Ubuntu, Debian, Linux Mint y derivados:

```sh
sudo apt update
sudo apt install nodejs cups cups-client curl
sudo systemctl enable --now cups
```

Descomprimir el paquete y ejecutar:

```sh
chmod +x *.sh
./Instalar-Inicio-Con-Linux.sh
./Probar-Omega-Print-Agent.sh
```

Comprobar:

```sh
lpstat -r
lpstat -p -d
systemctl --user status omega-print-agent.service
```

Si cambias grupos, debes cerrar sesion y volver a entrar:

```sh
sudo usermod -aG lp,lpadmin,dialout "$USER"
```

La administracion web de CUPS suele estar en:

```text
http://localhost:631
```

## 11. Rutas Linux para una termica USB

Probar en este orden:

### Ruta A: red IP

Es la opcion mas estable si la impresora tiene Ethernet:

```text
Conexion: Red / IP
Destino: IP_DE_LA_IMPRESORA
Puerto: 9100
```

No requiere driver de impresion para enviar ESC/POS RAW.

### Ruta B: cola CUPS

Instalar o agregar la impresora en CUPS. Confirmar:

```sh
lpstat -p -d
```

En Omega:

```text
Conexion: Instalada en esta computadora
Destino: cups:NOMBRE_DE_LA_COLA
```

La cola debe permitir datos RAW sin convertir ESC/POS en texto o graficos.

### Ruta C: USB directo

Comprobar:

```sh
lsusb
ls -l /dev/usb/lp*
```

Si existe `/dev/usb/lp0` y el usuario tiene permiso:

```text
Conexion: Destino avanzado
Destino: /dev/usb/lp0
```

Esta ruta evita el driver y CUPS, pero depende del dispositivo `usblp` y sus
permisos.

## 12. Perfil inicial para la impresora probada

Para la Xlife P82 / `Omega Ticket USB` que ya imprimio en Windows:

```text
Sistema: Linux
Lenguaje: ESC/POS
Modo: Silencioso por Omega Print Agent
Papel: 80 mm
Perfil: 80 mm / 48 caracteres
Caracteres por linea: 48
Margen izquierdo: 0
Ancho imprimible: 576
Ancho del logo: 280
Espacio antes del encabezado: 2
Lineas antes del corte: 8
```

Primero dejar que `Usar para tickets` complete el destino detectado. No escribir
manualmente `printer:Omega Ticket USB`, porque ese formato es exclusivo de
Windows; en Linux sera `cups:NOMBRE` o `/dev/usb/lp0`.

## 13. Protocolo seguro de prueba

Para no desperdiciar un rollo:

1. Mantener desmarcado `Imprimir al cerrar cada venta`.
2. Instalar y abrir el agente.
3. Pulsar `Detectar ahora`; no imprime.
4. Ejecutar `Diagnostico completo`; no imprime.
5. Seleccionar la impresora y guardar.
6. Pulsar una sola vez `Calibrar ancho`.
7. Si sale legible, pulsar una sola vez `Imprimir ticket seguro`.
8. Revisar margen, logo, codigo y corte.
9. Solo al final activar impresion automatica.

Si empieza a imprimir caracteres sin control:

```sh
cancel -a
systemctl --user stop omega-print-agent.service
```

Tambien puedes apagar la impresora, corregir lenguaje/destino y vaciar la cola
antes de encenderla nuevamente.

## 14. Problemas frecuentes

### El POS no encuentra el agente

- Abrir `http://127.0.0.1:17890/health`.
- Revisar que solo exista una instancia.
- Reiniciar el agente con el script del sistema.

### Linux detecta cero impresoras

- Ejecutar `lpstat -r` y `lpstat -p -d`.
- Confirmar que CUPS este activo.
- Agregar la impresora en `http://localhost:631`.
- Probar IP `9100` o `/dev/usb/lp0`.

### Permission denied en Linux

- Revisar permisos de `/dev/usb/lp0` o `/dev/ttyUSB0`.
- Agregar el usuario a `lp`, `lpadmin` o `dialout`.
- Cerrar sesion y volver a entrar.

### Imprime miles de caracteres

- Detener inmediatamente la cola.
- Confirmar que tickets usan ESC/POS.
- Confirmar que no se esta enviando HTML/PDF a una termica RAW.
- Si usa CUPS, revisar que la cola no transforme los bytes.
- No usar TSPL/ZPL en la impresora de tickets.

### Ticket desviado

- Confirmar papel y perfil correctos.
- Ajustar primero `Margen izquierdo`.
- Ajustar despues `Ancho imprimible`.
- Hacer cambios pequeños y una prueba por vez.

### Codigo final recortado

- Aumentar `Lineas antes del corte`.

### Logo recortado

- Aumentar `Espacio antes del encabezado`.
- Reducir `Ancho del logo` si supera el area imprimible.

## 15. Compatibilidad realista

La impresora que funciono en Windows probablemente funcionara en Linux porque
Omega conserva el mismo ticket ESC/POS. Lo que debe resolverse en Linux es el
transporte hasta el USB o la red.

No se puede garantizar una impresora fisica sin probarla. Los posibles bloqueos
son:

- Linux no detecta el USB.
- CUPS no tiene una cola adecuada.
- Faltan permisos.
- El driver transforma los comandos RAW.
- El modelo no implementa completamente ESC/POS.

La prueba en Windows ya confirma el punto mas importante: la impresora entiende
los comandos generados por Omega. Eso reduce bastante el riesgo de la migracion
a Linux.