`lora` — driver do modem LoRa¶

O módulo lora fornece um driver para o modem LoRa Murata CMWX1ZZABZ presente no Arduino Portenta Vision Shield. Expõe uma classe Lora de alto nível que encapsula o conjunto de comandos AT utilizado pelo firmware do modem (incluindo o firmware Arduino MKRWAN ARD-078), permitindo que uma aplicação se associe a uma rede LoRaWAN e envie/receba 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 de Ativação por Personalização.

lora.MODE_OTAA: int¶: Modo de Ativação Over-The-Air.

Modos de saída RF¶

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

lora.RF_MODE_PABOOST: int¶: Utiliza a saída 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¶: Classe A de dispositivo final LoRaWAN.

lora.CLASS_B: str¶: Classe B de dispositivo final LoRaWAN.

lora.CLASS_C: str¶: Classe C de dispositivo final LoRaWAN.

Exceções¶

exception lora.LoraError¶: Exceção base levantada para qualquer erro devolvido pelo modem ou pelo driver.

exception lora.LoraErrorTimeout¶: Levantada quando o modem não responde dentro do tempo limite configurado (o buffer de receção está vazio).

exception lora.LoraErrorParam¶: Levantada numa resposta +ERR_PARAM quando um comando AT foi emitido com um parâmetro inválido.

exception lora.LoraErrorBusy¶: Levantada numa resposta +ERR_BUSY quando o modem está ocupado a processar um comando anterior.

exception lora.LoraErrorOverflow¶: Levantada numa resposta +ERR_PARAM_OVERFLOW quando um parâmetro excede o comprimento máximo permitido.

exception lora.LoraErrorNoNetwork¶: Levantada numa resposta +ERR_NO_NETWORK quando o modem não se associou a uma rede.

exception lora.LoraErrorRX¶: Levantada numa resposta +ERR_RX quando ocorre um erro ao receber um downlink.

exception lora.LoraErrorUnknown¶: Levantada numa 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) o UART e os pinos de reset/boot, efetua um reset por hardware do módulo, realiza sincronização de baud automática, reinicia o módulo, consulta a versão do firmware e configura a band regional solicitada.

Parâmetros:

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

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

init_modem() → None¶: Inicializa de forma lazy self.uart, self.rst_pin e self.boot_pin com os valores predefinidos do Portenta Vision Shield, caso ainda não estejam definidos. Invocado pelo construtor; normalmente não é chamado diretamente pelo código do utilizador.

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

is_arduino_firmware() → bool¶: Devolve True se o modem está a executar o firmware Arduino MKRWAN ARD-078 (detetado a partir da string fw_version em cache).

configure_class(_class: str) → None¶

Configura a classe de dispositivo LoRaWAN.

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

configure_band(band: int) → bool¶

Configura a banda regional e, no firmware Arduino com BAND_EU868, ativa o limitador de ciclo de trabalho ETSI. Devolve True em caso de sucesso.

Parâmetros:: band – Um dos valores das constantes BAND_*.

set_baudrate(baudrate: int) → None¶

Altera a taxa de baud do UART do modem (AT+UART).

Parâmetros:: baudrate – Nova taxa de baud, 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. Devolve True se a sincronização foi bem-sucedida.

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

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

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

factory_default() → None¶: Restaura as predefinições de fábrica via AT+FACNEW.

restart() → None¶: Re-sincroniza a taxa de baud, reinicia o modem, relê a versão do firmware e reaplica a banda regional configurada. Levanta LoraError em caso de falha.

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

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

Parâmetros:

mode – Um 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 pelas chamadas subsequentes a send_data().

Parâmetros:: port – FPort LoRaWAN.

set_public_network(enable: bool) → None¶

Ativa ou desativa a palavra de sincronização da rede pública.

Parâmetros:: enable – True para a palavra de sincronização pública LoRaWAN, False para a privada.

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

format(hexMode: bool) → None¶

Seleciona o formato de dados utilizado no UART para os bytes de payload.

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

set_datarate(dr: int) → None¶

Define o índice de taxa de dados LoRaWAN (AT+DR).

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

get_datarate() → int¶: Devolve o índice de taxa de dados LoRaWAN atual.

set_adr(adr: bool) → None¶

Ativa ou desativa o Adaptive Data Rate.

Parâmetros:: adr – True para ativar ADR, False para desativar.

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

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

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

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

get_rx2dr() → int¶: Devolve o índice de taxa de dados utilizado para a janela de receção RX2.

set_rx2dr(dr: int) → None¶

Define o índice de taxa de dados utilizado para a janela de receção RX2.

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

get_ex2freq() → int¶: Devolve a frequência, em Hz, utilizada para a janela de receção RX2.

set_rx2freq(freq: int) → None¶

Define a frequência utilizada para a janela de receção RX2.

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

set_fcu(fcu: int) → None¶

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

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

get_fcu() → int¶: Devolve o contador de fotogramas de uplink atual.

set_fcd(fcd: int) → None¶

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

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

get_fcd() → int¶: Devolve o contador de fotogramas de downlink atual.

change_mode(mode: int) → None¶

Muda 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. Devolve True se o modem reportar +EVENT=1,1 (associação bem-sucedida) dentro de timeout_ms.

Parâmetros:: timeout_ms – Tempo máximo a aguardar tanto pelo +ACK como pelo evento de associação subsequente, em milissegundos.

get_join_status() → bool¶: Devolve True se o modem está atualmente associado a uma rede.

get_max_size() → int¶: Devolve o tamanho máximo de payload LoRaWAN, em bytes, para a taxa de dados atual. No firmware Arduino, este valor é fixo em 64.

poll() → None¶: Se tiverem passado mais de poll_ms milissegundos desde a última chamada, envia um uplink confirmado vazio para descarregar downlinks pendentes. Destinado a ser chamado frequentemente no ciclo principal da aplicação.

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

Transmite um uplink LoRaWAN. Levanta LoraError se buff for maior do 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).

Retorno:

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. Devolve None se nenhum evento +RECV for recebido dentro de timeout milissegundos; caso contrário, devolve um dicionário {"port": str, "data": str} contendo o FPort e os bytes de payload.

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

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

Leitura UART de baixo nível. Lê caracteres do modem até que um delimitador seja encontrado, que max_bytes caracteres tenham sido lidos, ou que decorram timeout milissegundos; devolve então 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 comparar com o buffer completo sem espaços, ou uma lista dessas strings.
max_bytes – Se definido, devolve assim que exatamente este número de bytes tiver sido lido.
timeout – Tempo limite global de leitura, em milissegundos.

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

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

Muda o modem para o modo OTAA, programa as chaves e EUIs fornecidos e, em seguida, tenta associar-se à rede. Devolve True se a associação foi bem-sucedida.

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 None, é utilizado o Device EUI programado de fábrica.
timeout – Tempo limite de associação, em milissegundos.

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

Muda o modem para o modo ABP, programa os endereços e chaves fornecidos e, em seguida, tenta associar-se. Devolve 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 – Tempo limite de associação, em milissegundos.

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

Inspeciona uma resposta do modem e levanta a subclasse LoraError correspondente se representar um erro. Não faz nada para respostas sem erro.

Parâmetros:

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

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

Constrói um comando AT a partir de cmd e args, opcionalmente acrescenta um payload data bruto, transmite-o e devolve a resposta do modem. Para comandos de consulta terminados em ?, apenas a parte do valor (a substring após =) é devolvida.

Parâmetros:

cmd – Sufixo do comando AT (p. ex. "+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 repassado a receive().
data – Bytes brutos opcionais escritos imediatamente após o comando AT (usados para payloads de uplink binários).
timeout – Tempo limite de resposta, em milissegundos.
raise_error – Quando True, as respostas de erro são convertidas em exceções LoraError; quando False, a resposta bruta é devolvida ao chamador.

lora — driver do modem LoRa¶

Constantes¶

Modos de ativação¶

Modos de saída RF¶

Bandas¶

Classes de dispositivo¶

Exceções¶

Classes¶

`lora` — driver do modem LoRa¶