LoRa TUN Network Bridge

Interfaccia TUN a bassa latenza tramite LoRa per connettività remota affidabile

v2.0.0

Panoramica

Il LoRa TUN Network Bridge crea un'interfaccia di rete Linux standard (lora0) tra località remote utilizzando moduli radio LoRa. A differenza delle soluzioni basate su PPP, questa implementazione utilizza un'interfaccia TUN per ridurre l'overhead e garantire prestazioni migliori, rendendo SSH e altri servizi di rete utilizzabili anche a basse velocità dati LoRa.

Perché LoRa TUN Bridge?
  • Nessuna connessione Internet richiesta: comunicazione radio diretta tra siti
  • Lungo raggio: fino a 15km in linea d'aria con antenne appropriate
  • Bassa latenza: l'interfaccia TUN elimina il sovraccarico del protocollo PPP
  • Affidabile: riconnessione automatica con monitoraggio watchdog
  • Efficiente: compressione, FEC e gestione pacchetti ottimizzata

Caratteristiche

Networking core

  • Interfaccia TUN: interfaccia Linux standard lora0 con sovraccarico di protocollo minimo
  • Compressione avanzata: compressione LZ4 con soli 3 byte di sovraccarico (riduzione tipica dell'83%)
  • Forward Error Correction: Reed-Solomon FEC per recupero pacchetti
  • Controllo intelligente della congestione: gestione adattiva delle code basata sulla qualità del collegamento
  • Ottimizzazione MTU: pacchetti da 100 byte ottimizzati per LoRa con header minimi
  • CSMA/CA: accesso multiplo con rilevamento di portante per evitare collisioni

Miglioramenti prestazioni

  • Aggregazione pacchetti: combina pacchetti piccoli per ridurre il sovraccarico LoRa
  • Code prioritarie: prioritizzazione traffico SSH/interattivo
  • Tracciamento statistiche: monitoraggio e analisi delle prestazioni in tempo reale
  • Terminal UDP: terminale ottimizzato per collegamenti a banda ridotta
  • Recupero automatico: servizio watchdog con capacità di reset hardware
  • Velocità configurabili: 1200-19200 bps air rate via configurazione YAML

Integrazione sistema

  • Servizi systemd: gestione completa servizi con auto-start
  • Configurazione YAML: tutte le impostazioni in /etc/lora/lora-tun.yaml
  • Monitoraggio hardware: reset modulo LoRa via GPIO
  • Strumenti diagnostici: test e debugging completi

Prerequisiti

Requisiti hardware

Componente Requisito Note
Moduli LoRa Basati su sx126x Compatibili con frequenze 868MHz (EU) / 915MHz (US)
Interfaccia USB Silicon Labs CP2102 USB-to-UART bridge
Accesso GPIO Per il reset hardware Funzionalità Raspberry Pi
Antenne Appropriate per banda Frequenza e portata
Alimentazione 5V USB Compatibile battery pack

Requisiti software

Software Versione Note
Sistema operativo Linux con systemd Raspberry Pi OS, Ubuntu 20.04+, Debian 11+
Python 3.7 o superiore Con pip3
Pacchetti Python pyserial, pyyaml, lz4 Installabili via pip3
Accesso root Richiesto Per creazione interfaccia TUN
iproute2 Standard Gestione interfacce di rete

Pianificazione rete

Aspetto Configurazione Esempio
Subnet LoRa 172.16.254.0/24 Configurabile
Nodo ufficio 172.16.254.1 IP interfaccia TUN
Nodo casa 172.16.254.2 IP interfaccia TUN
MTU 100 byte Ottimale per LoRa

Installazione

Avvio rapido

# 1. Clonare il repository
git clone <repository-url>
cd lora-tun-bridge

# 2. Installare sul nodo ufficio
sudo ./install-lora-tun.sh office

# 3. Installare sul nodo casa
sudo ./install-lora-tun.sh home

# 4. Avviare i servizi
sudo systemctl start lora-tun-office    # Sul nodo ufficio
sudo systemctl start lora-tun-home      # Sul nodo casa

Installazione passo-passo

1. Dipendenze di sistema

# Raspberry Pi OS / Debian / Ubuntu
sudo apt-get update
sudo apt-get install python3 python3-pip iproute2
sudo pip3 install pyserial pyyaml lz4

# Per il supporto GPIO (Raspberry Pi)
sudo apt-get install python3-rpi.gpio

2. Installare sistema bridge

# Eseguire lo script di installazione
sudo ./install-lora-tun.sh office  # o 'home'

# Questo comando:
# - Copiare i file in /opt/lora/
# - Installare servizi systemd
# - Creare configurazione in /etc/lora/lora-tun.yaml
# - Configurare interfacce di rete
# - Installare script helper

3. Configurazione

Modificare /etc/lora/lora-tun.yaml:

lora:
  port: /dev/lora-usb       # Porta seriale USB
  frequency: 868            # MHz (868 EU, 915 US)
  power: 22                 # dBm (max potenza legale)
  air_speed: 9600          # bps (1200-19200)
  serial_baud: 9600        # Deve corrispondere ad air_speed

network:
  mtu: 100                 # Ottimale per LoRa
  tcp_mss: 60              # TCP maximum segment size
  queue_size: 20           # Profondità coda pacchetti

# Configurazione ufficio
office:
  address: 100             # Indirizzo LoRa
  ip: 172.16.254.1        # IP interfaccia TUN

# Configurazione casa  
home:
  address: 200
  ip: 172.16.254.2

# Caratteristiche opzionali
features:
  compression: true        # Compressione LZ4
  fec: true               # Forward error correction
  csma: true              # Evitamento collisioni
  stats: true             # Tracking prestazioni

4. Verifica

# Controllare lo stato del servizio
sudo systemctl status lora-tun-office

# Controllare l'interfaccia
ip addr show lora0

# Visualizzare i log
sudo journalctl -u lora-tun-office -f

# Testare la connettività
ping 172.16.254.2          # Dall'ufficio a casa

Gestione configurazione

Unica fonte di verità

Tutta la configurazione è gestita attraverso /etc/lora/lora-tun.yaml. Non ci sono default hardcoded - il file YAML è richiesto.

Guida tuning velocità

Massima portata (molto lento)

lora:
  air_speed: 1200
  serial_baud: 1200
network:
  mtu: 80
  tcp_mss: 40

Prestazioni bilanciate (raccomandato)

lora:
  air_speed: 9600
  serial_baud: 9600
network:
  mtu: 100
  tcp_mss: 60

Corto raggio, alta velocità

lora:
  air_speed: 19200
  serial_baud: 19200
network:
  mtu: 150
  tcp_mss: 100

Applicare modifiche

# Modificare configurazione
sudo nano /etc/lora/lora-tun.yaml

# Riavviare il servizio
sudo systemctl restart lora-tun-office

Struttura progetto

Panoramica dei file

lora-tun-bridge/
├── Componenti core
│   ├── lora_tun.py              # Applicazione TUN bridge principale
│   ├── sx126x.py                # Driver LoRa modificato (adattato USB)
│   └── lora-tun-example.yaml    # Template di configurazione
│
├── Installazione & servizi
│   ├── install-lora-tun.sh      # Script di installazione
│   ├── lora-tun-office.service  # Servizio systemd per ufficio
│   ├── lora-tun-home.service    # Servizio systemd per casa
│   ├── lora-watchdog.service    # Servizio watchdog
│   ├── lora-watchdog.sh         # Script del watchdog
│   └── lora-watchdog-daemon.sh  # Daemon watchdog
│
├── Strumenti helper
│   ├── lora-status              # Monitoraggio stato interfaccia
│   ├── lora-ssh                 # Interfaccia SSH (non raccomandata)
│   ├── lora-terminal            # Interfaccia terminal UDP
│   └── reset-lora.sh            # Script di reset hardware
│
└── Opzioni terminal
    ├── udp-terminal.py          # Terminal UDP funzionale (raccomandato)
    ├── lora_terminal.py         # Funzionalità avanzate ma non operativo
    └── lora_terminal_fec.py     # Terminal FEC per seriale diretta

Strumenti helper

lora-status

Monitora lo stato dell'interfaccia LoRa TUN e le relative statistiche:

# Stato base
lora-status

# Esempio di output:
# LoRa TUN Status
# ===============
# Interface: lora0
# Status: UP
# IP: 172.16.254.1/24
# RX: 1234567 bytes (10234 packets)
# TX: 987654 bytes (8765 packets)
# Errors: 12 dropped, 0 overruns

lora-terminal (raccomandato)

Interfaccia semplificata per il terminal UDP:

# Si connette automaticamente all'altro nodo
lora-terminal

# Connessione manuale
lora-terminal 172.16.254.2

# Caratteristiche:
# - Rileva automaticamente a quale nodo connettersi
# - Molto più reattivo rispetto a SSH
# - Gestisce correttamente l'MTU ridotto di LoRa

lora-ssh (non raccomandato)

Wrapper SSH con ottimizzazioni LoRa:

# Connettersi al nodo remoto
lora-ssh

# Limitazioni:
# - Estremamente lento anche a 9600 bps
# - Può andare in timeout con connessioni di scarsa qualità
# - Il terminal UDP è molto più efficiente

Servizio watchdog

Il servizio watchdog provvede al recupero automatico dai guasti:

Caratteristiche

  • Monitoraggio dello stato dell'interfaccia TUN
  • Rilevamento dei guasti del servizio
  • Esecuzione del reset hardware tramite GPIO
  • Riavvio automatico dei servizi
  • Registrazione di tutte le azioni di recupero

Configurazione

# Abilitare il watchdog
sudo systemctl enable lora-watchdog
sudo systemctl start lora-watchdog

# Controllare lo stato del watchdog
sudo systemctl status lora-watchdog

# Visualizzare i log del watchdog
sudo journalctl -u lora-watchdog -f

Opzioni terminal

udp-terminal.py (raccomandato)

Il terminal UDP funzionale ottimizzato per LoRa TUN:

# Modalità server
/opt/lora/udp-terminal.py -s

# Modalità client
/opt/lora/udp-terminal.py 172.16.254.1

# Caratteristiche:
# - Gestisce MTU ridotto (blocchi da 60 byte)
# - Meccanismo keepalive (senza timeout)
# - Modalità di debug (opzione -d)
# - Emulazione corretta del terminale
# - Funziona in modo affidabile su collegamenti con perdite
Altre implementazioni terminal: Sono incluse ma non raccomandate:
  • lora_terminal.py: Presenta funzionalità avanzate (ACK/ritrasmissione, sliding window, controllo di flusso) ma non è mai stato operativo correttamente con l'interfaccia TUN
  • lora_terminal_fec.py: Progettato per connessione seriale diretta con FEC, non compatibile con interfaccia TUN

Esempi di utilizzo

Operazioni base

Gestione servizio

# Start/stop/restart
sudo systemctl start lora-tun-office
sudo systemctl stop lora-tun-office
sudo systemctl restart lora-tun-office

# Abilitare l'avvio automatico
sudo systemctl enable lora-tun-office

# Visualizzare i log
sudo journalctl -u lora-tun-office -f

Test di rete

# Eseguire ping al nodo remoto
ping 172.16.254.2

# SSH al nodo remoto (prestazioni limitate ma funzionale)
ssh user@172.16.254.2

# Utilizzare il terminal UDP (raccomandato)
lora-terminal              # Si connette automaticamente al nodo remoto

Terminal UDP (raccomandato per uso interattivo)

Il terminal UDP fornisce una reattività migliore rispetto a SSH sul collegamento LoRa a banda ridotta:

# Sul nodo server (ufficio)
/opt/lora/udp-terminal.py -s

# Sul nodo client (casa)  
/opt/lora/udp-terminal.py 172.16.254.1

# Oppure utilizzare il wrapper per il rilevamento automatico
lora-terminal              # Si connette automaticamente all'altro nodo

# Modalità di debug per la diagnostica
/opt/lora/udp-terminal.py -s -d

Monitoraggio e diagnostica

Monitoraggio stato

# Mostrare lo stato dell'interfaccia
lora-status

# Statistiche dettagliate
sudo /opt/lora/lora_tun.py office --mode stats

# Osservare il flusso dei pacchetti
sudo tcpdump -i lora0 -n

Test prestazioni

# Testare la connettività con statistiche
sudo /opt/lora/lora_tun.py office --mode ping

# Monitora efficacia compressione
sudo journalctl -u lora-tun-office | grep "Compressed"

Strumenti diagnostici

# Controllare l'hardware
ls -la /dev/ttyUSB*
lsusb | grep "Silicon Labs"

# Testare il modulo LoRa
sudo /opt/lora/lora_tun.py office --mode test

Architettura

Panoramica sistema

Livello applicazione
    ↓
Stack TCP/IP
    ↓
Interfaccia TUN (lora0)
    ↓
Python Bridge (lora_tun.py)
    ├── Compressione (LZ4)
    ├── FEC (Reed-Solomon)
    ├── Gestione code
    └── Aggregazione pacchetti
    ↓
Porta seriale (/dev/ttyUSB0)
    ↓
Modulo LoRa (SX126x)
    ↓
Link radio

Formato pacchetto

[Overhead: 3 byte]
┌─────────┬──────────┬─────────┐
│ Length  │ Compress │ Payload │
│ 2 bytes │ 1 byte   │Variable │
└─────────┴──────────┴─────────┘

Byte compressione:
- 0x00: Non compresso
- 0x01: Compresso LZ4  
- 0x02: Con FEC
- 0x03: LZ4 + FEC

Componenti chiave

Interfaccia TUN

  • Interfaccia di rete Linux standard
  • Nessun sovraccarico PPP
  • Gestione diretta pacchetti IP
  • Setup routing automatico

Motore compressione

  • Compressione LZ4 (veloce, efficiente)
  • Solo 3 byte di sovraccarico
  • Riduzione tipica 70-85%
  • Bypass automatico per pacchetti piccoli

Sistema FEC

  • Correzione errori Reed-Solomon
  • Recupera da corruzione pacchetti
  • Ridondanza configurabile
  • Overhead minimo per pacchetti piccoli

Gestione code

  • Code prioritarie per SSH/interattivo
  • Controllo congestione
  • Aggregazione automatica pacchetti
  • Gestione overflow

Risoluzione problemi

Problemi comuni

1. Interfaccia non si avvia

# Controllare lo stato del servizio
sudo systemctl status lora-tun-office

# Controllare gli errori
sudo journalctl -u lora-tun-office --no-pager | grep ERROR

# Verificare il dispositivo USB
ls -la /dev/ttyUSB*

2. Nessuna comunicazione

# Controllare che la configurazione sia identica su entrambi i nodi
diff /etc/lora/lora-tun.yaml <(ssh remote-node cat /etc/lora/lora-tun.yaml)

# Test modalità diretta
sudo /opt/lora/lora_tun.py office --mode test

# Controllare i parametri radio
grep -E "frequency|air_speed|power" /etc/lora/lora-tun.yaml

3. Alta perdita pacchetti

# Controllare la forza del segnale
sudo journalctl -u lora-tun-office | grep RSSI

# Ridurre la velocità per una portata migliore
sudo nano /etc/lora/lora-tun.yaml
# Impostare air_speed: 4800

# Riavviare il servizio
sudo systemctl restart lora-tun-office

4. SSH molto lento o bloccato

# Utilizzare il terminal UDP in alternativa
lora-terminal

# Oppure ridurre l'MTU per SSH
sudo ip link set lora0 mtu 80

# Controllare la perdita di pacchetti
ping -c 100 172.16.254.2

5. Problemi hardware

# Reset del dispositivo USB
sudo /opt/lora/reset-lora.sh

# Controllare il reset GPIO (se configurato)
gpio readall | grep 17

# Reset manuale del modulo
sudo systemctl stop lora-tun-office
# Disconnettere/riconnettere fisicamente l'USB
sudo systemctl start lora-tun-office

Modalità debug

# Eseguire con output di debug
sudo /opt/lora/lora_tun.py office --debug

# Abilitare la modalità statistiche
sudo /opt/lora/lora_tun.py office --mode stats

# Catturare i pacchetti
sudo tcpdump -i lora0 -w lora-capture.pcap

Procedure di recupero

Recupero watchdog

Il servizio watchdog recupera automaticamente dai guasti:

# Controllare lo stato del watchdog
sudo systemctl status lora-watchdog

# Visualizza azioni watchdog
sudo journalctl -u lora-watchdog -f

Recupero manuale

# Sequenza reset completa
sudo systemctl stop lora-tun-office
sudo systemctl stop lora-watchdog
sudo /opt/lora/reset-lora.sh
sudo systemctl start lora-watchdog
sudo systemctl start lora-tun-office

Ottimizzazione prestazioni

Prestazioni attese

A 9600 bps air speed:

  • Throughput teorico: ~1200 byte/secondo
  • Throughput pratico: ~800 byte/secondo (con sovraccarico)
  • Latenza ping: 500-800ms tipica
  • Latenza SSH: ~500ms per pressione tasto
  • Rapporto compressione: 70-85% per traffico tipico

Suggerimenti ottimizzazione

1. Utilizzare il terminal UDP invece di SSH

# Molto più reattivo di SSH
lora-terminal

2. Abilitare la compressione (predefinita)

La compressione tipicamente riduce il traffico del 70-85%:

features:
  compression: true

3. Ottimizzare per il proprio caso d'uso

  • Interattivo (SSH/Terminal): Utilizzare il valore predefinito di 9600 bps
  • Monitoraggio/Telemetria: È possibile utilizzare 4800 bps per maggiore portata
  • Trasferimento file: Disabilitare FEC per maggiore throughput

4. Monitorare le prestazioni

# Controllare le statistiche di compressione
sudo journalctl -u lora-tun-office | grep "stats"

# Monitorare la profondità delle code
watch -n 1 'sudo /opt/lora/lora_tun.py office --mode stats'

Funzionalità avanzate

Aggregazione pacchetti

I pacchetti piccoli vengono automaticamente combinati per ridurre il sovraccarico LoRa:

  • Attesa fino a 50ms per aggregare i pacchetti
  • Combinazione fino alla dimensione MTU
  • Miglioramento significativo dell'efficienza per pacchetti piccoli

Controllo congestione

Gestione code adattiva basata su qualità del link:

  • Monitoraggio della perdita di pacchetti e della latenza
  • Regolazione dinamica della profondità delle code
  • Prevenzione del buffer bloat
  • Prioritizzazione del traffico interattivo

Tracking statistiche

Monitoraggio prestazioni completo:

# Visualizzare le statistiche correnti
sudo /opt/lora/lora_tun.py office --mode stats

# L'output include:
# - Pacchetti inviati/ricevuti
# - Rapporti compressione
# - Profondità code
# - Conteggi errori
# - Statistiche recupero FEC

Benchmark prestazioni

Prestazioni tipiche (9600 bps)

Metrica Valore Note
Throughput raw 1200 byte/s Massimo teorico
Throughput effettivo 800 byte/s Con sovraccarico del protocollo
Rapporto compressione 70-85% Per traffico tipico
Ping RTT 500-800ms Dipende dal carico
Ritardo pressione tasto SSH ~500ms Utilizzabile per digitazione attenta
Ritardo terminal UDP ~200ms Migliore per uso interattivo
Perdita pacchetti <5% Con buon segnale

Compromessi portata vs velocità

Air speed Portata tipica Caso d'uso
1200 bps 15+ km Massima portata, monitoraggio
2400 bps 12 km Lunga portata, connettività base
4800 bps 8 km Portata/velocità bilanciate
9600 bps 5 km Uso interattivo (raccomandato)
19200 bps 2 km Alta velocità, corto raggio

Considerazioni sulla sicurezza

Sicurezza integrata

Caratteristiche di sicurezza

  • Crittografia LoRa: livello hardware (chiave 16-bit)
  • Isolamento rete: interfaccia TUN privata
  • Nessuna esposizione Internet: solo link radio
  • Sicurezza Linux standard: iptables, chiavi SSH, ecc.

Migliori pratiche

  1. Utilizzare chiavi SSH invece di password
  2. Abilitare il firewall sull'interfaccia TUN
  3. Monitorare i log per attività insolite
  4. Garantire la sicurezza fisica dei nodi
  5. Effettuare aggiornamenti regolari del software di sistema

Configurazione firewall

# Firewall base per interfaccia LoRa
sudo iptables -A INPUT -i lora0 -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A INPUT -i lora0 -p icmp -j ACCEPT
sudo iptables -A INPUT -i lora0 -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -i lora0 -p udp --dport 8888 -j ACCEPT  # Terminal UDP
sudo iptables -A INPUT -i lora0 -j DROP