lora — pilote de modem LoRa#

Le module lora fournit un pilote pour le modem LoRa Murata CMWX1ZZABZ présent sur l’Arduino Portenta Vision Shield. Il expose une classe haut niveau Lora qui encapsule le jeu de commandes AT utilisé par le micrologiciel du modem (y compris le micrologiciel Arduino MKRWAN ARD-078), permettant ainsi à une application de rejoindre un réseau LoRaWAN et d’envoyer/recevoir des paquets.

Exemple

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)

Constantes#

Modes d’activation#

lora.MODE_ABP: int#

Mode Activation By Personalization.

lora.MODE_OTAA: int#

Mode Over-The-Air Activation.

Modes de sortie RF#

lora.RF_MODE_RFO: int#

Utiliser la sortie RF RFO (basse puissance) du modem.

lora.RF_MODE_PABOOST: int#

Utiliser la sortie RF PA_BOOST (haute puissance) du modem.

Bandes#

lora.BAND_AS923: int#

Bande régionale AS923 (Asie 923 MHz).

lora.BAND_AU915: int#

Bande régionale AU915 (Australie 915 MHz).

lora.BAND_EU868: int#

Bande régionale EU868 (Europe 868 MHz).

lora.BAND_KR920: int#

Bande régionale KR920 (Corée 920 MHz).

lora.BAND_IN865: int#

Bande régionale IN865 (Inde 865 MHz).

lora.BAND_US915: int#

Bande régionale US915 (États-Unis 915 MHz).

lora.BAND_US915_HYBRID: int#

Plan régional hybride US915 (sous-bande).

Classes de périphériques#

lora.CLASS_A: str#

Périphérique terminal LoRaWAN de classe A.

lora.CLASS_B: str#

Périphérique terminal LoRaWAN de classe B.

lora.CLASS_C: str#

Périphérique terminal LoRaWAN de classe C.

Exceptions#

exception lora.LoraError#

Exception de base levée pour toute erreur renvoyée par le modem ou le pilote.

exception lora.LoraErrorTimeout#

Levée lorsque le modem ne répond pas dans le délai configuré (le tampon de réception est vide).

exception lora.LoraErrorParam#

Levée lors d’une réponse +ERR_PARAM lorsqu’une commande AT a été émise avec un paramètre invalide.

exception lora.LoraErrorBusy#

Levée lors d’une réponse +ERR_BUSY lorsque le modem est occupé à traiter une commande précédente.

exception lora.LoraErrorOverflow#

Levée lors d’une réponse +ERR_PARAM_OVERFLOW lorsqu’un paramètre dépasse la longueur maximale autorisée.

exception lora.LoraErrorNoNetwork#

Levée lors d’une réponse +ERR_NO_NETWORK lorsque le modem n’a pas rejoint de réseau.

exception lora.LoraErrorRX#

Levée lors d’une réponse +ERR_RX lorsqu’une erreur survient pendant la réception d’une liaison descendante.

exception lora.LoraErrorUnknown#

Levée lors d’une réponse +ERR_UNKNOWN ou lorsque le modem signale une erreur non documentée.

Classes#

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

Construit un nouveau pilote de modem. Le constructeur initialise (ou crée automatiquement) l’UART et les broches de réinitialisation/démarrage, effectue une réinitialisation matérielle du module, réalise une synchronisation autobaud, redémarre le module, interroge sa version de micrologiciel et configure la band régionale demandée.

Paramètres:

  • uart – Instance machine.UART préconfigurée utilisée pour communiquer avec le modem. Si None, le pilote ouvre UART(8, 19200) avec un cadrage 8N2 (la valeur par défaut du Portenta Vision Shield).

  • rst_pin – machine.Pin pilotant la ligne de réinitialisation du modem. Si None, "PC6" est configurée comme sortie push-pull.

  • boot_pin – machine.Pin pilotant la ligne de sélection de démarrage du modem. Si None, "PG7" est configurée comme sortie push-pull tirée à l’état bas.

  • band – Bande régionale à configurer. L’une des constantes BAND_*.

  • poll_ms – Intervalle en millisecondes entre les liaisons montantes vides automatiques déclenchées par poll() afin de maintenir ouverte la fenêtre de liaison descendante.

  • debug – Lorsque True, tout le trafic UART est affiché via print().

LoraErrors: dict#

Correspondance entre les chaînes de réponse d’erreur du modem (par ex. "+ERR_BUSY") et la classe d’exception correspondante. Utilisée en interne par handle_error().

init_modem() → None#

Initialise paresseusement self.uart, self.rst_pin et self.boot_pin avec leurs valeurs par défaut du Portenta Vision Shield si elles ne sont pas déjà définies. Appelée depuis le constructeur ; n’est normalement pas invoquée par le code utilisateur.

debug_print(data: str) → None#

Affiche data si debug a été activé lors de la construction, sinon ne fait rien.

is_arduino_firmware() → bool#

Renvoie True si le modem exécute le micrologiciel Arduino MKRWAN ARD-078 (détecté à partir de la chaîne fw_version mise en cache).

configure_class(_class: str) → None#

Configure la classe de périphérique LoRaWAN.

Paramètres:

_class – L’une des valeurs CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool#

Configure la bande régionale et, sur micrologiciel Arduino avec BAND_EU868, active le limiteur de rapport cyclique ETSI. Renvoie True en cas de succès.

Paramètres:

band – L’une des constantes BAND_*.

set_baudrate(baudrate: int) → None#

Modifie le débit en bauds de l’UART du modem (AT+UART).

Paramètres:

baudrate – Nouveau débit en bauds, en bits par seconde.

set_autobaud(timeout: int = 10000) → bool#

Envoie des commandes AT vides jusqu’à ce que le modem réponde par +OK ou jusqu’à ce que timeout millisecondes s’écoulent. Renvoie True si la synchronisation a réussi.

Paramètres:

timeout – Temps maximal à consacrer à la tentative, en millisecondes.

get_fw_version() → str#

Interroge la chaîne de périphérique du modem (AT+DEV?) et la version du micrologiciel (AT+VER?) et les renvoie sous la forme d’une seule chaîne séparée par des espaces.

get_device_eui() → str#

Renvoie le Device EUI 64 bits du modem sous forme de chaîne hexadécimale.

factory_default() → None#

Restaure les valeurs d’usine par défaut via AT+FACNEW.

restart() → None#

Resynchronise le débit en bauds, redémarre le modem, relit la version du micrologiciel et réapplique la bande régionale configurée. Lève LoraError en cas d’échec.

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

Configure l’étage de sortie RF du modem (AT+RFPOWER).

Paramètres:

  • mode – L’une des valeurs RF_MODE_RFO, RF_MODE_PABOOST.

  • power – Indice de puissance de sortie, en unités spécifiques au micrologiciel.

set_port(port: int) → None#

Configure le port applicatif LoRaWAN (1..223) utilisé par les appels send_data() ultérieurs.

Paramètres:

port – FPort LoRaWAN.

set_public_network(enable: bool) → None#

Active ou désactive le mot de synchronisation du réseau public.

Paramètres:

enable – True pour le mot de synchronisation LoRaWAN public, False pour le mot privé.

sleep(enable: bool) → None#

Met le modem en veille basse consommation (True) ou le réveille (False).

format(hexMode: bool) → None#

Sélectionne le format de données utilisé sur l’UART pour les octets de charge utile.

Paramètres:

hexMode – True pour un format de charge utile ASCII-hex, False pour du binaire brut.

set_datarate(dr: int) → None#

Définit l’indice de débit de données LoRaWAN (AT+DR).

Paramètres:

dr – Indice de débit de données spécifique à la région.

get_datarate() → int#

Renvoie l’indice de débit de données LoRaWAN actuel.

set_adr(adr: bool) → None#

Active ou désactive l’Adaptive Data Rate.

Paramètres:

adr – True pour activer l’ADR, False pour le désactiver.

get_adr() → int#

Renvoie le réglage ADR actuel (1 si activé, 0 sinon).

get_devaddr() → str#

Renvoie le DevAddr 32 bits actuel sous forme de chaîne hexadécimale.

get_nwk_skey() → str#

Renvoie la clé de session réseau (Network Session Key) actuelle sous forme de chaîne hexadécimale.

get_appskey() → str#

Renvoie la clé de session applicative (Application Session Key) actuelle sous forme de chaîne hexadécimale.

get_rx2dr() → int#

Renvoie l’indice de débit de données utilisé pour la fenêtre de réception RX2.

set_rx2dr(dr: int) → None#

Définit l’indice de débit de données utilisé pour la fenêtre de réception RX2.

Paramètres:

dr – Indice de débit de données spécifique à la région.

get_ex2freq() → int#

Renvoie la fréquence, en Hz, utilisée pour la fenêtre de réception RX2.

set_rx2freq(freq: int) → None#

Définit la fréquence utilisée pour la fenêtre de réception RX2.

Paramètres:

freq – Fréquence en Hz.

set_fcu(fcu: int) → None#

Définit le compteur de trames de liaison montante (AT+FCU).

Paramètres:

fcu – Nouvelle valeur du compteur de trames de liaison montante.

get_fcu() → int#

Renvoie le compteur de trames de liaison montante actuel.

set_fcd(fcd: int) → None#

Définit le compteur de trames de liaison descendante (AT+FCD).

Paramètres:

fcd – Nouvelle valeur du compteur de trames de liaison descendante.

get_fcd() → int#

Renvoie le compteur de trames de liaison descendante actuel.

change_mode(mode: int) → None#

Change le mode d’activation.

Paramètres:

mode – L’une des valeurs MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool#

Émet un AT+JOIN et attend l’événement d’acceptation de la jonction. Renvoie True si le modem signale +EVENT=1,1 (jonction réussie) dans le délai timeout_ms.

Paramètres:

timeout_ms – Temps maximal d’attente à la fois pour le +ACK et l’événement de jonction subséquent, en millisecondes.

get_join_status() → bool#

Renvoie True si le modem est actuellement rattaché à un réseau.

get_max_size() → int#

Renvoie la taille maximale de charge utile LoRaWAN, en octets, pour le débit de données actuel. Sur le micrologiciel Arduino, elle est fixée à 64.

poll() → None#

Si plus de poll_ms millisecondes se sont écoulées depuis le dernier appel, envoie une liaison montante confirmée vide pour vider les liaisons descendantes en attente. Destinée à être appelée fréquemment depuis la boucle principale de l’application.

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

Transmet une liaison montante LoRaWAN. Lève LoraError si buff est plus grand que get_max_size().

Paramètres:

  • buff – Octets de charge utile à transmettre.

  • confirmed – Lorsque True, envoie une liaison montante confirmée (+CTX) et attend un +ACK du serveur réseau. Lorsque False, envoie une liaison montante non confirmée (+UTX).

Renvoie:

True si le modem a accepté le paquet (et, pour les liaisons montantes confirmées, si le réseau l’a acquitté), False sinon.

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

Attend une liaison descendante. Renvoie None si aucun événement +RECV n’a été reçu dans le délai timeout millisecondes, sinon un dictionnaire {"port": str, "data": str} contenant le FPort et les octets de charge utile.

Paramètres:

timeout – Temps maximal d’attente, en millisecondes.

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

Lecture UART bas niveau. Lit des caractères depuis le modem jusqu’à ce qu’un délimiteur soit trouvé, que max_bytes caractères aient été lus, ou que timeout millisecondes s’écoulent, puis renvoie la chaîne accumulée avec tout \r final supprimé.

Paramètres:

  • delimiter – Soit un caractère unique à faire correspondre à la fin du tampon, soit une chaîne multi-caractères à comparer à l’ensemble du tampon nettoyé, soit une liste de telles chaînes.

  • max_bytes – Si défini, renvoie dès qu’exactement ce nombre d’octets a été lu.

  • timeout – Délai global de lecture, en millisecondes.

available() → int#

Renvoie le nombre d’octets actuellement disponibles dans le tampon de réception UART du modem.

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

Bascule le modem en mode OTAA, programme les clés et EUI fournis, puis tente de rejoindre le réseau. Renvoie True si la jonction a réussi.

Paramètres:

  • appEui – Application/Join EUI 64 bits sous forme de chaîne hexadécimale.

  • appKey – Application Key 128 bits sous forme de chaîne hexadécimale.

  • devEui – Device EUI 64 bits optionnel sous forme de chaîne hexadécimale. Si None, le Device EUI programmé en usine est utilisé.

  • timeout – Délai de jonction, en millisecondes.

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

Bascule le modem en mode ABP, programme les adresses et clés fournies, puis tente de rejoindre. Renvoie le résultat de get_join_status().

Paramètres:

  • nwkId – Identifiant réseau (actuellement ignoré par le micrologiciel).

  • devAddr – Device Address 32 bits sous forme de chaîne hexadécimale.

  • nwkSKey – Network Session Key 128 bits sous forme de chaîne hexadécimale.

  • appSKey – Application Session Key 128 bits sous forme de chaîne hexadécimale.

  • timeout – Délai de jonction, en millisecondes.

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

Inspecte une réponse du modem et lève la sous-classe LoraError correspondante si elle représente une erreur. Ne fait rien pour les réponses sans erreur.

Paramètres:

  • command – La commande AT (sans le préfixe AT) qui a produit data.

  • data – La chaîne de réponse renvoyée par le modem.

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

Construit une commande AT à partir de cmd et args, ajoute éventuellement une charge utile data brute, la transmet et renvoie la réponse du modem. Pour les commandes d’interrogation se terminant par ?, seule la partie valeur (la sous-chaîne après =) est renvoyée.

Paramètres:

  • cmd – Suffixe de commande AT (par ex. "+JOIN", "+DR=") ; le préfixe "AT" et le \r final sont ajoutés automatiquement.

  • args – Arguments supplémentaires concaténés à cmd après conversion en chaîne.

  • delimiter – Délimiteur transmis à receive().

  • data – Octets bruts optionnels écrits immédiatement après la commande AT (utilisés pour les charges utiles de liaison montante binaires).

  • timeout – Délai de réponse, en millisecondes.

  • raise_error – Lorsque True, les réponses d’erreur sont converties en exceptions LoraError ; lorsque False, la réponse brute est renvoyée à l’appelant.