Capitolo 3 — Applicazione Bridge (ponte di collegamento hardware)

La Cassa viene eseguita nel browser e il browser non può comunicare direttamente con il terminale di pagamento, la stampante, la bilancia e il display cliente. L'applicazione Bridge è questo ponte: viene eseguita accanto alla Cassa e collega questi dispositivi alla Cassa.

È disponibile in tre forme che svolgono tutte la stessa funzione (la versione iOS è sperimentale):

• App Android su tablet
• Applicazione desktop su computer (Windows/Mac/Linux)
• App iOS (sperimentale)

⚠️ Lingua: l'interfaccia dell'app Android è di fatto in inglese. Solo alcune vecchie stringhe sono state tradotte in tedesco; l'intera dashboard che l'operatore vede (stati, Power Guard, Keep Bridge Awake, log ecc.) è in inglese.

💡 Di solito si configura Bridge una volta e poi funziona in background. L'indirizzo di Bridge si inserisce in Cassa ← Impostazioni ← Bridge (guida della Cassa, capitolo 9). L'app Android viene eseguita come servizio di primo piano persistente: rimane attiva anche chiudendo l'applicazione dall'elenco, si riavvia automaticamente dopo un aggiornamento e un monitor ripristina il server ogni 30 secondi, se necessario.

3-1. App Android — schermata di stato

Una schermata a tutto schermo (chiosco) con una riga di riepilogo in alto e alcune schede di stato. All'avvio si vede il messaggio «Preparazione del ponte, collegamento del terminale di pagamento e del display cliente».

• Riepilogo generale in alto nella pagina, ad esempio: «Ponte pronto per il pagamento», «Terminale pronto, in attesa del browser», «Browser collegato / terminale offline», «Ripristino del collegamento del terminale in corso» oppure «Transazione in corso».
• Schede di stato (ciascuna con un punto colorato e una parola di stato):
• WebSocket — la porta locale a cui si collega la Cassa.
• Browser (Browser) — se la Cassa è collegata.
• Terminale di pagamento (POS Terminal) — stati: disconnesso / in connessione / in riconnessione / connesso / occupato (Busy) durante la transazione.
• Display cliente — stato del secondo display.
• Power Guard — protezione di batteria/processore/Wi-Fi per evitare interruzioni durante l'inattività.

Scheda dell'indirizzo di Bridge

• Mostra l'indirizzo (locale 127.0.0.1:PORT o indirizzo di rete con l'IP del dispositivo) che deve essere inserito nella Cassa.
• Il pulsante della modalità di connessione ha tre stati e a ogni pressione cambia ciclicamente: locale ← rete ← automatico (Auto). La modalità automatica passa alla rete se è disponibile un indirizzo di rete locale, altrimenti passa a locale.
• Tenendo premuto il pulsante della modalità di connessione: creazione o cancellazione del token di associazione — un codice di 6 caratteri che viene aggiunto all'indirizzo (?token=XXXXXX) affinché solo la Cassa autorizzata possa collegarsi. Questo token si applica solo nella modalità di rete (nella modalità locale viene ignorato) e nell'indirizzo viene indicato come «Paired/Open».

Altre schede e accesso ai log

• Power Guard → «mantenere attivo il ponte» (Keep Bridge Awake): apre le impostazioni della batteria di Android affinché Bridge non si interrompa durante l'inattività.
• Log: si attivano/disattivano con il pulsante Enable/Disable Logs e View Logs apre la pagina dei log; la disattivazione cancella i log salvati. Il secondo modo per aprire i log è tenere premuto (long-press) sulla barra superiore della pagina.
• Pagina dei log: è in sola lettura — testo a spaziatura fissa che si aggiorna ogni secondo e scorre verso il basso; non dispone di un pulsante di condivisione/esportazione (per inviarli all'assistenza è necessario copiarli manualmente).
• Pagina del display cliente: sul secondo display, mostra al cliente gli articoli e il totale dell'ordine tramite un modello web. Su Android si aggancia automaticamente a qualsiasi secondo display collegato (senza selezione manuale; viene rimosso scollegando il cavo).

3-2. Applicazione desktop — «LonioBridge — Host»

Una piccola finestra di controllo per eseguire Bridge sul computer:

• Modulo di configurazione:
• Porta WebSocket (predefinita 8088)
• Indirizzo di binding (Bind): solo questo computer o l'intera rete (predefinito 0.0.0.0).
• Display cliente: selezione manuale del monitor da usare come display cliente (o nessuno).
• Avvio/arresto per eseguire il ponte; le impostazioni vengono conservate tra un'esecuzione e l'altra nel file ~/.loniobridge/host.properties.
• Avvio automatico (Autostart): con il parametro --autostart (su Windows il programma di installazione lo configura con script di attivazione/disattivazione affinché si avvii all'accensione del sistema).
• Modalità senza finestra (Console): con --console è possibile eseguirlo senza interfaccia grafica.
• Pannello di stato: stato del server (arrestato / in avvio / in ascolto sulla porta / porta non valida / errore), numero di casse collegate, stato del terminale di pagamento e indicatore occupato/inattivo (durante la transazione).
• Report attività: log temporizzato degli eventi; opzione Verbose per registrare i frame grezzi del terminale di pagamento (solo per la risoluzione dei problemi).

⚠️ Nella finestra desktop non è presente la selezione della stampante o della bilancia; solo la porta, l'indirizzo di binding e il display cliente. La stampante e la bilancia vengono configurate dal lato Cassa e Bridge le avvia in base ai messaggi della Cassa.

3-3. Quali dispositivi vengono collegati

• Terminale di pagamento: sono disponibili due driver, selezionabili nel profilo del terminale:
• ZVT (predefinito) — tramite rete/TCP, con riconnessione automatica (backoff) e stati in connessione/ripristino/connesso.
• GP Tom (SoftPOS) — driver di Global Payments che, sullo stesso tablet Android, comunica con l'app terminale GP (vendita/annullamento/reso; la chiusura giornaliera tramite questo percorso App2App non è ancora supportata).
• Display cliente: modello web (articoli e totale dell'ordine) che la Cassa vi invia; su Android si aggancia automaticamente, su desktop con selezione manuale del monitor.
• Stampante:
• ⚠️ Su Android, la stampa al momento viene solo accettata ma l'esecuzione effettiva della stampa non è implementata; la stampa reale funziona su desktop.
• Il desktop dispone di tre metodi: seriale, stampante di sistema (Windows) e rete/TCP (predefinito, porta 9100); include il taglio della carta e l'apertura del cassetto portavalori.
• Bilancia: solo su desktop — seriale o USB-HID, con rilevamento dell'unità (kg/g/lb/oz) e stato stabile/instabile. Android non dispone della bilancia.

3-4. Configurazione che l'installatore deve conoscere

• Porta (predefinita 8088) e indirizzo di binding (locale rispetto a rete).
• Differenza tra 127.0.0.1 (locale) e IP di rete: se la Cassa si trova sullo stesso dispositivo, è sufficiente la modalità locale; se si trova su un altro dispositivo, sono necessari la modalità di rete + l'IP ed entrambi devono trovarsi sulla stessa rete.
• Token di associazione (?token=…) solo nella modalità di rete.
• Impostazioni della batteria di Android (Keep Bridge Awake) per evitare interruzioni.

3-5. Risoluzione rapida dei problemi