`lora` — LoRa modem meghajtó¶

A lora modul meghajtót biztosít az Arduino Portenta Vision Shield-en található Murata CMWX1ZZABZ LoRa modemhez. Magas szintű Lora osztályt tesz elérhetővé, amely becsomagolja a modem firmware által használt AT parancskészletet (beleértve az Arduino MKRWAN ARD-078 firmware-t), így egy alkalmazás csatlakozhat egy LoRaWAN hálózathoz, és csomagokat küldhet/fogadhat.

Példa:

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)

Konstansok¶

Aktiválási módok¶

lora.MODE_ABP: int¶: Activation By Personalization (személyre szabásos aktiválás) mód.

lora.MODE_OTAA: int¶: Over-The-Air (légi) aktiválási mód.

RF kimeneti módok¶

lora.RF_MODE_RFO: int¶: A modem RFO (alacsony teljesítményű) RF kimenetének használata.

lora.RF_MODE_PABOOST: int¶: A modem PA_BOOST (nagy teljesítményű) RF kimenetének használata.

Sávok¶

lora.BAND_AS923: int¶: AS923 (Ázsia 923 MHz) regionális sáv.

lora.BAND_AU915: int¶: AU915 (Ausztrália 915 MHz) regionális sáv.

lora.BAND_EU868: int¶: EU868 (Európa 868 MHz) regionális sáv.

lora.BAND_KR920: int¶: KR920 (Korea 920 MHz) regionális sáv.

lora.BAND_IN865: int¶: IN865 (India 865 MHz) regionális sáv.

lora.BAND_US915: int¶: US915 (Egyesült Államok 915 MHz) regionális sáv.

lora.BAND_US915_HYBRID: int¶: US915 hibrid (al-sávos) regionális terv.

Eszközosztályok¶

lora.CLASS_A: str¶: LoRaWAN végeszköz Class A.

lora.CLASS_B: str¶: LoRaWAN végeszköz Class B.

lora.CLASS_C: str¶: LoRaWAN végeszköz Class C.

Kivételek¶

exception lora.LoraError¶: Alap kivétel, amelyet a modem vagy a meghajtó által visszaadott bármilyen hiba esetén dob.

exception lora.LoraErrorTimeout¶: Akkor dobja, ha a modem nem válaszol a beállított időkorláton belül (a fogadópuffer üres).

exception lora.LoraErrorParam¶: +ERR_PARAM válasz esetén dobja, amikor egy AT parancsot érvénytelen paraméterrel adtak ki.

exception lora.LoraErrorBusy¶: +ERR_BUSY válasz esetén dobja, amikor a modem egy korábbi parancs feldolgozásával van elfoglalva.

exception lora.LoraErrorOverflow¶: +ERR_PARAM_OVERFLOW válasz esetén dobja, amikor egy paraméter meghaladja a megengedett maximális hosszt.

exception lora.LoraErrorNoNetwork¶: +ERR_NO_NETWORK válasz esetén dobja, amikor a modem nem csatlakozott hálózathoz.

exception lora.LoraErrorRX¶: +ERR_RX válasz esetén dobja, amikor egy downlink fogadása közben hiba történik.

exception lora.LoraErrorUnknown¶: +ERR_UNKNOWN válasz esetén, vagy amikor a modem dokumentálatlan hibát jelez, dobja.

Osztályok¶

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

Új modem meghajtót hoz létre. A konstruktor inicializálja (vagy automatikusan létrehozza) az UART-ot és a reset/boot lábakat, hardveresen visszaállítja a modult, autobaud szinkronizálást hajt végre, újraindítja a modult, lekérdezi a firmware verzióját, és beállítja a kért regionális band sávot.

Paraméterek:

uart – Előre konfigurált machine.UART példány, amelyet a modemmel való kommunikációhoz használ. Ha None, a meghajtó megnyitja az UART(8, 19200)-at 8N2 keretezéssel (a Portenta Vision Shield alapértelmezése).
rst_pin – machine.Pin, amely a modem reset vonalát vezérli. Ha None, a "PC6" push-pull kimenetként kerül beállításra.
boot_pin – machine.Pin, amely a modem boot-select vonalát vezérli. Ha None, a "PG7" alacsonyra húzott push-pull kimenetként kerül beállításra.
band – A beállítandó regionális sáv. A BAND_* konstansok egyike.
poll_ms – Milliszekundumban megadott időköz a poll() által kiváltott automatikus üres uplinkek között, hogy a downlink ablak nyitva maradjon.
debug – Ha True, minden UART forgalom kiírásra kerül a print() segítségével.

LoraErrors: dict¶: Leképezés a modem hibaválasz-szövegeiről (pl. "+ERR_BUSY") a megfelelő kivételosztályra. A handle_error() belsőleg használja.

init_modem() → None¶: Lustán inicializálja a self.uart, self.rst_pin és self.boot_pin értékeket a Portenta Vision Shield alapértelmezéseire, ha még nincsenek beállítva. A konstruktorból hívja meg; normál esetben nem a felhasználói kód hívja.

debug_print(data: str) → None¶: Kiírja a data-t, ha a debug engedélyezve volt a létrehozáskor, egyébként nem tesz semmit.

is_arduino_firmware() → bool¶: True-t ad vissza, ha a modem az Arduino MKRWAN ARD-078 firmware-t futtatja (a gyorsítótárazott fw_version szöveg alapján észlelve).

configure_class(_class: str) → None¶

Beállítja a LoRaWAN eszközosztályt.

Paraméterek:: _class – A CLASS_A, CLASS_B, CLASS_C egyike.

configure_band(band: int) → bool¶

Beállítja a regionális sávot, és Arduino firmware esetén BAND_EU868-cal engedélyezi az ETSI kitöltési tényező korlátozót. Sikeres esetben True-t ad vissza.

Paraméterek:: band – A BAND_* konstansok egyike.

set_baudrate(baudrate: int) → None¶

Megváltoztatja a modem UART átviteli sebességét (AT+UART).

Paraméterek:: baudrate – Az új átviteli sebesség, bit/másodpercben.

set_autobaud(timeout: int = 10000) → bool¶

Üres AT parancsokat küld, amíg a modem +OK választ nem ad, vagy amíg timeout milliszekundum el nem telik. True-t ad vissza, ha a szinkronizálás sikerült.

Paraméterek:: timeout – A próbálkozásra fordítható maximális idő, milliszekundumban.

get_fw_version() → str¶: Lekérdezi a modem eszközszövegét (AT+DEV?) és firmware verzióját (AT+VER?), és egyetlen szóközzel elválasztott szövegként adja vissza őket.

get_device_eui() → str¶: A modem 64 bites Device EUI-jét hexadecimális szövegként adja vissza.

factory_default() → None¶: Visszaállítja a gyári alapértékeket az AT+FACNEW segítségével.

restart() → None¶: Újra szinkronizálja az átviteli sebességet, újraindítja a modemet, újraolvassa a firmware verziót, és újra alkalmazza a beállított regionális sávot. Hiba esetén LoraError kivételt dob.

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

Beállítja a modem RF kimeneti fokozatát (AT+RFPOWER).

Paraméterek:

mode – A RF_MODE_RFO, RF_MODE_PABOOST egyike.
power – Kimeneti teljesítményindex, firmware-specifikus mértékegységben.

set_port(port: int) → None¶

Beállítja a következő send_data() hívások által használt LoRaWAN alkalmazásportot (1..223).

Paraméterek:: port – LoRaWAN FPort.

set_public_network(enable: bool) → None¶

Engedélyezi vagy letiltja a nyilvános hálózat szinkronszavát.

Paraméterek:: enable – True a nyilvános LoRaWAN szinkronszóhoz, False a privát változathoz.

sleep(enable: bool) → None¶: Alacsony fogyasztású alvó állapotba helyezi a modemet (True), vagy felébreszti (False).

format(hexMode: bool) → None¶

Kiválasztja az UART-on a hasznos adatbájtokhoz használt adatformátumot.

Paraméterek:: hexMode – True az ASCII-hex hasznos adat formátumhoz, False a nyers binárishoz.

set_datarate(dr: int) → None¶

Beállítja a LoRaWAN adatsebesség indexét (AT+DR).

Paraméterek:: dr – Régió-specifikus adatsebesség index.

get_datarate() → int¶: Visszaadja az aktuális LoRaWAN adatsebesség indexet.

set_adr(adr: bool) → None¶

Engedélyezi vagy letiltja az Adaptive Data Rate-et.

Paraméterek:: adr – True az ADR engedélyezéséhez, False a letiltásához.

get_adr() → int¶: Visszaadja az aktuális ADR beállítást (1 ha engedélyezve van, egyébként 0).

get_devaddr() → str¶: Visszaadja az aktuális 32 bites DevAddr-t hexadecimális szövegként.

get_nwk_skey() → str¶: Visszaadja az aktuális Network Session Key-t hexadecimális szövegként.

get_appskey() → str¶: Visszaadja az aktuális Application Session Key-t hexadecimális szövegként.

get_rx2dr() → int¶: Visszaadja az RX2 fogadóablakhoz használt adatsebesség indexet.

set_rx2dr(dr: int) → None¶

Beállítja az RX2 fogadóablakhoz használt adatsebesség indexet.

Paraméterek:: dr – Régió-specifikus adatsebesség index.

get_ex2freq() → int¶: Visszaadja az RX2 fogadóablakhoz használt frekvenciát Hz-ben.

set_rx2freq(freq: int) → None¶

Beállítja az RX2 fogadóablakhoz használt frekvenciát.

Paraméterek:: freq – Frekvencia Hz-ben.

set_fcu(fcu: int) → None¶

Beállítja az uplink képkocka-számlálót (AT+FCU).

Paraméterek:: fcu – Az új uplink képkocka-számláló érték.

get_fcu() → int¶: Visszaadja az aktuális uplink képkocka-számlálót.

set_fcd(fcd: int) → None¶

Beállítja a downlink képkocka-számlálót (AT+FCD).

Paraméterek:: fcd – Az új downlink képkocka-számláló érték.

get_fcd() → int¶: Visszaadja az aktuális downlink képkocka-számlálót.

change_mode(mode: int) → None¶

Átváltja az aktiválási módot.

Paraméterek:: mode – A MODE_ABP, MODE_OTAA egyike.

join(timeout_ms: int) → bool¶

Kiad egy AT+JOIN parancsot, és megvárja a join-accept eseményt. True-t ad vissza, ha a modem timeout_ms időn belül +EVENT=1,1 választ jelez (a csatlakozás sikerült).

Paraméterek:: timeout_ms – Az +ACK-ra és az azt követő join eseményre való várakozás maximális ideje, milliszekundumban.

get_join_status() → bool¶: True-t ad vissza, ha a modem jelenleg csatlakozva van egy hálózathoz.

get_max_size() → int¶: Visszaadja az aktuális adatsebességhez tartozó maximális LoRaWAN hasznos adat méretet bájtban. Arduino firmware esetén ez 64-re van rögzítve.

poll() → None¶: Ha az utolsó hívás óta több mint poll_ms milliszekundum telt el, egy üres megerősített uplinket küld a függőben lévő downlinkek kiürítéséhez. A célja, hogy gyakran hívják az alkalmazás fő ciklusából.

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

LoRaWAN uplinket továbbít. LoraError kivételt dob, ha a buff nagyobb, mint get_max_size().

Paraméterek:

buff – Továbbítandó hasznos adatbájtok.
confirmed – Ha True, megerősített uplinket küld (+CTX), és megvárja a hálózati szerver +ACK válaszát. Ha False, nem megerősített uplinket küld (+UTX).

Visszatérési érték:

True, ha a modem elfogadta a csomagot (és megerősített uplinkek esetén a hálózat nyugtázta), egyébként False.

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

Vár egy downlinkre. None-t ad vissza, ha timeout milliszekundumon belül nem érkezett +RECV esemény, egyébként egy {"port": str, "data": str} szótárat, amely az FPort-ot és a hasznos adatbájtokat tartalmazza.

Paraméterek:: timeout – A várakozás maximális ideje, milliszekundumban.

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

Alacsony szintű UART olvasás. Karaktereket olvas a modemből, amíg egy elválasztó nem illeszkedik, max_bytes karaktert be nem olvasott, vagy timeout milliszekundum el nem telik, majd visszaadja a felhalmozott szöveget, levágva a záró \r karaktert.

Paraméterek:

delimiter – Vagy egyetlen karakter, amelyet a puffer végén illeszt, vagy egy többkarakteres szöveg, amelyet a teljes levágott pufferhez illeszt, vagy ilyen szövegek listája.
max_bytes – Ha be van állítva, azonnal visszatér, amint pontosan ennyi bájtot beolvasott.
timeout – Teljes olvasási időkorlát, milliszekundumban.

available() → int¶: Visszaadja a modem UART fogadópufferében jelenleg elérhető bájtok számát.

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

Átkapcsolja a modemet OTAA módba, beprogramozza a megadott kulcsokat és EUI-ket, majd megpróbál csatlakozni a hálózathoz. True-t ad vissza, ha a csatlakozás sikerült.

Paraméterek:

appEui – 64 bites Application/Join EUI hexadecimális szövegként.
appKey – 128 bites Application Key hexadecimális szövegként.
devEui – Opcionális 64 bites Device EUI hexadecimális szövegként. Ha None, a gyárilag beprogramozott Device EUI-t használja.
timeout – Csatlakozási időkorlát, milliszekundumban.

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

Átkapcsolja a modemet ABP módba, beprogramozza a megadott címeket és kulcsokat, majd megpróbál csatlakozni. A get_join_status() eredményét adja vissza.

Paraméterek:

nwkId – Hálózati azonosító (jelenleg a firmware figyelmen kívül hagyja).
devAddr – 32 bites Device Address hexadecimális szövegként.
nwkSKey – 128 bites Network Session Key hexadecimális szövegként.
appSKey – 128 bites Application Session Key hexadecimális szövegként.
timeout – Csatlakozási időkorlát, milliszekundumban.

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

Megvizsgál egy modemválaszt, és a megfelelő LoraError alosztályt dobja, ha az hibát jelez. Nem hibás válaszok esetén nem tesz semmit.

Paraméterek:

command – Az AT parancs (az AT előtag nélkül), amely a data-t létrehozta.
data – A modem által visszaadott válaszszöveg.

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

Felépít egy AT parancsot a cmd és args alapján, opcionálisan hozzáfűz egy nyers data hasznos adatot, elküldi, és visszaadja a modem válaszát. A ?-re végződő lekérdező parancsoknál csak az értékrész (az = utáni alszöveg) kerül visszaadásra.

Paraméterek:

cmd – AT parancs utótag (pl. "+JOIN", "+DR="); az "AT" előtag és a záró \r automatikusan hozzáadódik.
args – A cmd-hez szövegkonverzió után hozzáfűzött további argumentumok.
delimiter – A receive() metódusnak továbbított elválasztó.
data – Opcionális nyers bájtok, amelyeket közvetlenül az AT parancs után ír ki (bináris uplink hasznos adatokhoz használatos).
timeout – Válasz időkorlát, milliszekundumban.
raise_error – Ha True, a hibaválaszok LoraError kivételekké alakulnak; ha False, a nyers válasz kerül visszaadásra a hívónak.

lora — LoRa modem meghajtó¶

Konstansok¶

Aktiválási módok¶

RF kimeneti módok¶

Sávok¶

Eszközosztályok¶

Kivételek¶

Osztályok¶

`lora` — LoRa modem meghajtó¶