LoRa Network Bridge - Documentazione

Panoramica

Il LoRa Network Bridge crea un'interfaccia di rete bidirezionale tra località remote utilizzando moduli radio LoRa. Invece delle tradizionali connessioni internet, questo sistema stabilisce un tunnel PPP (Point-to-Point Protocol) affidabile su LoRa, abilitando SSH, Mosh e altri servizi di rete attraverso distanze fino a diversi chilometri.

Nessuna connettività internet richiesta

Comunicazione radio diretta tra siti senza dipendenze da ISP o connettività internet.

Lungo raggio

Fino a 15km in linea d'aria con antenne appropriate e condizioni ottimali.

Sicuro

Crittografia LoRa integrata più SSH/TLS standard per sicurezza multi-livello.

Affidabile

Compatibile con battery pack con riconnessione automatica e monitoraggio salute hardware.

Basso consumo

Ottimizzato per implementazioni remote/off-grid con gestione energetica efficiente.

Semplicità di utilizzo

Installazione con un comando e gestione tramite systemd con script di utilità inclusi.

Caratteristiche

Networking core

PPP over LoRa: Interfaccia Linux ppp0 standard con bridging dati bidirezionale completo
Routing cross-LAN: Routing automatico tra reti remote
Traffic Shaping: Prioritizzazione SSH/Mosh integrata con HTB QoS (80% larghezza di banda prioritaria)
Compressione Dati: Compressione zlib automatica per migliore utilizzo della banda
Ottimizzazione MTU: Pacchetti da 200 byte ottimizzati per LoRa
Modalità Relay: Relay trasparente per estendere la portata (fino a 2x la distanza)

Connettività e strumenti

Wrapper SSH/Mosh: Script ottimizzati con auto-riconnessione
Monitoraggio real-time: Tracking RSSI e statistiche
Testing completo: Test larghezza di banda e latenza
Fallback di emergenza: Sistema di notifica integrato

Integrazione di sistema

Servizi systemd: Gestione completa del servizio
Rilevamento hardware: Riconoscimento automatico USB
Supporto battery pack: USB keepalive per portatilità
Installazione semplice: Setup con un comando

Prerequisiti

Requisiti hardware

Componente	Requisito	Note
Moduli LoRa	Basati su sx126x	Testati con 868MHz
Interfaccia USB	Silicon Labs CP2102	VID: 10c4, PID: ea60
Antenne	Appropriate per banda	Dipende da frequenza e portata
Alimentazione	USB 5V, 1A min	Compatibile battery pack

Requisiti software

Software	Versione	Note
Sistema operativo	Linux con systemd	Ubuntu 18.04+, Debian 10+, CentOS 7+
Python	3.6 o superiore	Con pip3 installato
Accesso root	Richiesto	Per interfaccia PPP e configurazione
PPP Daemon	pppd	Pacchetto standard Linux

Pianificazione di Rete

Aspetto	Configurazione	Esempio
Subnet IP	Due subnet differenti	10.0.1.0/24 e 192.168.1.0/24
Subnet LoRa	172.16.254.0/30	Configurata automaticamente
Routing	Route statiche	Opzionale ma raccomandato

Installazione

Avvio rapido

# 1. Clonare o scaricare il progetto
git clone <repository-url>
cd lora-network-bridge

# 2. Installare sul nodo ufficio
sudo ./install.sh --node-type office

# 3. Installare sul nodo casa
sudo ./install.sh --node-type home

# 4. (Opzionale) Installare nodo relay per estendere la portata
sudo ./install.sh --node-type relay

# 5. Avviare i servizi
sudo systemctl start lora-network@office.service   # Sul nodo ufficio
sudo systemctl start lora-network@home.service     # Sul nodo casa
sudo systemctl start lora-relay.service            # Sul nodo relay (se installato)

Installazione

1. Dipendenze di sistema

# Ubuntu/Debian - metodo preferito (pacchetti di sistema)
sudo apt-get update
sudo apt-get install python3 python3-pip pppd python3-yaml python3-serial

# Ubuntu/Debian - alternativo (pip con fallback per Debian 12+)
sudo apt-get install python3 python3-pip pppd
pip3 install --break-system-packages pyyaml pyserial

# CentOS/RHEL
sudo yum install python3 python3-pip ppp
pip3 install pyyaml pyserial

2. Driver LoRa (incluso)

Driver incluso: Il progetto include un driver sx126x.py modificato che è stato adattato per connessioni USB. Nessuna installazione separata richiesta.

3. Configurazione hardware

# Verificare il rilevamento del dispositivo
lsusb | grep "Silicon Labs"
# Output atteso: Bus 001 Device 004: ID 10c4:ea60 Silicon Labs CP2102 USB to UART Bridge Controller

# Verificare porta seriale
ls -la /dev/ttyUSB*
# Output atteso: crw-rw---- 1 root dialout 188, 0 Jul 18 10:19 /dev/ttyUSB0

4. Installare il sistema bridge

# Opzione A: Installazione interattiva
sudo ./install.sh

# Opzione B: Installazione automatizzata
sudo ./install.sh --node-type office --force

# Opzione C: Dry run per vedere cosa verrebbe installato
sudo ./install.sh --node-type office --dry-run

5. Verifica

# Controllare lo stato del servizio
sudo systemctl status lora-network@office.service

# Monitorare lo stato del bridge
lora-status

# Testare la connettività
lora-ssh -o  # Connettersi al nodo ufficio

Configurazione

File di configurazione principale

Il sistema utilizza lora_bridge.yaml per tutta la configurazione:

sudo nano /etc/lora-bridge/lora_bridge.yaml

Configurazione di esempio

# Configurazione LoRa Network Bridge

# Impostazioni LoRa comuni
lora:
  port: /dev/ttyUSB0  # Funzionerà anche come /dev/lora-usb dopo l'installazione
  frequency: 868      # MHz - regolare per la vostra regione
  power: 22          # dBm - regolare per le vostre esigenze
  air_speed: 2400    # bps - data rate aereo LoRa
  crypt_key: 0x1598  # chiave di crittografia a 16 bit

# Impostazioni specifiche del nodo
nodes:
  office:
    address: 100              # Indirizzo LoRa
    ip: 172.16.254.1         # IP tunnel LoRa
    peer_ip: 172.16.254.2    # IP tunnel remoto
    lan_subnet: 10.0.1.0/24  # Subnet LAN locale
    lan_ip: 10.0.1.200       # IP del bridge sulla LAN locale
  home:
    address: 200
    ip: 172.16.254.2
    peer_ip: 172.16.254.1
    lan_subnet: 192.168.1.0/24
    lan_ip: 192.168.1.200

# Ottimizzazioni di rete
network:
  mtu: 200           # Ottimale per LoRa
  compression: true  # Abilita compressione dati
  dns_servers:
    - 1.1.1.1
    - 8.8.8.8

Parametri di configurazione

Impostazioni LoRa

Parametro	Descrizione	Default	Note
`port`	Dispositivo seriale	`/dev/ttyUSB0`	Auto-rileva dispositivo USB
`frequency`	Frequenza radio	`868`	MHz - controllare regolamentazioni locali
`power`	Potenza di trasmissione	`22`	dBm - bilanciare portata vs consumo
`air_speed`	Data rate	`2400`	bps - più alto = portata minore
`crypt_key`	Chiave di crittografia	`0x1598`	Valore hex a 16 bit

Impostazioni di rete

Parametro	Descrizione	Default	Note
`mtu`	Dimensione massima pacchetto	`200`	Byte - ottimizzato per LoRa
`compression`	Abilita compressione	`true`	Raccomandato per larghezza di banda
`dns_servers`	Server DNS	`1.1.1.1, 8.8.8.8`	Per traffico tunnel

Topologia di rete

Connessione diretta (Standard):

LAN ufficio (10.0.1.0/24)          LAN casa (192.168.1.0/24)
         |                                    |
   [Router ufficio]                      [Router casa]
         |                                    |
   [PC ufficio]                          [PC casa]
   10.0.1.100                          192.168.1.100
         |                                    |
   [Nodo LoRa ufficio] <--- LoRa ---> [Nodo LoRa casa]
   10.0.1.200                         192.168.1.200
   172.16.254.1                       172.16.254.2

Con Relay (Portata estesa):

LAN ufficio (10.0.1.0/24)                     LAN casa (192.168.1.0/24)
         |                                                 |
   [Router ufficio]                               [Router casa]
         |                                                 |
   [PC ufficio]          [Nodo Relay]                [PC casa]
   10.0.1.100              (Solare)                192.168.1.100
         |                    |                            |
   [LoRa ufficio] <-5km-> [LoRa Relay] <-5km-> [LoRa casa]
   10.0.1.200                150                 192.168.1.200
   172.16.254.1         (Trasparente)            172.16.254.2
   Indirizzo: 100                               Indirizzo: 200

Configurazione router per cross-LAN

Opzionale ma raccomandato: Queste route permettono a qualsiasi dispositivo su entrambe le LAN di comunicare attraverso il bridge LoRa senza configurazione manuale.

# Router ufficio
ip route add 172.16.254.0/30 via 10.0.1.200
ip route add 192.168.1.0/24 via 10.0.1.200

# Router casa
ip route add 172.16.254.0/30 via 192.168.1.200
ip route add 10.0.1.0/24 via 192.168.1.200

Test connettività cross-LAN

Dal PC ufficio (10.0.1.100):

# Ping nodo LoRa casa
ping 172.16.254.2

# Ping dispositivo su LAN casa
ping 192.168.1.100

# Traceroute per vedere il percorso attraverso bridge LoRa
traceroute 192.168.1.100

# Output traceroute atteso:
# 1  10.0.1.200 (10.0.1.200)     1.234 ms  # Nodo LoRa ufficio
# 2  172.16.254.2 (172.16.254.2) 1567.891 ms  # Nodo LoRa casa via LoRa
# 3  192.168.1.100 (192.168.1.100) 1598.123 ms  # Dispositivo target

Dal PC casa (192.168.1.100):

# Ping nodo LoRa ufficio
ping 172.16.254.1

# Ping dispositivo su LAN ufficio
ping 10.0.1.100

# SSH verso dispositivi ufficio attraverso LoRa
ssh user@10.0.1.100

Nota: La configurazione del router abilita connettività senza soluzione di continuità dove qualsiasi dispositivo su entrambe le reti può comunicare attraverso il bridge LoRa senza routing manuale.

Esempi di utilizzo

Operazioni base

Gestione servizio

# Avvio manuale
sudo systemctl start lora-network@office.service

# Abilitare avvio automatico
sudo systemctl enable lora-network@office.service

# Controllare stato
sudo systemctl status lora-network@office.service

# Visualizzare log
sudo journalctl -u lora-network@office.service -f

Monitoraggio

# Stato base
lora-status

# Statistiche dettagliate
lora-status -s

# Monitoraggio continuo
lora-status -w

# Output JSON per script
lora-status -j

Connessioni remote

# Connettersi al nodo ufficio
lora-ssh -o

# Connettersi al nodo casa
lora-ssh -H

# Connettersi con utente personalizzato
lora-ssh -o -u admin

# Eseguire comando remoto
lora-ssh -o "df -h"

# Connettersi con tmux invece di screen
lora-ssh -o -t

# Connettersi al nodo ufficio
lora-mosh -o

# Connettersi con range di porte personalizzato
lora-mosh -H -p 60020:60030

# Connettersi con timeout specifico
lora-mosh -o --timeout 120

# Test completo
python3 lora_network.py --type office --mode test

# LoRa ping test
python3 lora_network.py --type office --mode ping

# Monitoraggio traffico
python3 lora_network.py --type office --mode monitor

# Statistiche storiche
python3 lora_network.py --type office --stats

Architettura

Stack protocollo

┌─────────────────────┐
│   Applicazione      │  SSH, Mosh, HTTP, ecc.
├─────────────────────┤
│   TCP/IP            │  Networking standard
├─────────────────────┤
│   PPP               │  Point-to-Point Protocol
├─────────────────────┤
│   LoRa Bridge       │  Compressione + Gestione pacchetti
├─────────────────────┤
│   Driver sx126x     │  Interfaccia radio LoRa
├─────────────────────┤
│   USB Seriale       │  CP2102 USB-to-UART
└─────────────────────┘

Flusso dati

Applicazione (SSH/Mosh) crea pacchetto di rete
Kernel Linux instrada pacchetto all'interfaccia ppp0
PPP daemon incapsula pacchetto in frame PPP e scrive su pseudo-terminale (pty)
Thread PPP-to-LoRa Bridge legge frame dal file descriptor master del pty
Compressione applica compressione zlib se vantaggiosa
Pacchetto LoRa viene costruito con indirizzamento e flag di compressione
Driver sx126x trasmette pacchetto via radio LoRa
Nodo remoto riceve pacchetto nel Thread LoRa-to-PPP Bridge
Decompressione ripristina frame PPP originale
Bridge scrive su pty che inoltra al demone PPP e poi all'applicazione

Architettura PPP/PTY

Il sistema usa pseudo-terminali (pty) per separare PPP dall'hardware LoRa:

Applicazione ↔ ppp0 ↔ Demone PPP ↔ pty slave ↔ pty master ↔ Bridge Python ↔ Seriale LoRa

Questa architettura previene conflitti di dispositivo e permette un controllo appropriato del flusso dati.

Struttura file

lora-network-bridge/
├── lora_network.py              # Applicazione bridge principale (include modalità relay)
├── sx126x.py                    # Driver LoRa modificato (da Waveshare, adattato USB)
├── lora_bridge.yaml             # File di configurazione per nodi ufficio/casa
├── lora_bridge_relay.yaml       # File di configurazione per nodo relay
├── lora_network_optimize.sh     # Script ottimizzazione rete (opzionale, vedi nota sotto)
├── lora-network@.service        # Template servizio systemd per ufficio/casa
├── lora-relay.service           # Servizio systemd per nodo relay
├── install.sh                   # Script di installazione (supporta relay)
├── lora-ssh                     # Script wrapper SSH
├── lora-mosh                    # Script wrapper Mosh
├── lora-status                  # Script monitoraggio stato
└── README.md                    # Questo file

Modalità Relay (Portata estesa)

Panoramica

La modalità relay estende la portata della rete LoRa aggiungendo un nodo relay intermedio che inoltra trasparentemente i pacchetti tra i nodi ufficio e casa. Questo può effettivamente raddoppiare la distanza di comunicazione senza modificare i nodi esistenti.

Quando usare la modalità Relay

Limitazione di distanza: Quando ufficio e casa sono troppo distanti per comunicazione diretta
Ostacoli: Quando terreno o edifici bloccano la linea di vista diretta
Qualità del segnale: Quando la connessione diretta ha RSSI scarso o alta perdita di pacchetti
Estensione copertura: Per raggiungere località remote oltre la normale portata LoRa

Configurazione Relay

# 1. Posizionare il nodo relay nel punto ottimale tra ufficio e casa
# 2. Installare il nodo relay
sudo ./install.sh --node-type relay

# 3. Configurare relay (modificare se necessario)
sudo nano /etc/lora-bridge/lora_bridge_relay.yaml

# 4. Avviare servizio relay
sudo systemctl start lora-relay.service
sudo systemctl enable lora-relay.service

# 5. Monitorare operazione relay
sudo journalctl -u lora-relay.service -f

Topologia Relay

Ufficio (100) <--5km--> Relay (150) <--5km--> Casa (200)
                      = 10km portata totale

Caratteristiche Relay

Operazione trasparente

Nessuna modifica necessaria ai nodi ufficio/casa esistenti

Deduplicazione pacchetti

Previene loop di inoltro con cache intelligente

Monitoraggio RSSI

Traccia forza segnale da entrambe le direzioni

Bassa latenza

Aggiunge solo ~50-100ms per hop

Test modalità Relay

# Eseguire relay in modalità test
python3 lora_network.py --type relay --mode relay --debug

# Monitorare statistiche relay
watch -n 1 'sudo journalctl -u lora-relay.service --no-pager | tail -20'

# Testare connettività attraverso relay
# Da ufficio: ping 172.16.254.2
# Da casa: ping 172.16.254.1

File configurazione Relay

Il file lora_bridge_relay.yaml contiene la configurazione specifica per il nodo relay:

# Impostazioni LoRa - DEVONO corrispondere ai nodi ufficio e casa
lora:
  port: /dev/ttyUSB0
  frequency: 868      # CRITICO: Deve corrispondere agli altri nodi
  power: 22          # Può essere più alto per migliore copertura
  air_speed: 2400    # CRITICO: Deve corrispondere agli altri nodi
  crypt_key: 0x1598  # CRITICO: Deve corrispondere per relay trasparente

# Configurazione nodo relay
nodes:
  relay:
    address: 150     # Indirizzo unico (tra ufficio:100 e casa:200)

Risoluzione problemi

Suggerimento: La maggior parte dei problemi può essere risolta controllando log di sistema, connessioni USB e configurazione. Utilizzare sempre --debug per diagnostica dettagliata.

Problemi comuni e soluzioni

Bridge PPP non funziona / Nessun flusso dati

Sintomi: Interfaccia PPP attiva ma nessun dato fluisce, impossibile pingare nodo remoto, connessioni SSH in timeout.

Causa: Versioni precedenti avevano un'architettura errata dove PPP e Python accedevano allo stesso dispositivo seriale.

Soluzione:

# Verificare versione con supporto pty
sudo journalctl -u lora-network@office.service | grep "Created pty pair"
# Verificare thread bridging attivi
sudo journalctl -u lora-network@office.service | grep "bridge thread"

Errori validazione configurazione

# Modificare configurazione
sudo nano /etc/lora-bridge/lora_bridge.yaml

# Verificare valori:
# frequency: 410-928 MHz
# power: 2-22 dBm
# air_speed: valori standard

Dispositivo non trovato

# Verificare USB
lsusb | grep "Silicon Labs"

# Verificare permessi
sudo usermod -a -G dialout $USER
newgrp dialout

Interfaccia PPP non si avvia

# Installare PPP
sudo apt-get install pppd

# Riavviare servizio
sudo systemctl restart lora-network@office.service

Modalità Debug

# Eseguire con logging debug
python3 lora_network.py --type office --mode bridge --debug

# Monitorare log di sistema
sudo journalctl -u lora-network@office.service -f

# Controllare salute hardware
sudo journalctl -u lora-network@office.service | grep -i "health\|hardware"

Considerazioni sulle prestazioni

Larghezza di banda

Teorico: ~300 byte/secondo (2400 bps)
Pratico: ~240 byte/secondo (dopo overhead protocollo)
Latenza: 1-3 secondi RTT
Sessioni interattive: 6-8 tasti premuti/secondo

Traffic shaping

Alta priorità: SSH, Mosh (2000 bps, burst fino a 2400 bps)
Bassa priorità: Dati bulk (400 bps, burst fino a 2400 bps)
Totale: 2400 bps (corrisponde alla velocità aerea configurata)

Nota: Il traffic shaping è ora integrato direttamente in lora_network.py e viene configurato automaticamente all'avvio del bridge. Lo script lora_network_optimize.sh è ora opzionale - tutte le ottimizzazioni critiche (traffic shaping, tuning TCP, configurazione DNS) sono integrate nell'applicazione principale.

Consumo energetico

Idle: ~100mA @ 5V
TX: ~200mA @ 5V
Runtime: 8-12h con 10Ah

Ottimizzazioni consigliate

• Usare SSH connection multiplexing
• Abilitare compressione per tutte le connessioni
• Evitare trasferimenti file durante sessioni interattive
• Usare screen o tmux per sessioni persistenti

Note sulla sicurezza

Caratteristiche di sicurezza

Crittografia hardware LoRa a 16 bit
Nessuna esposizione Internet
SSH/TLS standard sopra LoRa
Validazione configurazione automatica
Monitoraggio salute hardware

Best practices

Usare autenticazione SSH con chiave
Aggiornamenti di sicurezza regolari
Monitorare log per attività anomale
Considerare VPN su LoRa
Protezione fisica dei nodi

Limitazioni

Crittografia LoRa relativamente debole
Trasmissioni radio intercettabili
Sicurezza fisica critica
Nessuna forward secrecy nativa

Hardening raccomandato

# Disabilitare autenticazione password SSH
sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd

# Setup chiave SSH
ssh-keygen -t ed25519 -f ~/.ssh/lora_key
ssh-copy-id -i ~/.ssh/lora_key.pub user@172.16.254.1

# Installare fail2ban
sudo apt-get install fail2ban