`lora` — ovladač LoRa modemu¶

Modul lora poskytuje ovladač pro LoRa modem Murata CMWX1ZZABZ na Arduino Portenta Vision Shield. Vystavuje vysokoúrovňovou třídu Lora, která obaluje sadu AT příkazů používaných firmwarem modemu (včetně Arduino MKRWAN firmwaru ARD-078), takže se aplikace může připojit k síti LoRaWAN a odesílat/přijímat pakety.

Příklad:

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)

Konstanty¶

Aktivační režimy¶

lora.MODE_ABP: int¶: Režim Activation By Personalization.

lora.MODE_OTAA: int¶: Režim Over-The-Air Activation.

Režimy RF výstupu¶

lora.RF_MODE_RFO: int¶: Použít RFO (nízkopříkonový) RF výstup modemu.

lora.RF_MODE_PABOOST: int¶: Použít PA_BOOST (vysokopříkonový) RF výstup modemu.

Pásma¶

lora.BAND_AS923: int¶: Regionální pásmo AS923 (Asie 923 MHz).

lora.BAND_AU915: int¶: Regionální pásmo AU915 (Austrálie 915 MHz).

lora.BAND_EU868: int¶: Regionální pásmo EU868 (Evropa 868 MHz).

lora.BAND_KR920: int¶: Regionální pásmo KR920 (Korea 920 MHz).

lora.BAND_IN865: int¶: Regionální pásmo IN865 (Indie 865 MHz).

lora.BAND_US915: int¶: Regionální pásmo US915 (Spojené státy 915 MHz).

lora.BAND_US915_HYBRID: int¶: Regionální plán US915 hybrid (sub-band).

Třídy zařízení¶

lora.CLASS_A: str¶: LoRaWAN koncové zařízení třídy A.

lora.CLASS_B: str¶: LoRaWAN koncové zařízení třídy B.

lora.CLASS_C: str¶: LoRaWAN koncové zařízení třídy C.

Výjimky¶

exception lora.LoraError¶: Základní výjimka vyvolaná při jakékoli chybě vrácené modemem nebo ovladačem.

exception lora.LoraErrorTimeout¶: Vyvolá se, když modem neodpoví v nastaveném časovém limitu (přijímací buffer je prázdný).

exception lora.LoraErrorParam¶: Vyvolá se při odpovědi +ERR_PARAM, když byl AT příkaz zadán s neplatným parametrem.

exception lora.LoraErrorBusy¶: Vyvolá se při odpovědi +ERR_BUSY, když je modem zaneprázdněn zpracováním předchozího příkazu.

exception lora.LoraErrorOverflow¶: Vyvolá se při odpovědi +ERR_PARAM_OVERFLOW, když parametr překročí maximální povolenou délku.

exception lora.LoraErrorNoNetwork¶: Vyvolá se při odpovědi +ERR_NO_NETWORK, když se modem nepřipojil k síti.

exception lora.LoraErrorRX¶: Vyvolá se při odpovědi +ERR_RX, když dojde k chybě při příjmu downlinku.

exception lora.LoraErrorUnknown¶: Vyvolá se při odpovědi +ERR_UNKNOWN nebo když modem hlásí nezdokumentovanou chybu.

Třídy¶

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

Vytvoří nový ovladač modemu. Konstruktor inicializuje (nebo automaticky vytvoří) UART a piny pro reset/boot, provede hardwarový reset modulu, vykoná synchronizaci autobaud, restartuje modul, dotáže se na verzi jeho firmwaru a nakonfiguruje požadované regionální pásmo band.

Parametry:

uart – Předkonfigurovaná instance machine.UART použitá pro komunikaci s modemem. Pokud je None, ovladač otevře UART(8, 19200) s rámcováním 8N2 (výchozí nastavení pro Portenta Vision Shield).
rst_pin – machine.Pin ovládající reset linku modemu. Pokud je None, "PC6" je nakonfigurován jako push-pull výstup.
boot_pin – machine.Pin ovládající boot-select linku modemu. Pokud je None, "PG7" je nakonfigurován jako push-pull výstup stažený k nízké úrovni.
band – Regionální pásmo, které se má nakonfigurovat. Jedna z konstant BAND_*.
poll_ms – Interval v milisekundách mezi automatickými prázdnými uplinky spouštěnými metodou poll() pro udržení otevřeného downlink okna.
debug – Když je True, veškerý UART provoz je vypisován pomocí print().

LoraErrors: dict¶: Mapování z řetězců chybových odpovědí modemu (např. "+ERR_BUSY") na odpovídající třídu výjimky. Interně používáno metodou handle_error().

init_modem() → None¶: Líně inicializuje self.uart, self.rst_pin a self.boot_pin na jejich výchozí hodnoty pro Portenta Vision Shield, pokud ještě nejsou nastaveny. Volá se z konstruktoru; běžně se uživatelským kódem nevolá.

debug_print(data: str) → None¶: Vypíše data, pokud byl při konstrukci povolen debug, jinak neudělá nic.

is_arduino_firmware() → bool¶: Vrátí True, pokud modem běží na Arduino MKRWAN firmwaru ARD-078 (detekováno z uloženého řetězce fw_version).

configure_class(_class: str) → None¶

Nakonfiguruje třídu LoRaWAN zařízení.

Parametry:: _class – Jedna z CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Nakonfiguruje regionální pásmo a na Arduino firmwaru s BAND_EU868 povolí ETSI omezovač pracovního cyklu. Při úspěchu vrátí True.

Parametry:: band – Jedna z konstant BAND_*.

set_baudrate(baudrate: int) → None¶

Změní přenosovou rychlost (baud rate) UART modemu (AT+UART).

Parametry:: baudrate – Nová přenosová rychlost (baud rate) v bitech za sekundu.

set_autobaud(timeout: int = 10000) → bool¶

Odesílá prázdné příkazy AT, dokud modem neodpoví +OK nebo dokud neuplyne timeout milisekund. Vrátí True, pokud synchronizace uspěla.

Parametry:: timeout – Maximální čas strávený pokusy, v milisekundách.

get_fw_version() → str¶: Dotáže se na řetězec zařízení modemu (AT+DEV?) a verzi firmwaru (AT+VER?) a vrátí je jako jediný řetězec oddělený mezerou.

get_device_eui() → str¶: Vrátí 64bitový Device EUI modemu jako hexadecimální řetězec.

factory_default() → None¶: Obnoví tovární nastavení pomocí AT+FACNEW.

restart() → None¶: Znovu synchronizuje přenosovou rychlost (baud rate), restartuje modem, znovu načte verzi firmwaru a znovu aplikuje nakonfigurované regionální pásmo. Při selhání vyvolá LoraError.

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

Nakonfiguruje stupeň RF výstupu modemu (AT+RFPOWER).

Parametry:

mode – Jedna z RF_MODE_RFO, RF_MODE_PABOOST.
power – Index výstupního výkonu, v jednotkách specifických pro firmware.

set_port(port: int) → None¶

Nakonfiguruje LoRaWAN aplikační port (1..223) používaný následnými voláními send_data().

Parametry:: port – LoRaWAN FPort.

set_public_network(enable: bool) → None¶

Povolí nebo zakáže sync word veřejné sítě.

Parametry:: enable – True pro veřejný LoRaWAN sync word, False pro soukromý.

sleep(enable: bool) → None¶: Uvede modem do nízkopříkonového spánku (True) nebo jej probudí (False).

format(hexMode: bool) → None¶

Vybere datový formát používaný přes UART pro bajty payloadu.

Parametry:: hexMode – True pro formát payloadu ASCII-hex, False pro surovou binární podobu.

set_datarate(dr: int) → None¶

Nastaví index LoRaWAN datové rychlosti (AT+DR).

Parametry:: dr – Index datové rychlosti specifický pro region.

get_datarate() → int¶: Vrátí aktuální index LoRaWAN datové rychlosti.

set_adr(adr: bool) → None¶

Povolí nebo zakáže Adaptive Data Rate.

Parametry:: adr – True pro povolení ADR, False pro jeho zakázání.

get_adr() → int¶: Vrátí aktuální nastavení ADR (1 pokud je povoleno, jinak 0).

get_devaddr() → str¶: Vrátí aktuální 32bitový DevAddr jako hexadecimální řetězec.

get_nwk_skey() → str¶: Vrátí aktuální Network Session Key jako hexadecimální řetězec.

get_appskey() → str¶: Vrátí aktuální Application Session Key jako hexadecimální řetězec.

get_rx2dr() → int¶: Vrátí index datové rychlosti používaný pro přijímací okno RX2.

set_rx2dr(dr: int) → None¶

Nastaví index datové rychlosti používaný pro přijímací okno RX2.

Parametry:: dr – Index datové rychlosti specifický pro region.

get_ex2freq() → int¶: Vrátí frekvenci v Hz používanou pro přijímací okno RX2.

set_rx2freq(freq: int) → None¶

Nastaví frekvenci používanou pro přijímací okno RX2.

Parametry:: freq – Frekvence v Hz.

set_fcu(fcu: int) → None¶

Nastaví čítač uplink rámců (AT+FCU).

Parametry:: fcu – Nová hodnota čítače uplink rámců.

get_fcu() → int¶: Vrátí aktuální čítač uplink rámců.

set_fcd(fcd: int) → None¶

Nastaví čítač downlink rámců (AT+FCD).

Parametry:: fcd – Nová hodnota čítače downlink rámců.

get_fcd() → int¶: Vrátí aktuální čítač downlink rámců.

change_mode(mode: int) → None¶

Přepne aktivační režim.

Parametry:: mode – Jedna z MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Vydá AT+JOIN a počká na událost join-accept. Vrátí True, pokud modem nahlásí +EVENT=1,1 (připojení uspělo) během timeout_ms.

Parametry:: timeout_ms – Maximální čas čekání na +ACK i následnou událost připojení, v milisekundách.

get_join_status() → bool¶: Vrátí True, pokud je modem aktuálně připojen k síti.

get_max_size() → int¶: Vrátí maximální velikost LoRaWAN payloadu v bajtech pro aktuální datovou rychlost. Na Arduino firmwaru je pevně nastavena na 64.

poll() → None¶: Pokud od posledního volání uplynulo více než poll_ms milisekund, odešle prázdný potvrzený uplink pro vyprázdnění čekajících downlinků. Určeno k častému volání z hlavní smyčky aplikace.

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

Odešle LoRaWAN uplink. Vyvolá LoraError, pokud je buff větší než get_max_size().

Parametry:

buff – Bajty payloadu k odeslání.
confirmed – Když je True, odešle potvrzený uplink (+CTX) a počká na +ACK od síťového serveru. Když je False, odešle nepotvrzený uplink (+UTX).

Vrací:

True, pokud modem přijal paket (a u potvrzených uplinků jej síť potvrdila), jinak False.

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

Počká na downlink. Vrátí None, pokud během timeout milisekund nebyla přijata žádná událost +RECV, jinak slovník {"port": str, "data": str} obsahující FPort a bajty payloadu.

Parametry:: timeout – Maximální čas čekání, v milisekundách.

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

Nízkoúrovňové čtení UART. Čte znaky z modemu, dokud není shodný oddělovač, dokud není načteno max_bytes znaků nebo dokud neuplyne timeout milisekund, poté vrátí nahromaděný řetězec s odstraněným koncovým \r.

Parametry:

delimiter – Buď jeden znak, který se má shodovat na konci bufferu, víceznakový řetězec, který se má shodovat s celým oříznutým bufferem, nebo seznam takových řetězců.
max_bytes – Pokud je nastaveno, vrátí se, jakmile je načteno přesně tolik bajtů.
timeout – Celkový časový limit čtení, v milisekundách.

available() → int¶: Vrátí počet bajtů aktuálně dostupných v přijímacím bufferu UART modemu.

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

Přepne modem do režimu OTAA, naprogramuje dodané klíče a EUI a poté se pokusí připojit k síti. Vrátí True, pokud připojení uspělo.

Parametry:

appEui – 64bitový Application/Join EUI jako hexadecimální řetězec.
appKey – 128bitový Application Key jako hexadecimální řetězec.
devEui – Volitelný 64bitový Device EUI jako hexadecimální řetězec. Pokud je None, použije se tovární naprogramovaný Device EUI.
timeout – Časový limit připojení, v milisekundách.

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

Přepne modem do režimu ABP, naprogramuje dodané adresy a klíče a poté se pokusí připojit. Vrátí výsledek get_join_status().

Parametry:

nwkId – Identifikátor sítě (aktuálně firmwarem ignorováno).
devAddr – 32bitová adresa zařízení (Device Address) jako hexadecimální řetězec.
nwkSKey – 128bitový Network Session Key jako hexadecimální řetězec.
appSKey – 128bitový Application Session Key jako hexadecimální řetězec.
timeout – Časový limit připojení, v milisekundách.

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

Prozkoumá odpověď modemu a vyvolá odpovídající podtřídu LoraError, pokud představuje chybu. U nechybových odpovědí neudělá nic.

Parametry:

command – AT příkaz (bez prefixu AT), který vyprodukoval data.
data – Řetězec odpovědi vrácený modemem.

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

Sestaví AT příkaz z cmd a args, volitelně připojí surový payload data, odešle jej a vrátí odpověď modemu. U dotazovacích příkazů končících na ? se vrací pouze hodnotová část (podřetězec za =).

Parametry:

cmd – Přípona AT příkazu (např. "+JOIN", "+DR="); prefix "AT" a koncový \r se přidávají automaticky.
args – Další argumenty zřetězené k cmd po převodu na řetězec.
delimiter – Oddělovač předaný metodě receive().
data – Volitelné surové bajty zapsané ihned po AT příkazu (používané pro binární payloady uplinku).
timeout – Časový limit odpovědi, v milisekundách.
raise_error – Když je True, chybové odpovědi se převedou na výjimky LoraError; když je False, surová odpověď se vrátí volajícímu.

lora — ovladač LoRa modemu¶

Konstanty¶

Aktivační režimy¶

Režimy RF výstupu¶

Pásma¶

Třídy zařízení¶

Výjimky¶

Třídy¶

`lora` — ovladač LoRa modemu¶