`lora` — LoRa modem upravljački program¶

Modul lora pruža upravljački program za Murata CMWX1ZZABZ LoRa modem na Arduino Portenta Vision Shield. Izlaže visokorazinsku klasu Lora koja omata skup AT naredbi koje koristi firmware modema (uključujući Arduino MKRWAN ARD-078 firmware) tako da aplikacija može pristupiti LoRaWAN mreži te slati/primati pakete.

Primjer:

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)

Konstante¶

Načini aktivacije¶

lora.MODE_ABP: int¶: Način aktivacije personalizacijom (Activation By Personalization).

lora.MODE_OTAA: int¶: Način aktivacije putem zraka (Over-The-Air Activation).

Načini RF izlaza¶

lora.RF_MODE_RFO: int¶: Koristi RFO (niskoenergetski) RF izlaz modema.

lora.RF_MODE_PABOOST: int¶: Koristi PA_BOOST (visokoenergetski) RF izlaz modema.

Pojasevi¶

lora.BAND_AS923: int¶: AS923 (Azija 923 MHz) regionalni pojas.

lora.BAND_AU915: int¶: AU915 (Australija 915 MHz) regionalni pojas.

lora.BAND_EU868: int¶: EU868 (Europa 868 MHz) regionalni pojas.

lora.BAND_KR920: int¶: KR920 (Koreja 920 MHz) regionalni pojas.

lora.BAND_IN865: int¶: IN865 (Indija 865 MHz) regionalni pojas.

lora.BAND_US915: int¶: US915 (Sjedinjene Američke Države 915 MHz) regionalni pojas.

lora.BAND_US915_HYBRID: int¶: US915 hibridni (pod-pojas) regionalni plan.

Klase uređaja¶

lora.CLASS_A: str¶: LoRaWAN krajnji uređaj klase A.

lora.CLASS_B: str¶: LoRaWAN krajnji uređaj klase B.

lora.CLASS_C: str¶: LoRaWAN krajnji uređaj klase C.

Iznimke¶

exception lora.LoraError¶: Osnovna iznimka koja se podiže za bilo kakvu pogrešku koju vrati modem ili upravljački program.

exception lora.LoraErrorTimeout¶: Podiže se kada modem ne odgovori unutar konfiguriranog vremena čekanja (međuspremnik za primanje je prazan).

exception lora.LoraErrorParam¶: Podiže se kod +ERR_PARAM odgovora kada je AT naredba izdana s nevažećim parametrom.

exception lora.LoraErrorBusy¶: Podiže se kod +ERR_BUSY odgovora kada je modem zauzet obradom prethodne naredbe.

exception lora.LoraErrorOverflow¶: Podiže se kod +ERR_PARAM_OVERFLOW odgovora kada parametar premašuje najveću dopuštenu duljinu.

exception lora.LoraErrorNoNetwork¶: Podiže se kod +ERR_NO_NETWORK odgovora kada se modem nije pridružio mreži.

exception lora.LoraErrorRX¶: Podiže se kod +ERR_RX odgovora kada dođe do pogreške tijekom primanja silazne veze.

exception lora.LoraErrorUnknown¶: Podiže se kod +ERR_UNKNOWN odgovora ili kada modem prijavi nedokumentiranu pogrešku.

Klase¶

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

Konstruira novi upravljački program modema. Konstruktor inicijalizira (ili automatski kreira) UART i pinove za reset/boot, izvodi hardverski reset modula, obavlja autobaud sinkronizaciju, ponovno pokreće modul, ispituje verziju njegovog firmwarea te konfigurira traženi regionalni band.

Parametri:

uart – Unaprijed konfigurirana machine.UART instanca koja se koristi za komunikaciju s modemom. Ako je None, upravljački program otvara UART(8, 19200) s 8N2 okvirima (zadana postavka za Portenta Vision Shield).
rst_pin – machine.Pin koji upravlja reset linijom modema. Ako je None, "PC6" se konfigurira kao push-pull izlaz.
boot_pin – machine.Pin koji upravlja boot-select linijom modema. Ako je None, "PG7" se konfigurira kao push-pull izlaz povučen na nisko.
band – Regionalni pojas koji se konfigurira. Jedna od BAND_* konstanti.
poll_ms – Interval u milisekundama između automatskih praznih uzlaznih veza koje pokreće poll() kako bi prozor silazne veze ostao otvoren.
debug – Kada je True, sav UART promet se ispisuje putem print().

LoraErrors: dict¶: Mapiranje iz nizova odgovora pogreške modema (npr. "+ERR_BUSY") na odgovarajuću klasu iznimke. Koristi se interno od strane handle_error().

init_modem() → None¶: Lijeno inicijalizira self.uart, self.rst_pin i self.boot_pin na njihove zadane vrijednosti za Portenta Vision Shield ako još nisu postavljeni. Poziva se iz konstruktora; obično ga ne poziva korisnički kod.

debug_print(data: str) → None¶: Ispisuje data ako je debug bio omogućen u trenutku konstrukcije, inače ne čini ništa.

is_arduino_firmware() → bool¶: Vraća True ako modem koristi Arduino MKRWAN ARD-078 firmware (otkriveno iz keširanog fw_version niza).

configure_class(_class: str) → None¶

Konfigurira klasu LoRaWAN uređaja.

Parametri:: _class – Jedna od CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Konfigurira regionalni pojas i, na Arduino firmwareu s BAND_EU868, omogućuje ETSI ograničivač radnog ciklusa. Vraća True u slučaju uspjeha.

Parametri:: band – Jedna od BAND_* konstanti.

set_baudrate(baudrate: int) → None¶

Mijenja UART brzinu prijenosa modema (AT+UART).

Parametri:: baudrate – Nova brzina prijenosa, u bitovima u sekundi.

set_autobaud(timeout: int = 10000) → bool¶

Šalje prazne AT naredbe dok modem ne odgovori s +OK ili dok ne prođe timeout milisekundi. Vraća True ako je sinkronizacija uspjela.

Parametri:: timeout – Najveće vrijeme provedeno u pokušaju, u milisekundama.

get_fw_version() → str¶: Ispituje niz uređaja modema (AT+DEV?) i verziju firmwarea (AT+VER?) te ih vraća kao jedan niz razdvojen razmakom.

get_device_eui() → str¶: Vraća 64-bitni Device EUI modema kao heksadecimalni niz.

factory_default() → None¶: Vraća tvorničke zadane postavke putem AT+FACNEW.

restart() → None¶: Ponovno sinkronizira brzinu prijenosa, ponovno pokreće modem, ponovno čita verziju firmwarea i ponovno primjenjuje konfigurirani regionalni pojas. Podiže LoraError u slučaju neuspjeha.

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

Konfigurira RF izlazni stupanj modema (AT+RFPOWER).

Parametri:

mode – Jedna od RF_MODE_RFO, RF_MODE_PABOOST.
power – Indeks izlazne snage, u jedinicama specifičnim za firmware.

set_port(port: int) → None¶

Konfigurira LoRaWAN aplikacijski port (1..223) koji koriste naknadni pozivi send_data().

Parametri:: port – LoRaWAN FPort.

set_public_network(enable: bool) → None¶

Omogućuje ili onemogućuje sync word javne mreže.

Parametri:: enable – True za javni LoRaWAN sync word, False za privatni.

sleep(enable: bool) → None¶: Stavlja modem u niskoenergetsko mirovanje (True) ili ga budi (False).

format(hexMode: bool) → None¶

Odabire format podataka koji se koristi preko UART-a za bajtove korisnog tereta.

Parametri:: hexMode – True za ASCII-hex format korisnog tereta, False za sirovi binarni.

set_datarate(dr: int) → None¶

Postavlja indeks LoRaWAN brzine podataka (AT+DR).

Parametri:: dr – Indeks brzine podataka specifičan za regiju.

get_datarate() → int¶: Vraća trenutni indeks LoRaWAN brzine podataka.

set_adr(adr: bool) → None¶

Omogućuje ili onemogućuje prilagodljivu brzinu podataka (Adaptive Data Rate).

Parametri:: adr – True za omogućavanje ADR-a, False za onemogućavanje.

get_adr() → int¶: Vraća trenutnu ADR postavku (1 ako je omogućeno, 0 inače).

get_devaddr() → str¶: Vraća trenutni 32-bitni DevAddr kao heksadecimalni niz.

get_nwk_skey() → str¶: Vraća trenutni Network Session Key kao heksadecimalni niz.

get_appskey() → str¶: Vraća trenutni Application Session Key kao heksadecimalni niz.

get_rx2dr() → int¶: Vraća indeks brzine podataka koji se koristi za RX2 prozor primanja.

set_rx2dr(dr: int) → None¶

Postavlja indeks brzine podataka koji se koristi za RX2 prozor primanja.

Parametri:: dr – Indeks brzine podataka specifičan za regiju.

get_ex2freq() → int¶: Vraća frekvenciju, u Hz, koja se koristi za RX2 prozor primanja.

set_rx2freq(freq: int) → None¶

Postavlja frekvenciju koja se koristi za RX2 prozor primanja.

Parametri:: freq – Frekvencija u Hz.

set_fcu(fcu: int) → None¶

Postavlja brojač uzlaznih sličica (AT+FCU).

Parametri:: fcu – Nova vrijednost brojača uzlaznih sličica.

get_fcu() → int¶: Vraća trenutni brojač uzlaznih sličica.

set_fcd(fcd: int) → None¶

Postavlja brojač silaznih sličica (AT+FCD).

Parametri:: fcd – Nova vrijednost brojača silaznih sličica.

get_fcd() → int¶: Vraća trenutni brojač silaznih sličica.

change_mode(mode: int) → None¶

Mijenja način aktivacije.

Parametri:: mode – Jedna od MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Izdaje AT+JOIN i čeka na događaj prihvaćanja pridruživanja. Vraća True ako modem prijavi +EVENT=1,1 (pridruživanje uspjelo) unutar timeout_ms.

Parametri:: timeout_ms – Najveće vrijeme čekanja za oba +ACK i naknadni događaj pridruživanja, u milisekundama.

get_join_status() → bool¶: Vraća True ako je modem trenutno pridružen mreži.

get_max_size() → int¶: Vraća najveću veličinu LoRaWAN korisnog tereta, u bajtovima, za trenutnu brzinu podataka. Na Arduino firmwareu to je fiksno 64.

poll() → None¶: Ako je od posljednjeg poziva prošlo više od poll_ms milisekundi, šalje praznu potvrđenu uzlaznu vezu kako bi se ispraznile silazne veze koje čekaju. Namijenjeno za često pozivanje iz glavne petlje aplikacije.

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

Šalje LoRaWAN uzlaznu vezu. Podiže LoraError ako je buff veći od get_max_size().

Parametri:

buff – Bajtovi korisnog tereta za slanje.
confirmed – Kada je True, šalje potvrđenu uzlaznu vezu (+CTX) i čeka na +ACK mrežnog poslužitelja. Kada je False, šalje nepotvrđenu uzlaznu vezu (+UTX).

Vraća:

True ako je modem prihvatio paket (i, za potvrđene uzlazne veze, mreža ga je potvrdila), False inače.

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

Čeka na silaznu vezu. Vraća None ako nijedan +RECV događaj nije primljen unutar timeout milisekundi, inače rječnik {"port": str, "data": str} koji sadrži FPort i bajtove korisnog tereta.

Parametri:: timeout – Najveće vrijeme čekanja, u milisekundama.

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

Niskorazinsko UART čitanje. Čita znakove s modema dok se ne podudari razdjelnik, dok se ne pročita max_bytes znakova, ili dok ne prođe timeout milisekundi, zatim vraća akumulirani niz s uklonjenim svim završnim \r.

Parametri:

delimiter – Ili jedan znak za podudaranje na kraju međuspremnika, niz s više znakova za podudaranje s cijelim obrezanim međuspremnikom, ili popis takvih nizova.
max_bytes – Ako je postavljeno, vraća se čim se pročita točno toliko bajtova.
timeout – Ukupno vrijeme čekanja čitanja, u milisekundama.

available() → int¶: Vraća broj bajtova trenutno dostupnih u UART međuspremniku za primanje modema.

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

Prebacuje modem u OTAA način, programira priložene ključeve i EUI-jeve, zatim pokušava pristupiti mreži. Vraća True ako je pridruživanje uspjelo.

Parametri:

appEui – 64-bitni Application/Join EUI kao heksadecimalni niz.
appKey – 128-bitni Application Key kao heksadecimalni niz.
devEui – Opcionalni 64-bitni Device EUI kao heksadecimalni niz. Ako je None, koristi se tvornički programirani Device EUI.
timeout – Vrijeme čekanja pridruživanja, u milisekundama.

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

Prebacuje modem u ABP način, programira priložene adrese i ključeve, zatim pokušava pristupiti. Vraća rezultat get_join_status().

Parametri:

nwkId – Identifikator mreže (trenutno ga firmware ignorira).
devAddr – 32-bitna adresa uređaja kao heksadecimalni niz.
nwkSKey – 128-bitni Network Session Key kao heksadecimalni niz.
appSKey – 128-bitni Application Session Key kao heksadecimalni niz.
timeout – Vrijeme čekanja pridruživanja, u milisekundama.

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

Pregledava odgovor modema i podiže odgovarajuću LoraError podklasu ako predstavlja pogrešku. Ne čini ništa za odgovore koji nisu pogreške.

Parametri:

command – AT naredba (bez AT prefiksa) koja je proizvela data.
data – Niz odgovora koji vraća modem.

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

Gradi AT naredbu iz cmd i args, opcionalno dodaje sirovi data korisni teret, šalje je i vraća odgovor modema. Za upitne naredbe koje završavaju s ?, vraća se samo dio s vrijednošću (podniz nakon =).

Parametri:

cmd – Sufiks AT naredbe (npr. "+JOIN", "+DR="); "AT" prefiks i završni \r dodaju se automatski.
args – Dodatni argumenti spojeni na cmd nakon pretvorbe u niz.
delimiter – Razdjelnik proslijeđen na receive().
data – Opcionalni sirovi bajtovi zapisani neposredno nakon AT naredbe (koriste se za binarne korisne terete uzlazne veze).
timeout – Vrijeme čekanja odgovora, u milisekundama.
raise_error – Kada je True, odgovori s pogreškom pretvaraju se u LoraError iznimke; kada je False, sirovi odgovor se vraća pozivatelju.

lora — LoRa modem upravljački program¶

Konstante¶

Načini aktivacije¶

Načini RF izlaza¶

Pojasevi¶

Klase uređaja¶

Iznimke¶

Klase¶

`lora` — LoRa modem upravljački program¶