`lora` — driver del modem LoRa¶

Il modulo lora fornisce un driver per il modem LoRa Murata CMWX1ZZABZ presente sull’Arduino Portenta Vision Shield. Espone una classe Lora di alto livello che incapsula il set di comandi AT utilizzato dal firmware del modem (incluso il firmware Arduino MKRWAN ARD-078) in modo che un’applicazione possa unirsi a una rete LoRaWAN e inviare/ricevere pacchetti.

Esempio:

import lora

modem = lora.Lora(band=lora.BAND_EU868, debug=True)
print("Device EUI:", modem.get_device_eui())
if modem.join_OTAA("0000000000000000", "00000000000000000000000000000000"):
    modem.send_data(b"hello", confirmed=True)

Costanti¶

Modalità di attivazione¶

lora.MODE_ABP: int¶: Modalità Activation By Personalization.

lora.MODE_OTAA: int¶: Modalità Over-The-Air Activation.

Modalità di uscita RF¶

lora.RF_MODE_RFO: int¶: Usa l’uscita RF RFO (a bassa potenza) del modem.

lora.RF_MODE_PABOOST: int¶: Usa l’uscita RF PA_BOOST (ad alta potenza) del modem.

Bande¶

lora.BAND_AS923: int¶: Banda regionale AS923 (Asia 923 MHz).

lora.BAND_AU915: int¶: Banda regionale AU915 (Australia 915 MHz).

lora.BAND_EU868: int¶: Banda regionale EU868 (Europa 868 MHz).

lora.BAND_KR920: int¶: Banda regionale KR920 (Corea 920 MHz).

lora.BAND_IN865: int¶: Banda regionale IN865 (India 865 MHz).

lora.BAND_US915: int¶: Banda regionale US915 (Stati Uniti 915 MHz).

lora.BAND_US915_HYBRID: int¶: Piano regionale US915 ibrido (sotto-banda).

Classi di dispositivo¶

lora.CLASS_A: str¶: Dispositivo terminale LoRaWAN di Classe A.

lora.CLASS_B: str¶: Dispositivo terminale LoRaWAN di Classe B.

lora.CLASS_C: str¶: Dispositivo terminale LoRaWAN di Classe C.

Eccezioni¶

exception lora.LoraError¶: Eccezione di base sollevata per qualsiasi errore restituito dal modem o dal driver.

exception lora.LoraErrorTimeout¶: Sollevata quando il modem non risponde entro il timeout configurato (il buffer di ricezione è vuoto).

exception lora.LoraErrorParam¶: Sollevata su una risposta +ERR_PARAM quando un comando AT è stato emesso con un parametro non valido.

exception lora.LoraErrorBusy¶: Sollevata su una risposta +ERR_BUSY quando il modem è occupato a elaborare un comando precedente.

exception lora.LoraErrorOverflow¶: Sollevata su una risposta +ERR_PARAM_OVERFLOW quando un parametro supera la lunghezza massima consentita.

exception lora.LoraErrorNoNetwork¶: Sollevata su una risposta +ERR_NO_NETWORK quando il modem non si è unito a una rete.

exception lora.LoraErrorRX¶: Sollevata su una risposta +ERR_RX quando si verifica un errore durante la ricezione di un downlink.

exception lora.LoraErrorUnknown¶: Sollevata su una risposta +ERR_UNKNOWN o quando il modem segnala un errore non documentato.

Classi¶

class lora.Lora(uart: machine.UART | None = None, rst_pin: machine.Pin | None = None, boot_pin: machine.Pin | None = None, band: int = BAND_EU868, poll_ms: int = 300000, debug: bool = False)¶

Costruisce un nuovo driver del modem. Il costruttore inizializza (o crea automaticamente) la UART e i pin di reset/boot, esegue un reset hardware del modulo, esegue la sincronizzazione autobaud, riavvia il modulo, ne interroga la versione del firmware e configura la band regionale richiesta.

Parametri:

uart – Istanza machine.UART pre-configurata usata per comunicare con il modem. Se None, il driver apre UART(8, 19200) con framing 8N2 (il valore predefinito del Portenta Vision Shield).
rst_pin – Istanza machine.Pin che pilota la linea di reset del modem. Se None, "PC6" viene configurato come uscita push-pull.
boot_pin – Istanza machine.Pin che pilota la linea di boot-select del modem. Se None, "PG7" viene configurato come uscita push-pull tirata a livello basso.
band – Banda regionale da configurare. Una delle costanti BAND_*.
poll_ms – Intervallo in millisecondi tra gli uplink vuoti automatici attivati da poll() per mantenere aperta la finestra di downlink.
debug – Quando è True, tutto il traffico UART viene stampato tramite print().

LoraErrors: dict¶: Mappatura dalle stringhe di risposta di errore del modem (es. "+ERR_BUSY") alla corrispondente classe di eccezione. Usata internamente da handle_error().

init_modem() → None¶: Inizializza pigramente self.uart, self.rst_pin e self.boot_pin ai loro valori predefiniti del Portenta Vision Shield se non sono già impostati. Chiamato dal costruttore; normalmente non invocato dal codice utente.

debug_print(data: str) → None¶: Stampa data se debug era abilitato al momento della costruzione, altrimenti non fa nulla.

is_arduino_firmware() → bool¶: Restituisce True se il modem esegue il firmware Arduino MKRWAN ARD-078 (rilevato dalla stringa fw_version memorizzata in cache).

configure_class(_class: str) → None¶

Configura la classe di dispositivo LoRaWAN.

Parametri:: _class – Una tra CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Configura la banda regionale e, sul firmware Arduino con BAND_EU868, abilita il limitatore del duty-cycle ETSI. Restituisce True in caso di successo.

Parametri:: band – Una delle costanti BAND_*.

set_baudrate(baudrate: int) → None¶

Modifica il baud rate della UART del modem (AT+UART).

Parametri:: baudrate – Nuovo baud rate, in bit al secondo.

set_autobaud(timeout: int = 10000) → bool¶

Invia comandi AT vuoti finché il modem non risponde con +OK o finché non trascorrono timeout millisecondi. Restituisce True se la sincronizzazione è riuscita.

Parametri:: timeout – Tempo massimo da dedicare al tentativo, in millisecondi.

get_fw_version() → str¶: Interroga la stringa del dispositivo modem (AT+DEV?) e la versione del firmware (AT+VER?) e le restituisce come un’unica stringa separata da spazi.

get_device_eui() → str¶: Restituisce il Device EUI a 64 bit del modem come stringa esadecimale.

factory_default() → None¶: Ripristina le impostazioni di fabbrica tramite AT+FACNEW.

restart() → None¶: Ri-sincronizza il baud rate, riavvia il modem, rilegge la versione del firmware e riapplica la banda regionale configurata. Solleva LoraError in caso di errore.

set_rf_power(mode: int, power: int) → None¶

Configura lo stadio di uscita RF del modem (AT+RFPOWER).

Parametri:

mode – Una tra RF_MODE_RFO, RF_MODE_PABOOST.
power – Indice di potenza di uscita, in unità specifiche del firmware.

set_port(port: int) → None¶

Configura la porta dell’applicazione LoRaWAN (1..223) usata dalle successive chiamate a send_data().

Parametri:: port – FPort LoRaWAN.

set_public_network(enable: bool) → None¶

Abilita o disabilita la sync word di rete pubblica.

Parametri:: enable – True per la sync word LoRaWAN pubblica, False per quella privata.

sleep(enable: bool) → None¶: Mette il modem in modalità sleep a basso consumo (True) o lo risveglia (False).

format(hexMode: bool) → None¶

Seleziona il formato dei dati usato sulla UART per i byte del payload.

Parametri:: hexMode – True per il formato di payload ASCII-hex, False per il binario grezzo.

set_datarate(dr: int) → None¶

Imposta l’indice del data rate LoRaWAN (AT+DR).

Parametri:: dr – Indice del data rate specifico per regione.

get_datarate() → int¶: Restituisce l’indice corrente del data rate LoRaWAN.

set_adr(adr: bool) → None¶

Abilita o disabilita l’Adaptive Data Rate.

Parametri:: adr – True per abilitare l’ADR, False per disabilitarlo.

get_adr() → int¶: Restituisce l’impostazione corrente dell’ADR (1 se abilitato, 0 altrimenti).

get_devaddr() → str¶: Restituisce il DevAddr a 32 bit corrente come stringa esadecimale.

get_nwk_skey() → str¶: Restituisce la Network Session Key corrente come stringa esadecimale.

get_appskey() → str¶: Restituisce l’Application Session Key corrente come stringa esadecimale.

get_rx2dr() → int¶: Restituisce l’indice del data rate usato per la finestra di ricezione RX2.

set_rx2dr(dr: int) → None¶

Imposta l’indice del data rate usato per la finestra di ricezione RX2.

Parametri:: dr – Indice del data rate specifico per regione.

get_ex2freq() → int¶: Restituisce la frequenza, in Hz, usata per la finestra di ricezione RX2.

set_rx2freq(freq: int) → None¶

Imposta la frequenza usata per la finestra di ricezione RX2.

Parametri:: freq – Frequenza in Hz.

set_fcu(fcu: int) → None¶

Imposta il contatore di frame di uplink (AT+FCU).

Parametri:: fcu – Nuovo valore del contatore di frame di uplink.

get_fcu() → int¶: Restituisce il contatore di frame di uplink corrente.

set_fcd(fcd: int) → None¶

Imposta il contatore di frame di downlink (AT+FCD).

Parametri:: fcd – Nuovo valore del contatore di frame di downlink.

get_fcd() → int¶: Restituisce il contatore di frame di downlink corrente.

change_mode(mode: int) → None¶

Cambia la modalità di attivazione.

Parametri:: mode – Una tra MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Emette un AT+JOIN e attende l’evento di join-accept. Restituisce True se il modem segnala +EVENT=1,1 (join riuscito) entro timeout_ms.

Parametri:: timeout_ms – Tempo massimo di attesa sia per l”+ACK sia per il successivo evento di join, in millisecondi.

get_join_status() → bool¶: Restituisce True se il modem è attualmente unito a una rete.

get_max_size() → int¶: Restituisce la dimensione massima del payload LoRaWAN, in byte, per il data rate corrente. Sul firmware Arduino questa è fissata a 64.

poll() → None¶: Se sono trascorsi più di poll_ms millisecondi dall’ultima chiamata, invia un uplink confermato vuoto per svuotare i downlink in sospeso. Pensato per essere chiamato frequentemente dal loop principale dell’applicazione.

send_data(buff: bytes, confirmed: bool = True) → bool¶

Trasmette un uplink LoRaWAN. Solleva LoraError se buff è più grande di get_max_size().

Parametri:

buff – Byte del payload da trasmettere.
confirmed – Quando è True, invia un uplink confermato (+CTX) e attende un +ACK dal network server. Quando è False, invia un uplink non confermato (+UTX).

Ritorna:

True se il modem ha accettato il pacchetto (e, per gli uplink confermati, la rete lo ha riconosciuto), False altrimenti.

receive_data(timeout: int = 1000) → dict | None¶

Attende un downlink. Restituisce None se non è stato ricevuto alcun evento +RECV entro timeout millisecondi, altrimenti un dizionario {"port": str, "data": str} contenente l’FPort e i byte del payload.

Parametri:: timeout – Tempo massimo di attesa, in millisecondi.

receive(delimiter: str | list | None = None, max_bytes: int | None = None, timeout: int = 1000) → str¶

Lettura UART di basso livello. Legge caratteri dal modem finché non viene trovato un delimitatore, finché non sono stati letti max_bytes caratteri, o finché non trascorrono timeout millisecondi, quindi restituisce la stringa accumulata con eventuali \r finali rimossi.

Parametri:

delimiter – Un singolo carattere da confrontare alla fine del buffer, una stringa di più caratteri da confrontare con l’intero buffer ripulito, oppure una lista di tali stringhe.
max_bytes – Se impostato, restituisce non appena sono stati letti esattamente questi byte.
timeout – Timeout di lettura complessivo, in millisecondi.

available() → int¶: Restituisce il numero di byte attualmente disponibili nel buffer di ricezione UART del modem.

join_OTAA(appEui: str, appKey: str, devEui: str = None, timeout: int = 60000) → bool¶

Commuta il modem in modalità OTAA, programma le chiavi e gli EUI forniti, quindi tenta di unirsi alla rete. Restituisce True se il join è riuscito.

Parametri:

appEui – Application/Join EUI a 64 bit come stringa esadecimale.
appKey – Application Key a 128 bit come stringa esadecimale.
devEui – Device EUI a 64 bit opzionale come stringa esadecimale. Se None, viene usato il Device EUI programmato in fabbrica.
timeout – Timeout del join, in millisecondi.

join_ABP(nwkId: int, devAddr: str, nwkSKey: str, appSKey: str, timeout: int = 60000) → bool¶

Commuta il modem in modalità ABP, programma gli indirizzi e le chiavi forniti, quindi tenta di unirsi. Restituisce il risultato di get_join_status().

Parametri:

nwkId – Identificatore di rete (attualmente ignorato dal firmware).
devAddr – Device Address a 32 bit come stringa esadecimale.
nwkSKey – Network Session Key a 128 bit come stringa esadecimale.
appSKey – Application Session Key a 128 bit come stringa esadecimale.
timeout – Timeout del join, in millisecondi.

handle_error(command: str, data: str) → None¶

Esamina una risposta del modem e solleva la sottoclasse LoraError corrispondente se rappresenta un errore. Non fa nulla per le risposte che non sono errori.

Parametri:

command – Il comando AT (senza il prefisso AT) che ha prodotto data.
data – La stringa di risposta restituita dal modem.

send_command(cmd: str, *args, delimiter: str = '\\r', data: bytes = None, timeout: int = 1000, raise_error: bool = True) → str¶

Costruisce un comando AT a partire da cmd e args, opzionalmente accoda un payload data grezzo, lo trasmette e restituisce la risposta del modem. Per i comandi di query che terminano con ?, viene restituita solo la parte del valore (la sottostringa dopo =).

Parametri:

cmd – Suffisso del comando AT (es. "+JOIN", "+DR="); il prefisso "AT" e il \r finale vengono aggiunti automaticamente.
args – Argomenti aggiuntivi concatenati a cmd dopo la conversione in stringa.
delimiter – Delimitatore inoltrato a receive().
data – Byte grezzi opzionali scritti immediatamente dopo il comando AT (usati per i payload di uplink binari).
timeout – Timeout della risposta, in millisecondi.
raise_error – Quando è True, le risposte di errore vengono convertite in eccezioni LoraError; quando è False, la risposta grezza viene restituita al chiamante.

lora — driver del modem LoRa¶

Costanti¶

Modalità di attivazione¶

Modalità di uscita RF¶

Bande¶

Classi di dispositivo¶

Eccezioni¶

Classi¶

`lora` — driver del modem LoRa¶