`lora` — Controlador de módem LoRa¶

El módulo lora proporciona un controlador para el módem LoRa Murata CMWX1ZZABZ del Arduino Portenta Vision Shield. Expone una clase Lora de alto nivel que envuelve el conjunto de comandos AT utilizado por el firmware del módem (incluido el firmware Arduino MKRWAN ARD-078) para que una aplicación pueda unirse a una red LoRaWAN y enviar/recibir paquetes.

Ejemplo:

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¶

Modos de activación¶

lora.MODE_ABP: int¶: Modo de activación por personalización (Activation By Personalization).

lora.MODE_OTAA: int¶: Modo de activación por aire (Over-The-Air Activation).

Modos de salida de RF¶

lora.RF_MODE_RFO: int¶: Usar la salida de RF RFO (baja potencia) del módem.

lora.RF_MODE_PABOOST: int¶: Usar la salida de RF PA_BOOST (alta potencia) del módem.

Bandas¶

lora.BAND_AS923: int¶: Banda regional AS923 (Asia 923 MHz).

lora.BAND_AU915: int¶: Banda regional AU915 (Australia 915 MHz).

lora.BAND_EU868: int¶: Banda regional EU868 (Europa 868 MHz).

lora.BAND_KR920: int¶: Banda regional KR920 (Corea 920 MHz).

lora.BAND_IN865: int¶: Banda regional IN865 (India 865 MHz).

lora.BAND_US915: int¶: Banda regional US915 (Estados Unidos 915 MHz).

lora.BAND_US915_HYBRID: int¶: Plan regional híbrido (sub-banda) US915.

Clases de dispositivo¶

lora.CLASS_A: str¶: Dispositivo final LoRaWAN de Clase A.

lora.CLASS_B: str¶: Dispositivo final LoRaWAN de Clase B.

lora.CLASS_C: str¶: Dispositivo final LoRaWAN de Clase C.

Excepciones¶

exception lora.LoraError¶: Excepción base lanzada ante cualquier error devuelto por el módem o el controlador.

exception lora.LoraErrorTimeout¶: Se lanza cuando el módem no responde dentro del tiempo de espera configurado (el búfer de recepción está vacío).

exception lora.LoraErrorParam¶: Se lanza ante una respuesta +ERR_PARAM cuando se emitió un comando AT con un parámetro no válido.

exception lora.LoraErrorBusy¶: Se lanza ante una respuesta +ERR_BUSY cuando el módem está ocupado procesando un comando anterior.

exception lora.LoraErrorOverflow¶: Se lanza ante una respuesta +ERR_PARAM_OVERFLOW cuando un parámetro excede la longitud máxima permitida.

exception lora.LoraErrorNoNetwork¶: Se lanza ante una respuesta +ERR_NO_NETWORK cuando el módem no se ha unido a una red.

exception lora.LoraErrorRX¶: Se lanza ante una respuesta +ERR_RX cuando ocurre un error al recibir un enlace descendente.

exception lora.LoraErrorUnknown¶: Se lanza ante una respuesta +ERR_UNKNOWN o cuando el módem informa de un error no documentado.

Clases¶

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

Construye un nuevo controlador de módem. El constructor inicializa (o crea automáticamente) la UART y los pines de reinicio/arranque, realiza un reinicio por hardware del módulo, ejecuta la sincronización autobaud, reinicia el módulo, consulta su versión de firmware y configura la band regional solicitada.

Parámetros:

uart – Instancia machine.UART preconfigurada que se usa para comunicarse con el módem. Si es None, el controlador abre UART(8, 19200) con tramas 8N2 (el valor predeterminado del Portenta Vision Shield).
rst_pin – machine.Pin que controla la línea de reinicio del módem. Si es None, se configura "PC6" como salida push-pull.
boot_pin – machine.Pin que controla la línea de selección de arranque del módem. Si es None, se configura "PG7" como salida push-pull con resistencia a nivel bajo.
band – Banda regional a configurar. Una de las constantes BAND_*.
poll_ms – Intervalo en milisegundos entre enlaces ascendentes vacíos automáticos disparados por poll() para mantener abierta la ventana de enlace descendente.
debug – Cuando es True, todo el tráfico de la UART se imprime mediante print().

LoraErrors: dict¶: Asignación de cadenas de respuesta de error del módem (p. ej. "+ERR_BUSY") a la clase de excepción correspondiente. Usada internamente por handle_error().

init_modem() → None¶: Inicializa de forma diferida self.uart, self.rst_pin y self.boot_pin con sus valores predeterminados del Portenta Vision Shield si aún no están establecidos. Se llama desde el constructor; normalmente no la invoca el código del usuario.

debug_print(data: str) → None¶: Imprime data si debug estaba habilitado en el momento de la construcción; de lo contrario, no hace nada.

is_arduino_firmware() → bool¶: Devuelve True si el módem está ejecutando el firmware Arduino MKRWAN ARD-078 (detectado a partir de la cadena fw_version en caché).

configure_class(_class: str) → None¶

Configura la clase de dispositivo LoRaWAN.

Parámetros:: _class – Una de CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Configura la banda regional y, en el firmware de Arduino con BAND_EU868, habilita el limitador de ciclo de trabajo ETSI. Devuelve True en caso de éxito.

Parámetros:: band – Una de las constantes BAND_*.

set_baudrate(baudrate: int) → None¶

Cambia la velocidad en baudios de la UART del módem (AT+UART).

Parámetros:: baudrate – Nueva velocidad en baudios, en bits por segundo.

set_autobaud(timeout: int = 10000) → bool¶

Envía comandos AT vacíos hasta que el módem responda con +OK o hasta que transcurran timeout milisegundos. Devuelve True si la sincronización tuvo éxito.

Parámetros:: timeout – Tiempo máximo a dedicar al intento, en milisegundos.

get_fw_version() → str¶: Consulta la cadena del dispositivo del módem (AT+DEV?) y la versión de firmware (AT+VER?) y las devuelve como una única cadena separada por espacios.

get_device_eui() → str¶: Devuelve el EUI de dispositivo de 64 bits del módem como una cadena hexadecimal.

factory_default() → None¶: Restaura los valores de fábrica mediante AT+FACNEW.

restart() → None¶: Vuelve a sincronizar la velocidad en baudios, reinicia el módem, vuelve a leer la versión de firmware y vuelve a aplicar la banda regional configurada. Lanza LoraError en caso de fallo.

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

Configura la etapa de salida de RF del módem (AT+RFPOWER).

Parámetros:

mode – Una de RF_MODE_RFO, RF_MODE_PABOOST.
power – Índice de potencia de salida, en unidades específicas del firmware.

set_port(port: int) → None¶

Configura el puerto de aplicación LoRaWAN (1..223) usado por las llamadas posteriores a send_data().

Parámetros:: port – FPort de LoRaWAN.

set_public_network(enable: bool) → None¶

Habilita o deshabilita la palabra de sincronización de red pública.

Parámetros:: enable – True para la palabra de sincronización pública de LoRaWAN, False para la privada.

sleep(enable: bool) → None¶: Pone el módem en suspensión de baja potencia (True) o lo despierta (False).

format(hexMode: bool) → None¶

Selecciona el formato de datos usado a través de la UART para los bytes de carga útil.

Parámetros:: hexMode – True para el formato de carga útil ASCII-hex, False para binario sin procesar.

set_datarate(dr: int) → None¶

Establece el índice de velocidad de datos de LoRaWAN (AT+DR).

Parámetros:: dr – Índice de velocidad de datos específico de la región.

get_datarate() → int¶: Devuelve el índice de velocidad de datos actual de LoRaWAN.

set_adr(adr: bool) → None¶

Habilita o deshabilita la velocidad de datos adaptativa (Adaptive Data Rate).

Parámetros:: adr – True para habilitar ADR, False para deshabilitarla.

get_adr() → int¶: Devuelve la configuración actual de ADR (1 si está habilitada, 0 en caso contrario).

get_devaddr() → str¶: Devuelve el DevAddr de 32 bits actual como una cadena hexadecimal.

get_nwk_skey() → str¶: Devuelve la clave de sesión de red (Network Session Key) actual como una cadena hexadecimal.

get_appskey() → str¶: Devuelve la clave de sesión de aplicación (Application Session Key) actual como una cadena hexadecimal.

get_rx2dr() → int¶: Devuelve el índice de velocidad de datos usado para la ventana de recepción RX2.

set_rx2dr(dr: int) → None¶

Establece el índice de velocidad de datos usado para la ventana de recepción RX2.

Parámetros:: dr – Índice de velocidad de datos específico de la región.

get_ex2freq() → int¶: Devuelve la frecuencia, en Hz, usada para la ventana de recepción RX2.

set_rx2freq(freq: int) → None¶

Establece la frecuencia usada para la ventana de recepción RX2.

Parámetros:: freq – Frecuencia en Hz.

set_fcu(fcu: int) → None¶

Establece el contador de tramas de enlace ascendente (AT+FCU).

Parámetros:: fcu – Nuevo valor del contador de tramas de enlace ascendente.

get_fcu() → int¶: Devuelve el contador de tramas de enlace ascendente actual.

set_fcd(fcd: int) → None¶

Establece el contador de tramas de enlace descendente (AT+FCD).

Parámetros:: fcd – Nuevo valor del contador de tramas de enlace descendente.

get_fcd() → int¶: Devuelve el contador de tramas de enlace descendente actual.

change_mode(mode: int) → None¶

Cambia el modo de activación.

Parámetros:: mode – Uno de MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Emite un AT+JOIN y espera el evento de aceptación de unión. Devuelve True si el módem informa de +EVENT=1,1 (unión exitosa) dentro de timeout_ms.

Parámetros:: timeout_ms – Tiempo máximo de espera tanto para el +ACK como para el evento de unión posterior, en milisegundos.

get_join_status() → bool¶: Devuelve True si el módem está actualmente unido a una red.

get_max_size() → int¶: Devuelve el tamaño máximo de carga útil de LoRaWAN, en bytes, para la velocidad de datos actual. En el firmware de Arduino esto es fijo en 64.

poll() → None¶: Si han pasado más de poll_ms milisegundos desde la última llamada, envía un enlace ascendente confirmado vacío para vaciar los enlaces descendentes pendientes. Pensado para llamarse con frecuencia desde el bucle principal de la aplicación.

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

Transmite un enlace ascendente LoRaWAN. Lanza LoraError si buff es mayor que get_max_size().

Parámetros:

buff – Bytes de carga útil a transmitir.
confirmed – Cuando es True, envía un enlace ascendente confirmado (+CTX) y espera un +ACK del servidor de red. Cuando es False, envía un enlace ascendente no confirmado (+UTX).

Devuelve:

True si el módem aceptó el paquete (y, para enlaces ascendentes confirmados, la red lo confirmó), False en caso contrario.

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

Espera un enlace descendente. Devuelve None si no se recibió ningún evento +RECV dentro de timeout milisegundos; de lo contrario, un diccionario {"port": str, "data": str} que contiene el FPort y los bytes de carga útil.

Parámetros:: timeout – Tiempo máximo de espera, en milisegundos.

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

Lectura UART de bajo nivel. Lee caracteres del módem hasta que se encuentra un delimitador, se han leído max_bytes caracteres o transcurren timeout milisegundos, y luego devuelve la cadena acumulada con cualquier \r final eliminado.

Parámetros:

delimiter – Un único carácter para coincidir al final del búfer, una cadena de varios caracteres para comparar con el búfer recortado completo, o una lista de tales cadenas.
max_bytes – Si se establece, devuelve en cuanto se hayan leído exactamente esta cantidad de bytes.
timeout – Tiempo de espera total de lectura, en milisegundos.

available() → int¶: Devuelve el número de bytes actualmente disponibles en el búfer de recepción de la UART del módem.

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

Cambia el módem al modo OTAA, programa las claves y los EUI suministrados, y luego intenta unirse a la red. Devuelve True si la unión tuvo éxito.

Parámetros:

appEui – EUI de aplicación/unión de 64 bits como cadena hexadecimal.
appKey – Clave de aplicación de 128 bits como cadena hexadecimal.
devEui – EUI de dispositivo de 64 bits opcional como cadena hexadecimal. Si es None, se usa el EUI de dispositivo programado de fábrica.
timeout – Tiempo de espera de unión, en milisegundos.

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

Cambia el módem al modo ABP, programa las direcciones y claves suministradas, y luego intenta unirse. Devuelve el resultado de get_join_status().

Parámetros:

nwkId – Identificador de red (actualmente ignorado por el firmware).
devAddr – Dirección de dispositivo de 32 bits como cadena hexadecimal.
nwkSKey – Clave de sesión de red de 128 bits como cadena hexadecimal.
appSKey – Clave de sesión de aplicación de 128 bits como cadena hexadecimal.
timeout – Tiempo de espera de unión, en milisegundos.

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

Inspecciona una respuesta del módem y lanza la subclase LoraError correspondiente si representa un error. No hace nada para respuestas que no sean de error.

Parámetros:

command – El comando AT (sin el prefijo AT) que produjo data.
data – La cadena de respuesta devuelta por el módem.

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

Construye un comando AT a partir de cmd y args, opcionalmente añade una carga útil data sin procesar, lo transmite y devuelve la respuesta del módem. Para los comandos de consulta que terminan en ?, solo se devuelve la parte del valor (la subcadena después de =).

Parámetros:

cmd – Sufijo del comando AT (p. ej. "+JOIN", "+DR="); el prefijo "AT" y el \r final se añaden automáticamente.
args – Argumentos adicionales concatenados a cmd tras su conversión a cadena.
delimiter – Delimitador reenviado a receive().
data – Bytes sin procesar opcionales escritos inmediatamente después del comando AT (usados para cargas útiles binarias de enlace ascendente).
timeout – Tiempo de espera de respuesta, en milisegundos.
raise_error – Cuando es True, las respuestas de error se convierten en excepciones LoraError; cuando es False, la respuesta sin procesar se devuelve al llamador.

lora — Controlador de módem LoRa¶

Constantes¶

Modos de activación¶

Modos de salida de RF¶

Bandas¶

Clases de dispositivo¶

Excepciones¶

Clases¶

`lora` — Controlador de módem LoRa¶