`lora` — Driver de modem LoRa¶

O módulo lora fornece um driver para o modem LoRa Murata CMWX1ZZABZ presente no Arduino Portenta Vision Shield. Ele expõe uma classe Lora de alto nível que encapsula o conjunto de comandos AT usado pelo firmware do modem (incluindo o firmware ARD-078 do Arduino MKRWAN), de modo que uma aplicação possa se juntar a uma rede LoRaWAN e enviar/receber pacotes.

Exemplo:

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 ativação¶

lora.MODE_ABP: int¶: Modo Activation By Personalization (ativação por personalização).

lora.MODE_OTAA: int¶: Modo Over-The-Air Activation (ativação over-the-air).

Modos de saída de RF¶

lora.RF_MODE_RFO: int¶: Usa a saída de RF RFO (baixa potência) do modem.

lora.RF_MODE_PABOOST: int¶: Usa a saída de RF PA_BOOST (alta potência) do modem.

Bandas¶

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

lora.BAND_AU915: int¶: Banda regional AU915 (Austrália 915 MHz).

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

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

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

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

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

Classes de dispositivo¶

lora.CLASS_A: str¶: Dispositivo final LoRaWAN Classe A.

lora.CLASS_B: str¶: Dispositivo final LoRaWAN Classe B.

lora.CLASS_C: str¶: Dispositivo final LoRaWAN Classe C.

Exceções¶

exception lora.LoraError¶: Exceção base lançada para qualquer erro retornado pelo modem ou pelo driver.

exception lora.LoraErrorTimeout¶: Lançada quando o modem não responde dentro do timeout configurado (o buffer de recepção está vazio).

exception lora.LoraErrorParam¶: Lançada em uma resposta +ERR_PARAM quando um comando AT foi emitido com um parâmetro inválido.

exception lora.LoraErrorBusy¶: Lançada em uma resposta +ERR_BUSY quando o modem está ocupado processando um comando anterior.

exception lora.LoraErrorOverflow¶: Lançada em uma resposta +ERR_PARAM_OVERFLOW quando um parâmetro excede o comprimento máximo permitido.

exception lora.LoraErrorNoNetwork¶: Lançada em uma resposta +ERR_NO_NETWORK quando o modem não se juntou a uma rede.

exception lora.LoraErrorRX¶: Lançada em uma resposta +ERR_RX quando ocorre um erro ao receber um downlink.

exception lora.LoraErrorUnknown¶: Lançada em uma resposta +ERR_UNKNOWN ou quando o modem reporta um erro não documentado.

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

Constrói um novo driver de modem. O construtor inicializa (ou cria automaticamente) a UART e os pinos de reset/boot, faz o reset por hardware do módulo, executa a sincronização de autobaud, reinicia o módulo, consulta a versão do seu firmware e configura a band regional solicitada.

Parâmetros:

uart – Instância machine.UART pré-configurada usada para se comunicar com o modem. Se for None, o driver abre UART(8, 19200) com framing 8N2 (o padrão do Portenta Vision Shield).
rst_pin – Instância machine.Pin que controla a linha de reset do modem. Se for None, "PC6" é configurado como saída push-pull.
boot_pin – Instância machine.Pin que controla a linha de seleção de boot do modem. Se for None, "PG7" é configurado como saída push-pull com pull-down.
band – Banda regional a configurar. Uma das constantes BAND_*.
poll_ms – Intervalo em milissegundos entre uplinks vazios automáticos disparados por poll() para manter a janela de downlink aberta.
debug – Quando True, todo o tráfego da UART é impresso via print().

LoraErrors: dict¶: Mapeamento das strings de resposta de erro do modem (por exemplo, "+ERR_BUSY") para a classe de exceção correspondente. Usado internamente por handle_error().

init_modem() → None¶: Inicializa de forma preguiçosa self.uart, self.rst_pin e self.boot_pin com seus padrões do Portenta Vision Shield, caso ainda não estejam definidos. Chamado pelo construtor; normalmente não é invocado pelo código do usuário.

debug_print(data: str) → None¶: Imprime data se debug foi habilitado no momento da construção; caso contrário, não faz nada.

is_arduino_firmware() → bool¶: Retorna True se o modem estiver executando o firmware ARD-078 do Arduino MKRWAN (detectado a partir da string fw_version em cache).

configure_class(_class: str) → None¶

Configura a classe de dispositivo LoRaWAN.

Parâmetros:: _class – Uma de CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Configura a banda regional e, em firmware Arduino com BAND_EU868, habilita o limitador de duty-cycle da ETSI. Retorna True em caso de sucesso.

Parâmetros:: band – Uma das constantes BAND_*.

set_baudrate(baudrate: int) → None¶

Altera a taxa de transmissão (baud rate) da UART do modem (AT+UART).

Parâmetros:: baudrate – Nova taxa de transmissão (baud rate), em bits por segundo.

set_autobaud(timeout: int = 10000) → bool¶

Envia comandos AT vazios até que o modem responda com +OK ou até que decorram timeout milissegundos. Retorna True se a sincronização for bem-sucedida.

Parâmetros:: timeout – Tempo máximo a despender tentando, em milissegundos.

get_fw_version() → str¶: Consulta a string de dispositivo do modem (AT+DEV?) e a versão do firmware (AT+VER?) e as retorna como uma única string separada por espaço.

get_device_eui() → str¶: Retorna o Device EUI de 64 bits do modem como uma string hexadecimal.

factory_default() → None¶: Restaura os padrões de fábrica via AT+FACNEW.

restart() → None¶: Ressincroniza a taxa de transmissão (baud rate), reinicia o modem, relê a versão do firmware e reaplica a banda regional configurada. Lança LoraError em caso de falha.

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

Configura o estágio de saída de RF do modem (AT+RFPOWER).

Parâmetros:

mode – Uma de RF_MODE_RFO, RF_MODE_PABOOST.
power – Índice de potência de saída, em unidades específicas do firmware.

set_port(port: int) → None¶

Configura a porta de aplicação LoRaWAN (1..223) usada por chamadas subsequentes a send_data().

Parâmetros:: port – FPort LoRaWAN.

set_public_network(enable: bool) → None¶

Habilita ou desabilita a sync word de rede pública.

Parâmetros:: enable – True para a sync word LoRaWAN pública, False para a privada.

sleep(enable: bool) → None¶: Coloca o modem em modo de baixo consumo (True) ou o desperta (False).

format(hexMode: bool) → None¶

Seleciona o formato de dados usado na UART para os bytes de payload.

Parâmetros:: hexMode – True para o formato de payload ASCII-hex, False para binário bruto.

set_datarate(dr: int) → None¶

Define o índice da data rate LoRaWAN (AT+DR).

Parâmetros:: dr – Índice de data rate específico da região.

get_datarate() → int¶: Retorna o índice atual da data rate LoRaWAN.

set_adr(adr: bool) → None¶

Habilita ou desabilita o Adaptive Data Rate.

Parâmetros:: adr – True para habilitar o ADR, False para desabilitá-lo.

get_adr() → int¶: Retorna a configuração atual de ADR (1 se habilitado, 0 caso contrário).

get_devaddr() → str¶: Retorna o DevAddr atual de 32 bits como uma string hexadecimal.

get_nwk_skey() → str¶: Retorna a Network Session Key atual como uma string hexadecimal.

get_appskey() → str¶: Retorna a Application Session Key atual como uma string hexadecimal.

get_rx2dr() → int¶: Retorna o índice de data rate usado para a janela de recepção RX2.

set_rx2dr(dr: int) → None¶

Define o índice de data rate usado para a janela de recepção RX2.

Parâmetros:: dr – Índice de data rate específico da região.

get_ex2freq() → int¶: Retorna a frequência, em Hz, usada para a janela de recepção RX2.

set_rx2freq(freq: int) → None¶

Define a frequência usada para a janela de recepção RX2.

Parâmetros:: freq – Frequência em Hz.

set_fcu(fcu: int) → None¶

Define o contador de quadros de uplink (AT+FCU).

Parâmetros:: fcu – Novo valor do contador de quadros de uplink.

get_fcu() → int¶: Retorna o contador de quadros de uplink atual.

set_fcd(fcd: int) → None¶

Define o contador de quadros de downlink (AT+FCD).

Parâmetros:: fcd – Novo valor do contador de quadros de downlink.

get_fcd() → int¶: Retorna o contador de quadros de downlink atual.

change_mode(mode: int) → None¶

Alterna o modo de ativação.

Parâmetros:: mode – Um de MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Emite um AT+JOIN e aguarda o evento de join-accept. Retorna True se o modem reportar +EVENT=1,1 (join bem-sucedido) dentro de timeout_ms.

Parâmetros:: timeout_ms – Tempo máximo de espera tanto pelo +ACK quanto pelo evento de join subsequente, em milissegundos.

get_join_status() → bool¶: Retorna True se o modem estiver atualmente conectado a uma rede.

get_max_size() → int¶: Retorna o tamanho máximo do payload LoRaWAN, em bytes, para a data rate atual. Em firmware Arduino, isso é fixo em 64.

poll() → None¶: Se mais de poll_ms milissegundos se passaram desde a última chamada, envia um uplink confirmado vazio para esvaziar os downlinks pendentes. Destinado a ser chamado com frequência a partir do loop principal da aplicação.

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

Transmite um uplink LoRaWAN. Lança LoraError se buff for maior que get_max_size().

Parâmetros:

buff – Bytes de payload a transmitir.
confirmed – Quando True, envia um uplink confirmado (+CTX) e aguarda um +ACK do servidor de rede. Quando False, envia um uplink não confirmado (+UTX).

Retorna:

True se o modem aceitou o pacote (e, para uplinks confirmados, a rede o reconheceu), False caso contrário.

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

Aguarda um downlink. Retorna None se nenhum evento +RECV for recebido dentro de timeout milissegundos; caso contrário, retorna um dict {"port": str, "data": str} contendo o FPort e os bytes do payload.

Parâmetros:: timeout – Tempo máximo de espera, em milissegundos.

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

Leitura de baixo nível da UART. Lê caracteres do modem até que um delimitador seja correspondido, até que max_bytes caracteres tenham sido lidos ou até que decorram timeout milissegundos; então retorna a string acumulada com qualquer \r final removido.

Parâmetros:

delimiter – Pode ser um único caractere a corresponder no final do buffer, uma string de múltiplos caracteres a corresponder contra o buffer completo já recortado, ou uma lista de tais strings.
max_bytes – Se definido, retorna assim que exatamente esta quantidade de bytes tiver sido lida.
timeout – Timeout geral de leitura, em milissegundos.

available() → int¶: Retorna o número de bytes atualmente disponíveis no buffer de recepção da UART do modem.

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

Alterna o modem para o modo OTAA, programa as chaves e EUIs fornecidas e então tenta se juntar à rede. Retorna True se o join for bem-sucedido.

Parâmetros:

appEui – Application/Join EUI de 64 bits como uma string hexadecimal.
appKey – Application Key de 128 bits como uma string hexadecimal.
devEui – Device EUI opcional de 64 bits como uma string hexadecimal. Se for None, é usado o Device EUI programado de fábrica.
timeout – Timeout de join, em milissegundos.

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

Alterna o modem para o modo ABP, programa os endereços e chaves fornecidos e então tenta se juntar. Retorna o resultado de get_join_status().

Parâmetros:

nwkId – Identificador de rede (atualmente ignorado pelo firmware).
devAddr – Device Address de 32 bits como uma string hexadecimal.
nwkSKey – Network Session Key de 128 bits como uma string hexadecimal.
appSKey – Application Session Key de 128 bits como uma string hexadecimal.
timeout – Timeout de join, em milissegundos.

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

Inspeciona uma resposta do modem e lança a subclasse de LoraError correspondente se ela representar um erro. Não faz nada para respostas que não sejam de erro.

Parâmetros:

command – O comando AT (sem o prefixo AT) que produziu data.
data – A string de resposta retornada pelo modem.

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

Monta um comando AT a partir de cmd e args, opcionalmente acrescenta um payload data bruto, o transmite e retorna a resposta do modem. Para comandos de consulta que terminam em ?, apenas a parte do valor (a substring após =) é retornada.

Parâmetros:

cmd – Sufixo do comando AT (por exemplo, "+JOIN", "+DR="); o prefixo "AT" e o \r final são adicionados automaticamente.
args – Argumentos adicionais concatenados a cmd após conversão para string.
delimiter – Delimitador encaminhado para receive().
data – Bytes brutos opcionais escritos imediatamente após o comando AT (usados para payloads de uplink binários).
timeout – Timeout de resposta, em milissegundos.
raise_error – Quando True, respostas de erro são convertidas em exceções LoraError; quando False, a resposta bruta é retornada ao chamador.

lora — Driver de modem LoRa¶

Constantes¶

Modos de ativação¶

Modos de saída de RF¶

Bandas¶

Classes de dispositivo¶

Exceções¶

Classes¶

`lora` — Driver de modem LoRa¶