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:
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.