Skip to main content

Trasporto Real-Time: NATS, LAN e WebSocket

Panoramica​

La piattaforma utilizza un sistema di trasporto real-time astratto per la comunicazione tra dispositivi. L'interfaccia RealtimeTransport nasconde i dettagli implementativi, consentendo di passare trasparentemente da una connessione cloud NATS a una comunicazione LAN diretta via WebSocket.

Interfaccia RealtimeTransport​

Tutti i trasporti implementano un contratto comune che espone:

  • connect() / disconnect() -- gestione del ciclo di vita della connessione
  • publish(subject, data) -- invio di un messaggio su un subject
  • subscribe(subject) -- ricezione di messaggi da un subject (con supporto wildcard)
  • isConnected -- stato corrente della connessione

Il wrapper RealtimeMessage sostituisce l'oggetto Message di dart_nats e utilizza la property .data per accedere al payload.

Implementazioni Disponibili​

NatsTransport​

Connessione diretta al broker NATS cloud. E il trasporto predefinito per installazioni standard con connettivita internet:

  • Comunicazione affidabile tramite protocollo NATS
  • Supporto subject gerarchici e wildcard (*, >)
  • Riconnessione automatica con backoff esponenziale

LanMasterTransport​

Trasporto per il dispositivo master della rete locale. La cassa principale (o un dispositivo designato) funge da hub WebSocket:

  • Avvia un server WebSocket sulla porta configurata (default 8090)
  • Accetta connessioni dagli altri dispositivi della rete locale
  • Inoltra i messaggi tra tutti i client connessi (broker locale)
  • Gestisce l'heartbeat per monitorare la connessione dei client

LanWsTransport​

Trasporto per i dispositivi client della rete locale. Tablet camerieri e display cucina si connettono al master:

  • Connessione WebSocket verso il master LAN
  • Riconnessione automatica in caso di disconnessione
  • Heartbeat (ping/pong) ogni 15 secondi, timeout dopo 3 miss consecutivi

AutoTransport​

Trasporto ibrido con failover automatico:

  • Tenta prima la connessione al broker NATS cloud
  • Se non raggiungibile, effettua il fallback su LAN WebSocket
  • Monitora la connessione e ripristina il trasporto primario quando disponibile

Protocollo LAN​

I messaggi scambiati via WebSocket LAN seguono un formato JSON envelope:

{
  "type": "message",
  "deviceId": "cassa-01",
  "subject": "orders.new",
  "payload": { "orderId": "abc123", "items": [...] }
}

Il subject supporta wildcard matching: * per un singolo segmento, > per segmenti multipli (compatibile con la semantica NATS).

Discovery mDNS​

Il servizio LanDiscoveryService utilizza il protocollo mDNS (tramite la libreria bonsoir) per scoprire automaticamente il dispositivo master nella rete locale:

  • Il master pubblica un servizio di tipo _pos-master._tcp
  • I client cercano questo servizio sulla rete locale
  • Una volta trovato, estraggono indirizzo IP e porta per la connessione WebSocket
  • Il campo autoDiscovery nella configurazione della workstation abilita questo comportamento

Configurazione Workstation​

La modalita di trasporto si configura nel modello WorkstationConfig (Isar):

CampoValoriDescrizione
transportModecloud, lan_master, lan_client, autoTipo di trasporto
isMastertrue/falseQuesto dispositivo e il master LAN
lanServerPort8090 (default)Porta del server WebSocket master
masterAddressIP:portaIndirizzo del master (se discovery disabilitato)
autoDiscoverytrue/falseAbilita la scoperta mDNS automatica

L'interfaccia di configurazione si trova in Impostazioni > Modalita Connessione sia nell'app cassa che nell'app cameriere.

FAQ​

D: Quale trasporto scegliere per il mio punto vendita? R: Per installazioni standard con internet affidabile, usare cloud (NATS). Per locali senza internet o con connettivita instabile, configurare una cassa come lan_master e i tablet come lan_client. La modalita auto e consigliata per la massima resilienza.

D: Quanti dispositivi supporta il master LAN? R: Il LanMasterTransport gestisce fino a 20-30 connessioni WebSocket simultanee, piu che sufficienti per un punto vendita tipico.

D: Cosa succede quando il master LAN va offline? R: I client perdono la comunicazione real-time ma continuano a funzionare in modalita offline. Alla riconnessione del master, le connessioni si ristabiliscono automaticamente.

Vedi Anche​

Questa pagina ti è stata utile?