`lora` — LoRa-modemdriver¶

De lora-module biedt een driver voor de Murata CMWX1ZZABZ LoRa-modem op het Arduino Portenta Vision Shield. Hij stelt een hoogniveau Lora-klasse beschikbaar die de AT-commandoset omsluit die door de modemfirmware wordt gebruikt (waaronder de Arduino MKRWAN ARD-078-firmware), zodat een applicatie zich kan aansluiten op een LoRaWAN-netwerk en pakketten kan verzenden/ontvangen.

Voorbeeld:

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)

Constanten¶

Activeringsmodi¶

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

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

RF-uitgangsmodi¶

lora.RF_MODE_RFO: int¶: Gebruik de RFO-uitgang (laag vermogen) van de modem.

lora.RF_MODE_PABOOST: int¶: Gebruik de PA_BOOST-uitgang (hoog vermogen) van de modem.

Banden¶

lora.BAND_AS923: int¶: Regionale band AS923 (Azië 923 MHz).

lora.BAND_AU915: int¶: Regionale band AU915 (Australië 915 MHz).

lora.BAND_EU868: int¶: Regionale band EU868 (Europa 868 MHz).

lora.BAND_KR920: int¶: Regionale band KR920 (Korea 920 MHz).

lora.BAND_IN865: int¶: Regionale band IN865 (India 865 MHz).

lora.BAND_US915: int¶: Regionale band US915 (Verenigde Staten 915 MHz).

lora.BAND_US915_HYBRID: int¶: Regionaal plan US915 hybride (sub-band).

Apparaatklassen¶

lora.CLASS_A: str¶: LoRaWAN-eindapparaat Klasse A.

lora.CLASS_B: str¶: LoRaWAN-eindapparaat Klasse B.

lora.CLASS_C: str¶: LoRaWAN-eindapparaat Klasse C.

Uitzonderingen¶

exception lora.LoraError¶: Basisuitzondering die wordt opgegooid voor elke fout die door de modem of de driver wordt teruggegeven.

exception lora.LoraErrorTimeout¶: Opgegooid wanneer de modem niet reageert binnen de geconfigureerde timeout (de ontvangstbuffer is leeg).

exception lora.LoraErrorParam¶: Opgegooid bij een +ERR_PARAM-respons wanneer een AT-commando is uitgevoerd met een ongeldige parameter.

exception lora.LoraErrorBusy¶: Opgegooid bij een +ERR_BUSY-respons wanneer de modem bezig is met het verwerken van een vorig commando.

exception lora.LoraErrorOverflow¶: Opgegooid bij een +ERR_PARAM_OVERFLOW-respons wanneer een parameter de maximaal toegestane lengte overschrijdt.

exception lora.LoraErrorNoNetwork¶: Opgegooid bij een +ERR_NO_NETWORK-respons wanneer de modem zich niet bij een netwerk heeft aangesloten.

exception lora.LoraErrorRX¶: Opgegooid bij een +ERR_RX-respons wanneer er een fout optreedt tijdens het ontvangen van een downlink.

exception lora.LoraErrorUnknown¶: Opgegooid bij een +ERR_UNKNOWN-respons of wanneer de modem een ongedocumenteerde fout meldt.

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

Construeert een nieuwe modemdriver. De constructor initialiseert (of maakt automatisch aan) de UART en de reset-/boot-pinnen, voert een hardware-reset van de module uit, voert autobaud-synchronisatie uit, herstart de module, vraagt de firmwareversie op en configureert de gevraagde regionale band.

Parameters:

uart – Vooraf geconfigureerde machine.UART-instantie die wordt gebruikt om met de modem te communiceren. Als None, opent de driver UART(8, 19200) met 8N2-framing (de standaard van het Portenta Vision Shield).
rst_pin – machine.Pin die de resetlijn van de modem aanstuurt. Als None, wordt "PC6" geconfigureerd als push-pull-uitgang.
boot_pin – machine.Pin die de boot-selectlijn van de modem aanstuurt. Als None, wordt "PG7" geconfigureerd als push-pull-uitgang die laag wordt getrokken.
band – De te configureren regionale band. Een van de BAND_*-constanten.
poll_ms – Interval in milliseconden tussen automatische lege uplinks die door poll() worden geactiveerd om het downlink-venster open te houden.
debug – Wanneer True, wordt al het UART-verkeer afgedrukt via print().

LoraErrors: dict¶: Toewijzing van modemfoutresponsstrings (bijv. "+ERR_BUSY") aan de bijbehorende uitzonderingsklasse. Intern gebruikt door handle_error().

init_modem() → None¶: Initialiseert self.uart, self.rst_pin en self.boot_pin lui naar hun standaardwaarden voor het Portenta Vision Shield als ze nog niet zijn ingesteld. Wordt aangeroepen vanuit de constructor; normaal niet aangeroepen door gebruikerscode.

debug_print(data: str) → None¶: Drukt data af als debug was ingeschakeld tijdens het construeren, en doet anders niets.

is_arduino_firmware() → bool¶: Geeft True terug als de modem de Arduino MKRWAN ARD-078-firmware draait (gedetecteerd vanuit de gecachte fw_version-string).

configure_class(_class: str) → None¶

Configureert de LoRaWAN-apparaatklasse.

Parameters:: _class – Een van CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Configureert de regionale band en schakelt, op Arduino-firmware met BAND_EU868, de ETSI duty-cycle-begrenzer in. Geeft True terug bij succes.

Parameters:: band – Een van de BAND_*-constanten.

set_baudrate(baudrate: int) → None¶

Wijzigt de UART-baudrate van de modem (AT+UART).

Parameters:: baudrate – Nieuwe baudrate, in bits per seconde.

set_autobaud(timeout: int = 10000) → bool¶

Verzendt lege AT-commando’s totdat de modem reageert met +OK of totdat timeout milliseconden zijn verstreken. Geeft True terug als de synchronisatie is gelukt.

Parameters:: timeout – Maximale tijd die aan de poging wordt besteed, in milliseconden.

get_fw_version() → str¶: Vraagt de apparaatstring van de modem op (AT+DEV?) en de firmwareversie (AT+VER?) en geeft deze terug als één string gescheiden door een spatie.

get_device_eui() → str¶: Geeft de 64-bits Device EUI van de modem terug als een hexstring.

factory_default() → None¶: Herstelt de fabrieksinstellingen via AT+FACNEW.

restart() → None¶: Hersynchroniseert de baudrate, herstart de modem, leest de firmwareversie opnieuw uit en past de geconfigureerde regionale band opnieuw toe. Gooit LoraError op bij mislukking.

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

Configureert de RF-uitgangstrap van de modem (AT+RFPOWER).

Parameters:

mode – Een van RF_MODE_RFO, RF_MODE_PABOOST.
power – Index voor het uitgangsvermogen, in firmwarespecifieke eenheden.

set_port(port: int) → None¶

Configureert de LoRaWAN-applicatiepoort (1..223) die door volgende send_data()-aanroepen wordt gebruikt.

Parameters:: port – LoRaWAN FPort.

set_public_network(enable: bool) → None¶

Schakelt het sync-woord voor het publieke netwerk in of uit.

Parameters:: enable – True voor het publieke LoRaWAN-sync-woord, False voor het privé sync-woord.

sleep(enable: bool) → None¶: Zet de modem in energiezuinige slaapstand (True) of wekt hem op (False).

format(hexMode: bool) → None¶

Selecteert het dataformaat dat over de UART wordt gebruikt voor payloadbytes.

Parameters:: hexMode – True voor het ASCII-hex-payloadformaat, False voor ruwe binaire data.

set_datarate(dr: int) → None¶

Stelt de LoRaWAN-datasnelheidindex in (AT+DR).

Parameters:: dr – Regiospecifieke datasnelheidindex.

get_datarate() → int¶: Geeft de huidige LoRaWAN-datasnelheidindex terug.

set_adr(adr: bool) → None¶

Schakelt Adaptive Data Rate in of uit.

Parameters:: adr – True om ADR in te schakelen, False om het uit te schakelen.

get_adr() → int¶: Geeft de huidige ADR-instelling terug (1 indien ingeschakeld, anders 0).

get_devaddr() → str¶: Geeft het huidige 32-bits DevAddr terug als een hexstring.

get_nwk_skey() → str¶: Geeft de huidige Network Session Key terug als een hexstring.

get_appskey() → str¶: Geeft de huidige Application Session Key terug als een hexstring.

get_rx2dr() → int¶: Geeft de datasnelheidindex terug die voor het RX2-ontvangstvenster wordt gebruikt.

set_rx2dr(dr: int) → None¶

Stelt de datasnelheidindex in die voor het RX2-ontvangstvenster wordt gebruikt.

Parameters:: dr – Regiospecifieke datasnelheidindex.

get_ex2freq() → int¶: Geeft de frequentie, in Hz, terug die voor het RX2-ontvangstvenster wordt gebruikt.

set_rx2freq(freq: int) → None¶

Stelt de frequentie in die voor het RX2-ontvangstvenster wordt gebruikt.

Parameters:: freq – Frequentie in Hz.

set_fcu(fcu: int) → None¶

Stelt de uplink-frameteller in (AT+FCU).

Parameters:: fcu – Nieuwe waarde voor de uplink-frameteller.

get_fcu() → int¶: Geeft de huidige uplink-frameteller terug.

set_fcd(fcd: int) → None¶

Stelt de downlink-frameteller in (AT+FCD).

Parameters:: fcd – Nieuwe waarde voor de downlink-frameteller.

get_fcd() → int¶: Geeft de huidige downlink-frameteller terug.

change_mode(mode: int) → None¶

Schakelt de activeringsmodus om.

Parameters:: mode – Een van MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Geeft een AT+JOIN af en wacht op de join-accept-gebeurtenis. Geeft True terug als de modem +EVENT=1,1 meldt (aansluiting geslaagd) binnen timeout_ms.

Parameters:: timeout_ms – Maximale tijd om te wachten op zowel de +ACK als de daaropvolgende join-gebeurtenis, in milliseconden.

get_join_status() → bool¶: Geeft True terug als de modem momenteel is aangesloten op een netwerk.

get_max_size() → int¶: Geeft de maximale LoRaWAN-payloadgrootte, in bytes, terug voor de huidige datasnelheid. Op Arduino-firmware is dit vast ingesteld op 64.

poll() → None¶: Als er meer dan poll_ms milliseconden zijn verstreken sinds de laatste aanroep, verzendt een lege bevestigde uplink om openstaande downlinks door te spoelen. Bedoeld om frequent aangeroepen te worden vanuit de hoofdlus van de applicatie.

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

Verzendt een LoRaWAN-uplink. Gooit LoraError op als buff groter is dan get_max_size().

Parameters:

buff – Te verzenden payloadbytes.
confirmed – Wanneer True, verzendt een bevestigde uplink (+CTX) en wacht op een +ACK van de netwerkserver. Wanneer False, verzendt een onbevestigde uplink (+UTX).

Geeft terug:

True als de modem het pakket heeft geaccepteerd (en, voor bevestigde uplinks, het netwerk het heeft bevestigd), anders False.

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

Wacht op een downlink. Geeft None terug als er binnen timeout milliseconden geen +RECV-gebeurtenis is ontvangen, anders een dict {"port": str, "data": str} met de FPort en de payloadbytes.

Parameters:: timeout – Maximale tijd om te wachten, in milliseconden.

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

Laagniveau UART-lezing. Leest tekens van de modem totdat een scheidingsteken overeenkomt, max_bytes tekens zijn gelezen, of timeout milliseconden zijn verstreken, en geeft dan de opgebouwde string terug met een eventuele afsluitende \r verwijderd.

Parameters:

delimiter – Ofwel een enkel teken dat aan het einde van de buffer moet worden gematcht, een string van meerdere tekens die tegen de volledige getrimde buffer wordt gematcht, of een lijst van zulke strings.
max_bytes – Indien ingesteld, geeft terug zodra exact dit aantal bytes is gelezen.
timeout – Algehele lees-timeout, in milliseconden.

available() → int¶: Geeft het aantal bytes terug dat momenteel beschikbaar is in de UART-ontvangstbuffer van de modem.

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

Schakelt de modem naar OTAA-modus, programmeert de opgegeven sleutels en EUI’s, en probeert vervolgens zich bij het netwerk aan te sluiten. Geeft True terug als de aansluiting is gelukt.

Parameters:

appEui – 64-bits Application/Join EUI als een hexstring.
appKey – 128-bits Application Key als een hexstring.
devEui – Optionele 64-bits Device EUI als een hexstring. Als None, wordt de in de fabriek geprogrammeerde Device EUI gebruikt.
timeout – Join-timeout, in milliseconden.

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

Schakelt de modem naar ABP-modus, programmeert de opgegeven adressen en sleutels, en probeert vervolgens zich aan te sluiten. Geeft het resultaat van get_join_status() terug.

Parameters:

nwkId – Netwerkidentifier (momenteel genegeerd door de firmware).
devAddr – 32-bits Device Address als een hexstring.
nwkSKey – 128-bits Network Session Key als een hexstring.
appSKey – 128-bits Application Session Key als een hexstring.
timeout – Join-timeout, in milliseconden.

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

Inspecteert een modemrespons en gooit de bijbehorende LoraError-subklasse op als deze een fout vertegenwoordigt. Doet niets voor niet-foutresponsen.

Parameters:

command – Het AT-commando (zonder het AT-voorvoegsel) dat data heeft geproduceerd.
data – De responsstring die door de modem is teruggegeven.

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

Bouwt een AT-commando op uit cmd en args, voegt optioneel een ruwe data-payload toe, verzendt het, en geeft de respons van de modem terug. Voor query-commando’s die eindigen op ? wordt alleen het waardegedeelte teruggegeven (de substring na =).

Parameters:

cmd – AT-commandosuffix (bijv. "+JOIN", "+DR="); het "AT"-voorvoegsel en de afsluitende \r worden automatisch toegevoegd.
args – Aanvullende argumenten die na stringconversie aan cmd worden geconcateneerd.
delimiter – Scheidingsteken doorgegeven aan receive().
data – Optionele ruwe bytes die direct na het AT-commando worden geschreven (gebruikt voor binaire uplink-payloads).
timeout – Respons-timeout, in milliseconden.
raise_error – Wanneer True, worden foutresponsen omgezet in LoraError-uitzonderingen; wanneer False, wordt de ruwe respons aan de aanroeper teruggegeven.

lora — LoRa-modemdriver¶

Constanten¶

Activeringsmodi¶

RF-uitgangsmodi¶

Banden¶

Apparaatklassen¶

Uitzonderingen¶

Klassen¶

`lora` — LoRa-modemdriver¶