`lora` — LoRa-Modemtreiber¶

Das Modul lora stellt einen Treiber für das LoRa-Modem Murata CMWX1ZZABZ auf dem Arduino Portenta Vision Shield bereit. Es bietet eine High-Level-Klasse Lora, die den vom Modem genutzten AT-Befehlssatz kapselt (einschließlich der Arduino-MKRWAN-Firmware ARD-078), sodass eine Anwendung einem LoRaWAN-Netzwerk beitreten und Pakete senden bzw. empfangen kann.

Beispiel:

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)

Konstanten¶

Aktivierungsmodi¶

lora.MODE_ABP: int¶: Activation-By-Personalization-Modus.

lora.MODE_OTAA: int¶: Over-The-Air-Activation-Modus.

RF-Ausgangsmodi¶

lora.RF_MODE_RFO: int¶: Den RFO-Ausgang (niedrige Leistung) des Modems verwenden.

lora.RF_MODE_PABOOST: int¶: Den PA_BOOST-Ausgang (hohe Leistung) des Modems verwenden.

Bänder¶

lora.BAND_AS923: int¶: Regionales Band AS923 (Asien 923 MHz).

lora.BAND_AU915: int¶: Regionales Band AU915 (Australien 915 MHz).

lora.BAND_EU868: int¶: Regionales Band EU868 (Europa 868 MHz).

lora.BAND_KR920: int¶: Regionales Band KR920 (Korea 920 MHz).

lora.BAND_IN865: int¶: Regionales Band IN865 (Indien 865 MHz).

lora.BAND_US915: int¶: Regionales Band US915 (Vereinigte Staaten 915 MHz).

lora.BAND_US915_HYBRID: int¶: Regionaler Plan US915 hybrid (Sub-Band).

Geräteklassen¶

lora.CLASS_A: str¶: LoRaWAN-Endgerät der Klasse A.

lora.CLASS_B: str¶: LoRaWAN-Endgerät der Klasse B.

lora.CLASS_C: str¶: LoRaWAN-Endgerät der Klasse C.

Ausnahmen¶

exception lora.LoraError¶: Basisausnahme, die für jeden vom Modem oder Treiber zurückgegebenen Fehler ausgelöst wird.

exception lora.LoraErrorTimeout¶: Wird ausgelöst, wenn das Modem nicht innerhalb des konfigurierten Timeouts antwortet (der Empfangspuffer ist leer).

exception lora.LoraErrorParam¶: Wird bei einer +ERR_PARAM-Antwort ausgelöst, wenn ein AT-Befehl mit einem ungültigen Parameter abgesetzt wurde.

exception lora.LoraErrorBusy¶: Wird bei einer +ERR_BUSY-Antwort ausgelöst, wenn das Modem mit der Verarbeitung eines vorherigen Befehls beschäftigt ist.

exception lora.LoraErrorOverflow¶: Wird bei einer +ERR_PARAM_OVERFLOW-Antwort ausgelöst, wenn ein Parameter die maximal zulässige Länge überschreitet.

exception lora.LoraErrorNoNetwork¶: Wird bei einer +ERR_NO_NETWORK-Antwort ausgelöst, wenn das Modem keinem Netzwerk beigetreten ist.

exception lora.LoraErrorRX¶: Wird bei einer +ERR_RX-Antwort ausgelöst, wenn beim Empfang eines Downlinks ein Fehler auftritt.

exception lora.LoraErrorUnknown¶: Wird bei einer +ERR_UNKNOWN-Antwort ausgelöst oder wenn das Modem einen undokumentierten Fehler meldet.

Klassen¶

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

Erstellt einen neuen Modemtreiber. Der Konstruktor initialisiert (oder erstellt automatisch) die UART- sowie die Reset-/Boot-Pins, führt einen Hardware-Reset des Moduls durch, synchronisiert die Baudrate (Autobaud), startet das Modul neu, fragt dessen Firmware-Version ab und konfiguriert das angeforderte regionale band.

Parameter:

uart – Vorkonfigurierte machine.UART-Instanz zur Kommunikation mit dem Modem. Wenn None, öffnet der Treiber UART(8, 19200) mit 8N2-Framing (der Standardeinstellung des Portenta Vision Shield).
rst_pin – machine.Pin, der die Reset-Leitung des Modems steuert. Wenn None, wird "PC6" als Push-Pull-Ausgang konfiguriert.
boot_pin – machine.Pin, der die Boot-Select-Leitung des Modems steuert. Wenn None, wird "PG7" als nach Low gezogener Push-Pull-Ausgang konfiguriert.
band – Zu konfigurierendes regionales Band. Eine der BAND_*-Konstanten.
poll_ms – Intervall in Millisekunden zwischen automatischen leeren Uplinks, die von poll() ausgelöst werden, um das Downlink-Fenster offen zu halten.
debug – Wenn True, wird der gesamte UART-Verkehr über print() ausgegeben.

LoraErrors: dict¶: Zuordnung von Fehlerantwort-Strings des Modems (z. B. "+ERR_BUSY") zu der entsprechenden Ausnahmeklasse. Wird intern von handle_error() verwendet.

init_modem() → None¶: Initialisiert self.uart, self.rst_pin und self.boot_pin verzögert auf ihre Portenta-Vision-Shield-Standardwerte, sofern sie noch nicht gesetzt sind. Wird vom Konstruktor aufgerufen; normalerweise nicht durch Benutzercode aufgerufen.

debug_print(data: str) → None¶: Gibt data aus, wenn debug beim Erstellen aktiviert wurde, andernfalls geschieht nichts.

is_arduino_firmware() → bool¶: Gibt True zurück, wenn auf dem Modem die Arduino-MKRWAN-Firmware ARD-078 läuft (erkannt anhand des zwischengespeicherten fw_version-Strings).

configure_class(_class: str) → None¶

Konfiguriert die LoRaWAN-Geräteklasse.

Parameter:: _class – Eines von CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Konfiguriert das regionale Band und aktiviert auf Arduino-Firmware mit BAND_EU868 den ETSI-Duty-Cycle-Begrenzer. Gibt bei Erfolg True zurück.

Parameter:: band – Eine der BAND_*-Konstanten.

set_baudrate(baudrate: int) → None¶

Ändert die UART-Baudrate des Modems (AT+UART).

Parameter:: baudrate – Neue Baudrate in Bit pro Sekunde.

set_autobaud(timeout: int = 10000) → bool¶

Sendet leere AT-Befehle, bis das Modem mit +OK antwortet oder bis timeout Millisekunden verstrichen sind. Gibt True zurück, wenn die Synchronisation erfolgreich war.

Parameter:: timeout – Maximale Zeit für den Versuch, in Millisekunden.

get_fw_version() → str¶: Fragt den Geräte-String des Modems (AT+DEV?) und die Firmware-Version (AT+VER?) ab und gibt sie als einen einzigen, durch Leerzeichen getrennten String zurück.

get_device_eui() → str¶: Gibt die 64-Bit-Device-EUI des Modems als Hex-String zurück.

factory_default() → None¶: Stellt über AT+FACNEW die Werkseinstellungen wieder her.

restart() → None¶: Synchronisiert die Baudrate erneut, startet das Modem neu, liest die Firmware-Version erneut ein und wendet das konfigurierte regionale Band erneut an. Löst bei einem Fehler LoraError aus.

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

Konfiguriert die RF-Ausgangsstufe des Modems (AT+RFPOWER).

Parameter:

mode – Eines von RF_MODE_RFO, RF_MODE_PABOOST.
power – Ausgangsleistungsindex in firmwarespezifischen Einheiten.

set_port(port: int) → None¶

Konfiguriert den LoRaWAN-Anwendungsport (1..223), der von nachfolgenden send_data()-Aufrufen verwendet wird.

Parameter:: port – LoRaWAN-FPort.

set_public_network(enable: bool) → None¶

Aktiviert oder deaktiviert das Public-Network-Sync-Word.

Parameter:: enable – True für das öffentliche LoRaWAN-Sync-Word, False für das private.

sleep(enable: bool) → None¶: Versetzt das Modem in den Low-Power-Schlafmodus (True) oder weckt es auf (False).

format(hexMode: bool) → None¶

Wählt das über UART verwendete Datenformat für Payload-Bytes aus.

Parameter:: hexMode – True für das ASCII-Hex-Payload-Format, False für rohes Binärformat.

set_datarate(dr: int) → None¶

Setzt den LoRaWAN-Datenraten-Index (AT+DR).

Parameter:: dr – Regionsspezifischer Datenraten-Index.

get_datarate() → int¶: Gibt den aktuellen LoRaWAN-Datenraten-Index zurück.

set_adr(adr: bool) → None¶

Aktiviert oder deaktiviert Adaptive Data Rate.

Parameter:: adr – True, um ADR zu aktivieren, False, um es zu deaktivieren.

get_adr() → int¶: Gibt die aktuelle ADR-Einstellung zurück (1 wenn aktiviert, sonst 0).

get_devaddr() → str¶: Gibt die aktuelle 32-Bit-DevAddr als Hex-String zurück.

get_nwk_skey() → str¶: Gibt den aktuellen Network Session Key als Hex-String zurück.

get_appskey() → str¶: Gibt den aktuellen Application Session Key als Hex-String zurück.

get_rx2dr() → int¶: Gibt den für das RX2-Empfangsfenster verwendeten Datenraten-Index zurück.

set_rx2dr(dr: int) → None¶

Setzt den für das RX2-Empfangsfenster verwendeten Datenraten-Index.

Parameter:: dr – Regionsspezifischer Datenraten-Index.

get_ex2freq() → int¶: Gibt die für das RX2-Empfangsfenster verwendete Frequenz in Hz zurück.

set_rx2freq(freq: int) → None¶

Setzt die für das RX2-Empfangsfenster verwendete Frequenz.

Parameter:: freq – Frequenz in Hz.

set_fcu(fcu: int) → None¶

Setzt den Uplink-Frame-Zähler (AT+FCU).

Parameter:: fcu – Neuer Wert für den Uplink-Frame-Zähler.

get_fcu() → int¶: Gibt den aktuellen Uplink-Frame-Zähler zurück.

set_fcd(fcd: int) → None¶

Setzt den Downlink-Frame-Zähler (AT+FCD).

Parameter:: fcd – Neuer Wert für den Downlink-Frame-Zähler.

get_fcd() → int¶: Gibt den aktuellen Downlink-Frame-Zähler zurück.

change_mode(mode: int) → None¶

Wechselt den Aktivierungsmodus.

Parameter:: mode – Eines von MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Setzt ein AT+JOIN ab und wartet auf das Join-Accept-Ereignis. Gibt True zurück, wenn das Modem innerhalb von timeout_ms +EVENT=1,1 meldet (Join erfolgreich).

Parameter:: timeout_ms – Maximale Wartezeit sowohl auf das +ACK als auch auf das nachfolgende Join-Ereignis, in Millisekunden.

get_join_status() → bool¶: Gibt True zurück, wenn das Modem aktuell einem Netzwerk beigetreten ist.

get_max_size() → int¶: Gibt die maximale LoRaWAN-Payload-Größe in Bytes für die aktuelle Datenrate zurück. Auf Arduino-Firmware ist dieser Wert fest auf 64 gesetzt.

poll() → None¶: Wenn seit dem letzten Aufruf mehr als poll_ms Millisekunden vergangen sind, wird ein leerer bestätigter Uplink gesendet, um ausstehende Downlinks abzurufen. Vorgesehen für den häufigen Aufruf aus der Hauptschleife der Anwendung.

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

Sendet einen LoRaWAN-Uplink. Löst LoraError aus, wenn buff größer ist als get_max_size().

Parameter:

buff – Zu sendende Payload-Bytes.
confirmed – Wenn True, wird ein bestätigter Uplink (+CTX) gesendet und auf ein +ACK des Netzwerkservers gewartet. Wenn False, wird ein unbestätigter Uplink (+UTX) gesendet.

Rückgabe:

True, wenn das Modem das Paket akzeptiert hat (und es bei bestätigten Uplinks vom Netzwerk quittiert wurde), andernfalls False.

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

Wartet auf einen Downlink. Gibt None zurück, wenn innerhalb von timeout Millisekunden kein +RECV-Ereignis empfangen wurde, andernfalls ein Dict {"port": str, "data": str}, das den FPort und die Payload-Bytes enthält.

Parameter:: timeout – Maximale Wartezeit in Millisekunden.

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

Low-Level-UART-Lesevorgang. Liest Zeichen vom Modem, bis ein Trennzeichen erkannt wird, max_bytes Zeichen gelesen wurden oder timeout Millisekunden verstrichen sind, und gibt dann den angesammelten String zurück, wobei ein abschließendes \r entfernt wird.

Parameter:

delimiter – Entweder ein einzelnes am Ende des Puffers zu erkennendes Zeichen, ein mehrzeichiger String, der mit dem gesamten getrimmten Puffer verglichen wird, oder eine Liste solcher Strings.
max_bytes – Wenn gesetzt, wird zurückgekehrt, sobald genau diese Anzahl an Bytes gelesen wurde.
timeout – Gesamtes Lese-Timeout in Millisekunden.

available() → int¶: Gibt die Anzahl der derzeit im UART-Empfangspuffer des Modems verfügbaren Bytes zurück.

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

Schaltet das Modem in den OTAA-Modus, programmiert die angegebenen Schlüssel und EUIs und versucht dann, dem Netzwerk beizutreten. Gibt True zurück, wenn der Join erfolgreich war.

Parameter:

appEui – 64-Bit-Application-/Join-EUI als Hex-String.
appKey – 128-Bit-Application-Key als Hex-String.
devEui – Optionale 64-Bit-Device-EUI als Hex-String. Wenn None, wird die werkseitig programmierte Device-EUI verwendet.
timeout – Join-Timeout in Millisekunden.

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

Schaltet das Modem in den ABP-Modus, programmiert die angegebenen Adressen und Schlüssel und versucht dann, beizutreten. Gibt das Ergebnis von get_join_status() zurück.

Parameter:

nwkId – Netzwerkkennung (wird derzeit von der Firmware ignoriert).
devAddr – 32-Bit-Geräteadresse als Hex-String.
nwkSKey – 128-Bit-Network-Session-Key als Hex-String.
appSKey – 128-Bit-Application-Session-Key als Hex-String.
timeout – Join-Timeout in Millisekunden.

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

Untersucht eine Modemantwort und löst die passende LoraError-Unterklasse aus, wenn sie einen Fehler darstellt. Bei Nicht-Fehler-Antworten geschieht nichts.

Parameter:

command – Der AT-Befehl (ohne das AT-Präfix), der data erzeugt hat.
data – Der vom Modem zurückgegebene Antwort-String.

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

Erstellt einen AT-Befehl aus cmd und args, hängt optional eine rohe data-Payload an, sendet ihn und gibt die Antwort des Modems zurück. Bei Abfragebefehlen, die auf ? enden, wird nur der Werteteil (der Teilstring nach =) zurückgegeben.

Parameter:

cmd – AT-Befehlssuffix (z. B. "+JOIN", "+DR="); das "AT"-Präfix und das abschließende \r werden automatisch hinzugefügt.
args – Zusätzliche Argumente, die nach der String-Konvertierung an cmd angehängt werden.
delimiter – An receive() weitergereichtes Trennzeichen.
data – Optionale rohe Bytes, die unmittelbar nach dem AT-Befehl geschrieben werden (verwendet für binäre Uplink-Payloads).
timeout – Antwort-Timeout in Millisekunden.
raise_error – Wenn True, werden Fehlerantworten in LoraError-Ausnahmen umgewandelt; wenn False, wird die rohe Antwort an den Aufrufer zurückgegeben.

lora — LoRa-Modemtreiber¶

Konstanten¶

Aktivierungsmodi¶

RF-Ausgangsmodi¶

Bänder¶

Geräteklassen¶

Ausnahmen¶

Klassen¶

`lora` — LoRa-Modemtreiber¶