lora — sterownik modemu LoRa#

Moduł lora udostępnia sterownik modemu LoRa Murata CMWX1ZZABZ na płytce Arduino Portenta Vision Shield. Udostępnia on wysokopoziomową klasę Lora, która opakowuje zestaw poleceń AT używany przez oprogramowanie układowe modemu (w tym oprogramowanie układowe Arduino MKRWAN ARD-078), dzięki czemu aplikacja może dołączyć do sieci LoRaWAN oraz wysyłać i odbierać pakiety.

Przykład:

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)

Stałe#

Tryby aktywacji#

lora.MODE_ABP: int#

Tryb Activation By Personalization.

lora.MODE_OTAA: int#

Tryb Over-The-Air Activation.

Tryby wyjścia RF#

lora.RF_MODE_RFO: int#

Użyj wyjścia RF modemu RFO (niskiej mocy).

lora.RF_MODE_PABOOST: int#

Użyj wyjścia RF modemu PA_BOOST (wysokiej mocy).

Pasma#

lora.BAND_AS923: int#

Pasmo regionalne AS923 (Azja 923 MHz).

lora.BAND_AU915: int#

Pasmo regionalne AU915 (Australia 915 MHz).

lora.BAND_EU868: int#

Pasmo regionalne EU868 (Europa 868 MHz).

lora.BAND_KR920: int#

Pasmo regionalne KR920 (Korea 920 MHz).

lora.BAND_IN865: int#

Pasmo regionalne IN865 (Indie 865 MHz).

lora.BAND_US915: int#

Pasmo regionalne US915 (Stany Zjednoczone 915 MHz).

lora.BAND_US915_HYBRID: int#

Plan regionalny hybrydowy US915 (podpasmo).

Klasy urządzeń#

lora.CLASS_A: str#

Urządzenie końcowe LoRaWAN klasy A.

lora.CLASS_B: str#

Urządzenie końcowe LoRaWAN klasy B.

lora.CLASS_C: str#

Urządzenie końcowe LoRaWAN klasy C.

Wyjątki#

exception lora.LoraError#

Bazowy wyjątek zgłaszany dla dowolnego błędu zwróconego przez modem lub sterownik.

exception lora.LoraErrorTimeout#

Zgłaszany, gdy modem nie odpowie w skonfigurowanym czasie oczekiwania (bufor odbiorczy jest pusty).

exception lora.LoraErrorParam#

Zgłaszany przy odpowiedzi +ERR_PARAM, gdy polecenie AT zostało wydane z nieprawidłowym parametrem.

exception lora.LoraErrorBusy#

Zgłaszany przy odpowiedzi +ERR_BUSY, gdy modem jest zajęty przetwarzaniem poprzedniego polecenia.

exception lora.LoraErrorOverflow#

Zgłaszany przy odpowiedzi +ERR_PARAM_OVERFLOW, gdy parametr przekracza maksymalną dozwoloną długość.

exception lora.LoraErrorNoNetwork#

Zgłaszany przy odpowiedzi +ERR_NO_NETWORK, gdy modem nie dołączył do sieci.

exception lora.LoraErrorRX#

Zgłaszany przy odpowiedzi +ERR_RX, gdy podczas odbierania pakietu downlink wystąpi błąd.

exception lora.LoraErrorUnknown#

Zgłaszany przy odpowiedzi +ERR_UNKNOWN lub gdy modem zgłosi nieudokumentowany błąd.

Klasy#

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

Tworzy nowy sterownik modemu. Konstruktor inicjalizuje (lub automatycznie tworzy) UART oraz piny reset/boot, wykonuje sprzętowy reset modułu, przeprowadza synchronizację autobaud, ponownie uruchamia moduł, odpytuje wersję jego oprogramowania układowego i konfiguruje żądane pasmo regionalne band.

Parametry:

  • uart – Wstępnie skonfigurowana instancja machine.UART używana do komunikacji z modemem. Jeśli None, sterownik otwiera UART(8, 19200) z ramkowaniem 8N2 (domyślnym dla Portenta Vision Shield).

  • rst_pin – machine.Pin sterujący linią reset modemu. Jeśli None, jako wyjście push-pull konfigurowany jest "PC6".

  • boot_pin – machine.Pin sterujący linią boot-select modemu. Jeśli None, jako wyjście push-pull podciągnięte do stanu niskiego konfigurowany jest "PG7".

  • band – Pasmo regionalne do skonfigurowania. Jedna ze stałych BAND_*.

  • poll_ms – Odstęp w milisekundach pomiędzy automatycznymi pustymi uplinkami wyzwalanymi przez poll() w celu utrzymania otwartego okna downlink.

  • debug – Gdy True, cały ruch UART jest wypisywany za pomocą print().

LoraErrors: dict#

Mapowanie z łańcuchów odpowiedzi błędów modemu (np. "+ERR_BUSY") na odpowiadające im klasy wyjątków. Używane wewnętrznie przez handle_error().

init_modem() → None#

Leniwie inicjalizuje self.uart, self.rst_pin i self.boot_pin do ich wartości domyślnych dla Portenta Vision Shield, jeśli nie zostały jeszcze ustawione. Wywoływane z konstruktora; zwykle nie jest wywoływane przez kod użytkownika.

debug_print(data: str) → None#

Wypisuje data, jeśli przy tworzeniu obiektu włączono debug, w przeciwnym razie nie robi nic.

is_arduino_firmware() → bool#

Zwraca True, jeśli modem działa na oprogramowaniu układowym Arduino MKRWAN ARD-078 (wykryte na podstawie zbuforowanego łańcucha fw_version).

configure_class(_class: str) → None#

Konfiguruje klasę urządzenia LoRaWAN.

Parametry:

_class – Jedna z wartości CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool#

Konfiguruje pasmo regionalne oraz, na oprogramowaniu układowym Arduino z BAND_EU868, włącza ogranicznik cyklu pracy ETSI. Zwraca True w przypadku powodzenia.

Parametry:

band – Jedna ze stałych BAND_*.

set_baudrate(baudrate: int) → None#

Zmienia szybkość transmisji (baud) UART modemu (AT+UART).

Parametry:

baudrate – Nowa szybkość transmisji (baud), w bitach na sekundę.

set_autobaud(timeout: int = 10000) → bool#

Wysyła puste polecenia AT, aż modem odpowie +OK lub upłynie timeout milisekund. Zwraca True, jeśli synchronizacja się powiodła.

Parametry:

timeout – Maksymalny czas przeznaczony na próby, w milisekundach.

get_fw_version() → str#

Odpytuje łańcuch urządzenia modemu (AT+DEV?) oraz wersję oprogramowania układowego (AT+VER?) i zwraca je jako pojedynczy łańcuch rozdzielony spacjami.

get_device_eui() → str#

Zwraca 64-bitowy Device EUI modemu jako łańcuch szesnastkowy.

factory_default() → None#

Przywraca ustawienia fabryczne za pomocą AT+FACNEW.

restart() → None#

Ponownie synchronizuje szybkość transmisji (baud), uruchamia ponownie modem, ponownie odczytuje wersję oprogramowania układowego i ponownie stosuje skonfigurowane pasmo regionalne. Zgłasza LoraError w przypadku niepowodzenia.

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

Konfiguruje stopień wyjściowy RF modemu (AT+RFPOWER).

Parametry:

  • mode – Jedna z wartości RF_MODE_RFO, RF_MODE_PABOOST.

  • power – Indeks mocy wyjściowej, w jednostkach specyficznych dla oprogramowania układowego.

set_port(port: int) → None#

Konfiguruje port aplikacji LoRaWAN (1..223) używany przez kolejne wywołania send_data().

Parametry:

port – FPort LoRaWAN.

set_public_network(enable: bool) → None#

Włącza lub wyłącza słowo synchronizacji sieci publicznej.

Parametry:

enable – True dla publicznego słowa synchronizacji LoRaWAN, False dla prywatnego.

sleep(enable: bool) → None#

Wprowadza modem w tryb uśpienia niskiej mocy (True) lub wybudza go (False).

format(hexMode: bool) → None#

Wybiera format danych używany przez UART dla bajtów ładunku.

Parametry:

hexMode – True dla formatu ładunku ASCII-hex, False dla surowego formatu binarnego.

set_datarate(dr: int) → None#

Ustawia indeks szybkości transmisji danych LoRaWAN (AT+DR).

Parametry:

dr – Indeks szybkości transmisji danych specyficzny dla regionu.

get_datarate() → int#

Zwraca bieżący indeks szybkości transmisji danych LoRaWAN.

set_adr(adr: bool) → None#

Włącza lub wyłącza Adaptive Data Rate.

Parametry:

adr – True aby włączyć ADR, False aby je wyłączyć.

get_adr() → int#

Zwraca bieżące ustawienie ADR (1 jeśli włączone, 0 w przeciwnym razie).

get_devaddr() → str#

Zwraca bieżący 32-bitowy DevAddr jako łańcuch szesnastkowy.

get_nwk_skey() → str#

Zwraca bieżący Network Session Key jako łańcuch szesnastkowy.

get_appskey() → str#

Zwraca bieżący Application Session Key jako łańcuch szesnastkowy.

get_rx2dr() → int#

Zwraca indeks szybkości transmisji danych używany dla okna odbiorczego RX2.

set_rx2dr(dr: int) → None#

Ustawia indeks szybkości transmisji danych używany dla okna odbiorczego RX2.

Parametry:

dr – Indeks szybkości transmisji danych specyficzny dla regionu.

get_ex2freq() → int#

Zwraca częstotliwość w Hz używaną dla okna odbiorczego RX2.

set_rx2freq(freq: int) → None#

Ustawia częstotliwość używaną dla okna odbiorczego RX2.

Parametry:

freq – Częstotliwość w Hz.

set_fcu(fcu: int) → None#

Ustawia licznik ramek uplink (AT+FCU).

Parametry:

fcu – Nowa wartość licznika ramek uplink.

get_fcu() → int#

Zwraca bieżący licznik ramek uplink.

set_fcd(fcd: int) → None#

Ustawia licznik ramek downlink (AT+FCD).

Parametry:

fcd – Nowa wartość licznika ramek downlink.

get_fcd() → int#

Zwraca bieżący licznik ramek downlink.

change_mode(mode: int) → None#

Przełącza tryb aktywacji.

Parametry:

mode – Jedna z wartości MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool#

Wydaje polecenie AT+JOIN i czeka na zdarzenie join-accept. Zwraca True, jeśli modem zgłosi +EVENT=1,1 (dołączenie powiodło się) w ciągu timeout_ms.

Parametry:

timeout_ms – Maksymalny czas oczekiwania zarówno na +ACK, jak i na kolejne zdarzenie dołączenia, w milisekundach.

get_join_status() → bool#

Zwraca True, jeśli modem jest aktualnie dołączony do sieci.

get_max_size() → int#

Zwraca maksymalny rozmiar ładunku LoRaWAN, w bajtach, dla bieżącej szybkości transmisji danych. Na oprogramowaniu układowym Arduino jest on ustalony na 64.

poll() → None#

Jeśli od ostatniego wywołania minęło więcej niż poll_ms milisekund, wysyła pusty potwierdzony uplink, aby opróżnić oczekujące pakiety downlink. Przeznaczone do częstego wywoływania z głównej pętli aplikacji.

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

Wysyła uplink LoRaWAN. Zgłasza LoraError, jeśli buff jest większy niż get_max_size().

Parametry:

  • buff – Bajty ładunku do wysłania.

  • confirmed – Gdy True, wysyła potwierdzony uplink (+CTX) i czeka na +ACK z serwera sieci. Gdy False, wysyła niepotwierdzony uplink (+UTX).

Zwraca:

True, jeśli modem zaakceptował pakiet (a w przypadku potwierdzonych uplinków sieć go potwierdziła), False w przeciwnym razie.

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

Czeka na pakiet downlink. Zwraca None, jeśli w ciągu timeout milisekund nie odebrano zdarzenia +RECV, w przeciwnym razie słownik {"port": str, "data": str} zawierający FPort i bajty ładunku.

Parametry:

timeout – Maksymalny czas oczekiwania, w milisekundach.

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

Niskopoziomowy odczyt UART. Odczytuje znaki z modemu, aż zostanie dopasowany ogranicznik, odczytanych zostanie max_bytes znaków lub upłynie timeout milisekund, a następnie zwraca zgromadzony łańcuch z usuniętym końcowym \r.

Parametry:

  • delimiter – Pojedynczy znak do dopasowania na końcu bufora, wieloznakowy łańcuch do dopasowania względem całego przyciętego bufora albo lista takich łańcuchów.

  • max_bytes – Jeśli ustawione, zwraca natychmiast po odczytaniu dokładnie tylu bajtów.

  • timeout – Całkowity limit czasu odczytu, w milisekundach.

available() → int#

Zwraca liczbę bajtów aktualnie dostępnych w buforze odbiorczym UART modemu.

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

Przełącza modem w tryb OTAA, programuje dostarczone klucze i EUI, a następnie próbuje dołączyć do sieci. Zwraca True, jeśli dołączenie się powiodło.

Parametry:

  • appEui – 64-bitowy Application/Join EUI jako łańcuch szesnastkowy.

  • appKey – 128-bitowy Application Key jako łańcuch szesnastkowy.

  • devEui – Opcjonalny 64-bitowy Device EUI jako łańcuch szesnastkowy. Jeśli None, używany jest fabrycznie zaprogramowany Device EUI.

  • timeout – Limit czasu dołączenia, w milisekundach.

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

Przełącza modem w tryb ABP, programuje dostarczone adresy i klucze, a następnie próbuje dołączyć. Zwraca wynik get_join_status().

Parametry:

  • nwkId – Identyfikator sieci (obecnie ignorowany przez oprogramowanie układowe).

  • devAddr – 32-bitowy Device Address jako łańcuch szesnastkowy.

  • nwkSKey – 128-bitowy Network Session Key jako łańcuch szesnastkowy.

  • appSKey – 128-bitowy Application Session Key jako łańcuch szesnastkowy.

  • timeout – Limit czasu dołączenia, w milisekundach.

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

Bada odpowiedź modemu i zgłasza pasującą podklasę LoraError, jeśli reprezentuje ona błąd. Nie robi nic dla odpowiedzi niebędących błędami.

Parametry:

  • command – Polecenie AT (bez prefiksu AT), które wygenerowało data.

  • data – Łańcuch odpowiedzi zwrócony przez modem.

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

Buduje polecenie AT z cmd i args, opcjonalnie dołącza surowy ładunek data, wysyła je i zwraca odpowiedź modemu. W przypadku poleceń zapytań kończących się na ? zwracana jest tylko część z wartością (podłańcuch po =).

Parametry:

  • cmd – Sufiks polecenia AT (np. "+JOIN", "+DR="); prefiks "AT" oraz końcowy \r są dodawane automatycznie.

  • args – Dodatkowe argumenty łączone z cmd po konwersji na łańcuch.

  • delimiter – Ogranicznik przekazywany do receive().

  • data – Opcjonalne surowe bajty zapisywane bezpośrednio po poleceniu AT (używane dla binarnych ładunków uplink).

  • timeout – Limit czasu odpowiedzi, w milisekundach.

  • raise_error – Gdy True, odpowiedzi błędów są konwertowane na wyjątki LoraError; gdy False, surowa odpowiedź jest zwracana do wywołującego.