`lora` — LoRa-modeemin ajuri¶

lora-moduuli tarjoaa ajurin Arduino Portenta Vision Shield -laajennuksen Murata CMWX1ZZABZ LoRa -modeemille. Se julkaisee korkean tason Lora-luokan, joka kapseloi modeemin laiteohjelmiston käyttämän AT-komentojoukon (mukaan lukien Arduino MKRWAN ARD-078 -laiteohjelmiston), jotta sovellus voi liittyä LoRaWAN-verkkoon sekä lähettää ja vastaanottaa paketteja.

Esimerkki:

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)

Vakiot¶

Aktivointitilat¶

lora.MODE_ABP: int¶: Personointiin perustuva aktivointitila (Activation By Personalization).

lora.MODE_OTAA: int¶: Langaton aktivointitila (Over-The-Air Activation).

RF-lähtötilat¶

lora.RF_MODE_RFO: int¶: Käytä modeemin RFO (matalatehoista) RF-lähtöä.

lora.RF_MODE_PABOOST: int¶: Käytä modeemin PA_BOOST (suuritehoista) RF-lähtöä.

Taajuusalueet¶

lora.BAND_AS923: int¶: AS923 (Aasia 923 MHz) -alueellinen taajuuskaista.

lora.BAND_AU915: int¶: AU915 (Australia 915 MHz) -alueellinen taajuuskaista.

lora.BAND_EU868: int¶: EU868 (Eurooppa 868 MHz) -alueellinen taajuuskaista.

lora.BAND_KR920: int¶: KR920 (Korea 920 MHz) -alueellinen taajuuskaista.

lora.BAND_IN865: int¶: IN865 (Intia 865 MHz) -alueellinen taajuuskaista.

lora.BAND_US915: int¶: US915 (Yhdysvallat 915 MHz) -alueellinen taajuuskaista.

lora.BAND_US915_HYBRID: int¶: US915-hybridi (alikaista) -alueellinen suunnitelma.

Laiteluokat¶

lora.CLASS_A: str¶: LoRaWAN-päätelaite, luokka A.

lora.CLASS_B: str¶: LoRaWAN-päätelaite, luokka B.

lora.CLASS_C: str¶: LoRaWAN-päätelaite, luokka C.

Poikkeukset¶

exception lora.LoraError¶: Peruspoikkeus, joka nostetaan minkä tahansa modeemin tai ajurin palauttaman virheen yhteydessä.

exception lora.LoraErrorTimeout¶: Nostetaan, kun modeemi ei vastaa määritetyn aikakatkaisun kuluessa (vastaanottopuskuri on tyhjä).

exception lora.LoraErrorParam¶: Nostetaan +ERR_PARAM-vastauksen yhteydessä, kun AT-komento annettiin virheellisellä parametrilla.

exception lora.LoraErrorBusy¶: Nostetaan +ERR_BUSY-vastauksen yhteydessä, kun modeemi on varattuna käsittelemään aiempaa komentoa.

exception lora.LoraErrorOverflow¶: Nostetaan +ERR_PARAM_OVERFLOW-vastauksen yhteydessä, kun parametri ylittää suurimman sallitun pituuden.

exception lora.LoraErrorNoNetwork¶: Nostetaan +ERR_NO_NETWORK-vastauksen yhteydessä, kun modeemi ei ole liittynyt verkkoon.

exception lora.LoraErrorRX¶: Nostetaan +ERR_RX-vastauksen yhteydessä, kun alalinkin vastaanotossa tapahtuu virhe.

exception lora.LoraErrorUnknown¶: Nostetaan +ERR_UNKNOWN-vastauksen yhteydessä tai kun modeemi raportoi dokumentoimattoman virheen.

Luokat¶

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

Luo uuden modeemiajurin. Konstruktori alustaa (tai luo automaattisesti) UARTin sekä reset- ja boot-nastat, suorittaa moduulin laitteistonollauksen, tekee automaattisen siirtonopeuden synkronoinnin, käynnistää moduulin uudelleen, kysyy sen laiteohjelmiston version ja määrittää pyydetyn alueellisen band-asetuksen.

Parametrit:

uart – Esimääritetty machine.UART-instanssi, jota käytetään yhteydenpitoon modeemin kanssa. Jos None, ajuri avaa UART(8, 19200) 8N2-kehystyksellä (Portenta Vision Shieldin oletus).
rst_pin – machine.Pin, joka ohjaa modeemin reset-linjaa. Jos None, "PC6" määritetään push-pull-lähdöksi.
boot_pin – machine.Pin, joka ohjaa modeemin boot-valintalinjaa. Jos None, "PG7" määritetään matalalle vedetyksi push-pull-lähdöksi.
band – Määritettävä alueellinen taajuuskaista. Yksi BAND_*-vakioista.
poll_ms – Väli millisekunteina automaattisten tyhjien ylälinkkien välillä, jotka poll() käynnistää alalinkki-ikkunan pitämiseksi auki.
debug – Kun True, kaikki UART-liikenne tulostetaan print()-funktiolla.

LoraErrors: dict¶: Kuvaus modeemin virhevastausmerkkijonoista (esim. "+ERR_BUSY") vastaaviin poikkeusluokkiin. handle_error() käyttää tätä sisäisesti.

init_modem() → None¶: Alustaa laiskasti self.uart, self.rst_pin ja self.boot_pin Portenta Vision Shieldin oletuksiin, jos niitä ei ole jo asetettu. Kutsutaan konstruktorista; käyttäjäkoodi ei normaalisti kutsu tätä.

debug_print(data: str) → None¶: Tulostaa data, jos debug oli käytössä luonnin yhteydessä, muutoin ei tee mitään.

is_arduino_firmware() → bool¶: Palauttaa True, jos modeemissa ajetaan Arduino MKRWAN ARD-078 -laiteohjelmistoa (tunnistetaan välimuistissa olevasta fw_version-merkkijonosta).

configure_class(_class: str) → None¶

Määrittää LoRaWAN-laiteluokan.

Parametrit:: _class – Yksi arvoista CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Määrittää alueellisen taajuuskaistan ja, Arduino-laiteohjelmistossa BAND_EU868-asetuksella, ottaa käyttöön ETSI-pulssisuhderajoittimen. Palauttaa True onnistuessaan.

Parametrit:: band – Yksi BAND_*-vakioista.

set_baudrate(baudrate: int) → None¶

Vaihtaa modeemin UART-siirtonopeuden (AT+UART).

Parametrit:: baudrate – Uusi siirtonopeus bitteinä sekunnissa.

set_autobaud(timeout: int = 10000) → bool¶

Lähettää tyhjiä AT-komentoja, kunnes modeemi vastaa +OK tai kunnes timeout millisekuntia on kulunut. Palauttaa True, jos synkronointi onnistui.

Parametrit:: timeout – Enimmäisaika yrittämiseen millisekunteina.

get_fw_version() → str¶: Kysyy modeemin laitemerkkijonon (AT+DEV?) ja laiteohjelmiston version (AT+VER?) ja palauttaa ne yhtenä välilyönnein eroteltuna merkkijonona.

get_device_eui() → str¶: Palauttaa modeemin 64-bittisen Device EUI:n heksamerkkijonona.

factory_default() → None¶: Palauttaa tehdasasetukset komennolla AT+FACNEW.

restart() → None¶: Synkronoi siirtonopeuden uudelleen, käynnistää modeemin uudelleen, lukee laiteohjelmiston version uudelleen ja ottaa määritetyn alueellisen taajuuskaistan uudelleen käyttöön. Nostaa LoraError-poikkeuksen virhetilanteessa.

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

Määrittää modeemin RF-lähtöasteen (AT+RFPOWER).

Parametrit:

mode – Yksi arvoista RF_MODE_RFO, RF_MODE_PABOOST.
power – Lähtötehoindeksi laiteohjelmistokohtaisina yksikköinä.

set_port(port: int) → None¶

Määrittää LoRaWAN-sovellusportin (1..223), jota seuraavat send_data()-kutsut käyttävät.

Parametrit:: port – LoRaWAN FPort.

set_public_network(enable: bool) → None¶

Ottaa käyttöön tai poistaa käytöstä julkisen verkon synkronointisanan.

Parametrit:: enable – True julkista LoRaWAN-synkronointisanaa varten, False yksityistä varten.

sleep(enable: bool) → None¶: Asettaa modeemin matalatehoiseen lepotilaan (True) tai herättää sen (False).

format(hexMode: bool) → None¶

Valitsee UARTin yli hyötykuormatavuille käytettävän tietomuodon.

Parametrit:: hexMode – True ASCII-heksa-hyötykuormamuotoa varten, False raakaa binääriä varten.

set_datarate(dr: int) → None¶

Asettaa LoRaWAN-tiedonsiirtonopeuden indeksin (AT+DR).

Parametrit:: dr – Aluekohtainen tiedonsiirtonopeuden indeksi.

get_datarate() → int¶: Palauttaa nykyisen LoRaWAN-tiedonsiirtonopeuden indeksin.

set_adr(adr: bool) → None¶

Ottaa käyttöön tai poistaa käytöstä mukautuvan tiedonsiirtonopeuden (Adaptive Data Rate).

Parametrit:: adr – True ottaa ADR:n käyttöön, False poistaa sen käytöstä.

get_adr() → int¶: Palauttaa nykyisen ADR-asetuksen (1 jos käytössä, muutoin 0).

get_devaddr() → str¶: Palauttaa nykyisen 32-bittisen DevAddr:n heksamerkkijonona.

get_nwk_skey() → str¶: Palauttaa nykyisen verkkoistuntoavaimen (Network Session Key) heksamerkkijonona.

get_appskey() → str¶: Palauttaa nykyisen sovellusistuntoavaimen (Application Session Key) heksamerkkijonona.

get_rx2dr() → int¶: Palauttaa RX2-vastaanottoikkunassa käytetyn tiedonsiirtonopeuden indeksin.

set_rx2dr(dr: int) → None¶

Asettaa RX2-vastaanottoikkunassa käytetyn tiedonsiirtonopeuden indeksin.

Parametrit:: dr – Aluekohtainen tiedonsiirtonopeuden indeksi.

get_ex2freq() → int¶: Palauttaa RX2-vastaanottoikkunassa käytetyn taajuuden hertseinä.

set_rx2freq(freq: int) → None¶

Asettaa RX2-vastaanottoikkunassa käytetyn taajuuden.

Parametrit:: freq – Taajuus hertseinä.

set_fcu(fcu: int) → None¶

Asettaa ylälinkin kehyslaskurin (AT+FCU).

Parametrit:: fcu – Uusi ylälinkin kehyslaskurin arvo.

get_fcu() → int¶: Palauttaa nykyisen ylälinkin kehyslaskurin.

set_fcd(fcd: int) → None¶

Asettaa alalinkin kehyslaskurin (AT+FCD).

Parametrit:: fcd – Uusi alalinkin kehyslaskurin arvo.

get_fcd() → int¶: Palauttaa nykyisen alalinkin kehyslaskurin.

change_mode(mode: int) → None¶

Vaihtaa aktivointitilan.

Parametrit:: mode – Yksi arvoista MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Antaa AT+JOIN-komennon ja odottaa join-accept-tapahtumaa. Palauttaa True, jos modeemi raportoi +EVENT=1,1 (liittyminen onnistui) timeout_ms-ajan kuluessa.

Parametrit:: timeout_ms – Enimmäisaika sekä +ACK- että sitä seuraavan liittymistapahtuman odottamiseen millisekunteina.

get_join_status() → bool¶: Palauttaa True, jos modeemi on parhaillaan liittyneenä verkkoon.

get_max_size() → int¶: Palauttaa LoRaWAN-hyötykuorman enimmäiskoon tavuina nykyisellä tiedonsiirtonopeudella. Arduino-laiteohjelmistossa tämä on kiinteästi 64.

poll() → None¶: Jos viimeisestä kutsusta on kulunut yli poll_ms millisekuntia, lähettää tyhjän vahvistetun ylälinkin odottavien alalinkkien tyhjentämiseksi. Tarkoitettu kutsuttavaksi usein sovelluksen pääsilmukasta.

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

Lähettää LoRaWAN-ylälinkin. Nostaa LoraError-poikkeuksen, jos buff on suurempi kuin get_max_size().

Parametrit:

buff – Lähetettävät hyötykuormatavut.
confirmed – Kun True, lähettää vahvistetun ylälinkin (+CTX) ja odottaa verkkopalvelimen +ACK-kuittausta. Kun False, lähettää vahvistamattoman ylälinkin (+UTX).

Palauttaa:

True, jos modeemi hyväksyi paketin (ja vahvistettujen ylälinkkien osalta verkko kuittasi sen), muutoin False.

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

Odottaa alalinkkiä. Palauttaa None, jos +RECV-tapahtumaa ei vastaanotettu timeout millisekunnin kuluessa, muutoin sanakirjan {"port": str, "data": str}, joka sisältää FPortin ja hyötykuormatavut.

Parametrit:: timeout – Enimmäisaika odottamiseen millisekunteina.

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

Matalan tason UART-luku. Lukee merkkejä modeemista, kunnes erotinmerkki löytyy, max_bytes merkkiä on luettu tai timeout millisekuntia on kulunut, ja palauttaa sitten kertyneen merkkijonon, josta mahdollinen lopussa oleva \r on poistettu.

Parametrit:

delimiter – Joko yksittäinen merkki, joka täsmätään puskurin lopussa, monimerkkinen merkkijono, joka täsmätään koko siistittyä puskuria vasten, tai lista tällaisia merkkijonoja.
max_bytes – Jos asetettu, palauttaa heti, kun täsmälleen tämä määrä tavuja on luettu.
timeout – Luvun kokonaisaikakatkaisu millisekunteina.

available() → int¶: Palauttaa modeemin UART-vastaanottopuskurissa parhaillaan käytettävissä olevien tavujen määrän.

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

Vaihtaa modeemin OTAA-tilaan, ohjelmoi annetut avaimet ja EUI:t ja yrittää sitten liittyä verkkoon. Palauttaa True, jos liittyminen onnistui.

Parametrit:

appEui – 64-bittinen Application/Join EUI heksamerkkijonona.
appKey – 128-bittinen sovellusavain (Application Key) heksamerkkijonona.
devEui – Valinnainen 64-bittinen Device EUI heksamerkkijonona. Jos None, käytetään tehdasohjelmoitua Device EUI:tä.
timeout – Liittymisen aikakatkaisu millisekunteina.

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

Vaihtaa modeemin ABP-tilaan, ohjelmoi annetut osoitteet ja avaimet ja yrittää sitten liittyä. Palauttaa get_join_status()-metodin tuloksen.

Parametrit:

nwkId – Verkkotunniste (laiteohjelmisto jättää tällä hetkellä huomiotta).
devAddr – 32-bittinen laiteosoite (Device Address) heksamerkkijonona.
nwkSKey – 128-bittinen verkkoistuntoavain (Network Session Key) heksamerkkijonona.
appSKey – 128-bittinen sovellusistuntoavain (Application Session Key) heksamerkkijonona.
timeout – Liittymisen aikakatkaisu millisekunteina.

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

Tarkastaa modeemin vastauksen ja nostaa vastaavan LoraError-alaluokan, jos vastaus edustaa virhettä. Ei tee mitään virheettömille vastauksille.

Parametrit:

command – AT-komento (ilman AT-etuliitettä), joka tuotti data.
data – Modeemin palauttama vastausmerkkijono.

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

Rakentaa AT-komennon arvoista cmd ja args, liittää valinnaisesti raa’an data-hyötykuorman, lähettää sen ja palauttaa modeemin vastauksen. Kyselykomennoille, jotka päättyvät merkkiin ?, palautetaan vain arvo-osa (=-merkin jälkeinen osamerkkijono).

Parametrit:

cmd – AT-komennon pääte (esim. "+JOIN", "+DR="); "AT"-etuliite ja lopun \r lisätään automaattisesti.
args – cmd-arvoon merkkijonomuunnoksen jälkeen ketjutettavat lisäargumentit.
delimiter – Erotinmerkki, joka välitetään edelleen receive()-metodille.
data – Valinnaiset raakatavut, jotka kirjoitetaan välittömästi AT-komennon jälkeen (käytetään binääristen ylälinkki-hyötykuormien yhteydessä).
timeout – Vastauksen aikakatkaisu millisekunteina.
raise_error – Kun True, virhevastaukset muunnetaan LoraError-poikkeuksiksi; kun False, raaka vastaus palautetaan kutsujalle.

lora — LoRa-modeemin ajuri¶

Vakiot¶

Aktivointitilat¶

RF-lähtötilat¶

Taajuusalueet¶

Laiteluokat¶

Poikkeukset¶

Luokat¶

`lora` — LoRa-modeemin ajuri¶