`lora` — driver pentru modem LoRa¶

Modulul lora oferă un driver pentru modemul LoRa Murata CMWX1ZZABZ de pe Arduino Portenta Vision Shield. Acesta expune o clasă Lora de nivel înalt care încapsulează setul de comenzi AT folosit de firmware-ul modemului (inclusiv firmware-ul Arduino MKRWAN ARD-078), astfel încât o aplicație să se poată conecta la o rețea LoRaWAN și să trimită/primească pachete.

Exemplu:

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)

Constante¶

Moduri de activare¶

lora.MODE_ABP: int¶: Mod de activare prin personalizare (Activation By Personalization).

lora.MODE_OTAA: int¶: Mod de activare prin aer (Over-The-Air Activation).

Moduri de ieșire RF¶

lora.RF_MODE_RFO: int¶: Folosește ieșirea RF RFO (consum redus) a modemului.

lora.RF_MODE_PABOOST: int¶: Folosește ieșirea RF PA_BOOST (putere mare) a modemului.

Benzi¶

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

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

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

lora.BAND_KR920: int¶: Banda regională KR920 (Coreea 920 MHz).

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

lora.BAND_US915: int¶: Banda regională US915 (Statele Unite 915 MHz).

lora.BAND_US915_HYBRID: int¶: Planul regional US915 hibrid (sub-bandă).

Clase de dispozitive¶

lora.CLASS_A: str¶: Dispozitiv final LoRaWAN de clasă A.

lora.CLASS_B: str¶: Dispozitiv final LoRaWAN de clasă B.

lora.CLASS_C: str¶: Dispozitiv final LoRaWAN de clasă C.

Excepții¶

exception lora.LoraError¶: Excepție de bază generată pentru orice eroare returnată de modem sau de driver.

exception lora.LoraErrorTimeout¶: Generată atunci când modemul nu răspunde în intervalul de timp configurat (tamponul de recepție este gol).

exception lora.LoraErrorParam¶: Generată la un răspuns +ERR_PARAM atunci când o comandă AT a fost emisă cu un parametru invalid.

exception lora.LoraErrorBusy¶: Generată la un răspuns +ERR_BUSY atunci când modemul este ocupat cu procesarea unei comenzi anterioare.

exception lora.LoraErrorOverflow¶: Generată la un răspuns +ERR_PARAM_OVERFLOW atunci când un parametru depășește lungimea maximă permisă.

exception lora.LoraErrorNoNetwork¶: Generată la un răspuns +ERR_NO_NETWORK atunci când modemul nu s-a conectat la o rețea.

exception lora.LoraErrorRX¶: Generată la un răspuns +ERR_RX atunci când apare o eroare în timpul recepției unui downlink.

exception lora.LoraErrorUnknown¶: Generată la un răspuns +ERR_UNKNOWN sau atunci când modemul raportează o eroare nedocumentată.

Clase¶

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)¶

Construiește un nou driver de modem. Constructorul inițializează (sau creează automat) UART-ul și pinii de reset/boot, efectuează un reset hardware al modulului, realizează sincronizarea autobaud, repornește modulul, interoghează versiunea firmware-ului și configurează banda regională band solicitată.

Parametrii:

uart – Instanță machine.UART preconfigurată folosită pentru a comunica cu modemul. Dacă este None, driverul deschide UART(8, 19200) cu cadrare 8N2 (valoarea implicită pentru Portenta Vision Shield).
rst_pin – Instanță machine.Pin care controlează linia de reset a modemului. Dacă este None, "PC6" este configurat ca ieșire push-pull.
boot_pin – Instanță machine.Pin care controlează linia de selecție boot a modemului. Dacă este None, "PG7" este configurat ca ieșire push-pull menținută în starea joasă.
band – Banda regională de configurat. Una dintre constantele BAND_*.
poll_ms – Intervalul în milisecunde dintre uplink-urile goale automate declanșate de poll() pentru a menține deschisă fereastra de downlink.
debug – Când este True, tot traficul UART este afișat prin print().

LoraErrors: dict¶: Mapare de la șirurile de răspuns de eroare ale modemului (de ex. "+ERR_BUSY") la clasa de excepție corespunzătoare. Folosită intern de handle_error().

init_modem() → None¶: Inițializează leneș self.uart, self.rst_pin și self.boot_pin la valorile implicite pentru Portenta Vision Shield dacă nu sunt deja setate. Apelată din constructor; în mod normal nu este invocată de codul utilizatorului.

debug_print(data: str) → None¶: Afișează data dacă debug a fost activat la construire, altfel nu face nimic.

is_arduino_firmware() → bool¶: Returnează True dacă modemul rulează firmware-ul Arduino MKRWAN ARD-078 (detectat din șirul fw_version din cache).

configure_class(_class: str) → None¶

Configurează clasa dispozitivului LoRaWAN.

Parametrii:: _class – Una dintre CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Configurează banda regională și, pe firmware Arduino cu BAND_EU868, activează limitatorul de ciclu de funcționare ETSI. Returnează True în caz de succes.

Parametrii:: band – Una dintre constantele BAND_*.

set_baudrate(baudrate: int) → None¶

Modifică rata baud a UART-ului modemului (AT+UART).

Parametrii:: baudrate – Noua rată baud, în biți pe secundă.

set_autobaud(timeout: int = 10000) → bool¶

Trimite comenzi AT goale până când modemul răspunde cu +OK sau până când trec timeout milisecunde. Returnează True dacă sincronizarea a reușit.

Parametrii:: timeout – Timpul maxim alocat încercării, în milisecunde.

get_fw_version() → str¶: Interoghează șirul de identificare al dispozitivului modem (AT+DEV?) și versiunea firmware-ului (AT+VER?) și le returnează ca un singur șir separat prin spațiu.

get_device_eui() → str¶: Returnează Device EUI pe 64 de biți al modemului ca șir hexazecimal.

factory_default() → None¶: Restabilește valorile implicite din fabrică prin AT+FACNEW.

restart() → None¶: Resincronizează rata baud, repornește modemul, recitește versiunea firmware-ului și reaplică banda regională configurată. Generează LoraError în caz de eșec.

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

Configurează etajul de ieșire RF al modemului (AT+RFPOWER).

Parametrii:

mode – Una dintre RF_MODE_RFO, RF_MODE_PABOOST.
power – Indexul puterii de ieșire, în unități specifice firmware-ului.

set_port(port: int) → None¶

Configurează portul aplicației LoRaWAN (1..223) folosit de apelurile ulterioare send_data().

Parametrii:: port – FPort-ul LoRaWAN.

set_public_network(enable: bool) → None¶

Activează sau dezactivează cuvântul de sincronizare pentru rețeaua publică.

Parametrii:: enable – True pentru cuvântul de sincronizare LoRaWAN public, False pentru cel privat.

sleep(enable: bool) → None¶: Pune modemul în modul de repaus cu consum redus (True) sau îl trezește (False).

format(hexMode: bool) → None¶

Selectează formatul de date folosit pe UART pentru octeții de payload.

Parametrii:: hexMode – True pentru formatul de payload ASCII-hex, False pentru binar brut.

set_datarate(dr: int) → None¶

Setează indexul ratei de date LoRaWAN (AT+DR).

Parametrii:: dr – Indexul ratei de date specific regiunii.

get_datarate() → int¶: Returnează indexul curent al ratei de date LoRaWAN.

set_adr(adr: bool) → None¶

Activează sau dezactivează rata de date adaptivă (Adaptive Data Rate).

Parametrii:: adr – True pentru a activa ADR, False pentru a-l dezactiva.

get_adr() → int¶: Returnează setarea curentă ADR (1 dacă este activată, 0 în caz contrar).

get_devaddr() → str¶: Returnează DevAddr-ul curent pe 32 de biți ca șir hexazecimal.

get_nwk_skey() → str¶: Returnează cheia curentă de sesiune de rețea (Network Session Key) ca șir hexazecimal.

get_appskey() → str¶: Returnează cheia curentă de sesiune de aplicație (Application Session Key) ca șir hexazecimal.

get_rx2dr() → int¶: Returnează indexul ratei de date folosit pentru fereastra de recepție RX2.

set_rx2dr(dr: int) → None¶

Setează indexul ratei de date folosit pentru fereastra de recepție RX2.

Parametrii:: dr – Indexul ratei de date specific regiunii.

get_ex2freq() → int¶: Returnează frecvența, în Hz, folosită pentru fereastra de recepție RX2.

set_rx2freq(freq: int) → None¶

Setează frecvența folosită pentru fereastra de recepție RX2.

Parametrii:: freq – Frecvența în Hz.

set_fcu(fcu: int) → None¶

Setează contorul de cadre de uplink (AT+FCU).

Parametrii:: fcu – Noua valoare a contorului de cadre de uplink.

get_fcu() → int¶: Returnează contorul curent de cadre de uplink.

set_fcd(fcd: int) → None¶

Setează contorul de cadre de downlink (AT+FCD).

Parametrii:: fcd – Noua valoare a contorului de cadre de downlink.

get_fcd() → int¶: Returnează contorul curent de cadre de downlink.

change_mode(mode: int) → None¶

Comută modul de activare.

Parametrii:: mode – Una dintre MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Emite un AT+JOIN și așteaptă evenimentul de acceptare a conectării. Returnează True dacă modemul raportează +EVENT=1,1 (conectare reușită) în intervalul timeout_ms.

Parametrii:: timeout_ms – Timpul maxim de așteptare pentru +ACK și pentru evenimentul de conectare ulterior, în milisecunde.

get_join_status() → bool¶: Returnează True dacă modemul este în prezent conectat la o rețea.

get_max_size() → int¶: Returnează dimensiunea maximă a payload-ului LoRaWAN, în octeți, pentru rata de date curentă. Pe firmware Arduino aceasta este fixată la 64.

poll() → None¶: Dacă au trecut mai mult de poll_ms milisecunde de la ultimul apel, trimite un uplink confirmat gol pentru a goli downlink-urile în așteptare. Destinată apelării frecvente din bucla principală a aplicației.

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

Transmite un uplink LoRaWAN. Generează LoraError dacă buff este mai mare decât get_max_size().

Parametrii:

buff – Octeții de payload de transmis.
confirmed – Când este True, trimite un uplink confirmat (+CTX) și așteaptă un +ACK de la serverul de rețea. Când este False, trimite un uplink neconfirmat (+UTX).

Întoarce:

True dacă modemul a acceptat pachetul (și, pentru uplink-urile confirmate, rețeaua l-a confirmat), False în caz contrar.

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

Așteaptă un downlink. Returnează None dacă niciun eveniment +RECV nu a fost primit în timeout milisecunde, altfel un dicționar {"port": str, "data": str} care conține FPort-ul și octeții de payload.

Parametrii:: timeout – Timpul maxim de așteptare, în milisecunde.

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

Citire UART de nivel scăzut. Citește caractere de la modem până când este găsit un delimitator, până când au fost citite max_bytes caractere sau până când trec timeout milisecunde, apoi returnează șirul acumulat cu orice \r final eliminat.

Parametrii:

delimiter – Fie un singur caracter de potrivit la sfârșitul tamponului, fie un șir cu mai multe caractere de potrivit cu întregul tampon ajustat, fie o listă de astfel de șiruri.
max_bytes – Dacă este setat, returnează imediat ce au fost citiți exact atâția octeți.
timeout – Timpul total de așteptare la citire, în milisecunde.

available() → int¶: Returnează numărul de octeți disponibili în prezent în tamponul de recepție UART al modemului.

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

Comută modemul în modul OTAA, programează cheile și EUI-urile furnizate, apoi încearcă să se conecteze la rețea. Returnează True dacă conectarea a reușit.

Parametrii:

appEui – Application/Join EUI pe 64 de biți ca șir hexazecimal.
appKey – Application Key pe 128 de biți ca șir hexazecimal.
devEui – Device EUI opțional pe 64 de biți ca șir hexazecimal. Dacă este None, se folosește Device EUI programat din fabrică.
timeout – Timpul limită pentru conectare, în milisecunde.

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

Comută modemul în modul ABP, programează adresele și cheile furnizate, apoi încearcă să se conecteze. Returnează rezultatul lui get_join_status().

Parametrii:

nwkId – Identificatorul de rețea (în prezent ignorat de firmware).
devAddr – Device Address pe 32 de biți ca șir hexazecimal.
nwkSKey – Network Session Key pe 128 de biți ca șir hexazecimal.
appSKey – Application Session Key pe 128 de biți ca șir hexazecimal.
timeout – Timpul limită pentru conectare, în milisecunde.

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

Inspectează un răspuns al modemului și generează subclasa LoraError corespunzătoare dacă acesta reprezintă o eroare. Nu face nimic pentru răspunsurile care nu sunt erori.

Parametrii:

command – Comanda AT (fără prefixul AT) care a produs data.
data – Șirul de răspuns returnat de modem.

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

Construiește o comandă AT din cmd și args, opțional adaugă un payload brut data, o transmite și returnează răspunsul modemului. Pentru comenzile de interogare care se termină cu ?, este returnată doar porțiunea de valoare (subșirul de după =).

Parametrii:

cmd – Sufixul comenzii AT (de ex. "+JOIN", "+DR="); prefixul "AT" și \r final sunt adăugate automat.
args – Argumente suplimentare concatenate la cmd după conversia în șir.
delimiter – Delimitatorul transmis mai departe către receive().
data – Octeți bruți opționali scriși imediat după comanda AT (folosiți pentru payload-uri de uplink binare).
timeout – Timpul limită pentru răspuns, în milisecunde.
raise_error – Când este True, răspunsurile de eroare sunt convertite în excepții LoraError; când este False, răspunsul brut este returnat apelantului.

lora — driver pentru modem LoRa¶

Constante¶

Moduri de activare¶

Moduri de ieșire RF¶

Benzi¶

Clase de dispozitive¶

Excepții¶

Clase¶

`lora` — driver pentru modem LoRa¶