`lora` — драйвер LoRa-модема¶

Модуль lora предоставляет драйвер для LoRa-модема Murata CMWX1ZZABZ на плате Arduino Portenta Vision Shield. Он предоставляет высокоуровневый класс Lora, который оборачивает набор AT-команд, используемых прошивкой модема (включая прошивку Arduino MKRWAN ARD-078), чтобы приложение могло подключаться к сети LoRaWAN и отправлять/принимать пакеты.

Пример:

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)

Константы¶

Режимы активации¶

lora.MODE_ABP: int¶: Режим активации по персонализации (Activation By Personalization).

lora.MODE_OTAA: int¶: Режим активации по воздуху (Over-The-Air Activation).

Режимы RF-выхода¶

lora.RF_MODE_RFO: int¶: Использовать RF-выход RFO модема (с низким энергопотреблением).

lora.RF_MODE_PABOOST: int¶: Использовать RF-выход PA_BOOST модема (с высокой мощностью).

Диапазоны¶

lora.BAND_AS923: int¶: Региональный диапазон AS923 (Азия, 923 МГц).

lora.BAND_AU915: int¶: Региональный диапазон AU915 (Австралия, 915 МГц).

lora.BAND_EU868: int¶: Региональный диапазон EU868 (Европа, 868 МГц).

lora.BAND_KR920: int¶: Региональный диапазон KR920 (Корея, 920 МГц).

lora.BAND_IN865: int¶: Региональный диапазон IN865 (Индия, 865 МГц).

lora.BAND_US915: int¶: Региональный диапазон US915 (США, 915 МГц).

lora.BAND_US915_HYBRID: int¶: Региональный план US915 hybrid (поддиапазон).

Классы устройств¶

lora.CLASS_A: str¶: Оконечное устройство LoRaWAN класса A.

lora.CLASS_B: str¶: Оконечное устройство LoRaWAN класса B.

lora.CLASS_C: str¶: Оконечное устройство LoRaWAN класса C.

Исключения¶

exception lora.LoraError¶: Базовое исключение, возбуждаемое при любой ошибке, возвращаемой модемом или драйвером.

exception lora.LoraErrorTimeout¶: Возбуждается, когда модем не отвечает в течение заданного тайм-аута (приёмный буфер пуст).

exception lora.LoraErrorParam¶: Возбуждается при ответе +ERR_PARAM, когда AT-команда была выполнена с недопустимым параметром.

exception lora.LoraErrorBusy¶: Возбуждается при ответе +ERR_BUSY, когда модем занят обработкой предыдущей команды.

exception lora.LoraErrorOverflow¶: Возбуждается при ответе +ERR_PARAM_OVERFLOW, когда параметр превышает максимально допустимую длину.

exception lora.LoraErrorNoNetwork¶: Возбуждается при ответе +ERR_NO_NETWORK, когда модем не подключён к сети.

exception lora.LoraErrorRX¶: Возбуждается при ответе +ERR_RX, когда происходит ошибка при приёме нисходящего пакета.

exception lora.LoraErrorUnknown¶: Возбуждается при ответе +ERR_UNKNOWN или когда модем сообщает о недокументированной ошибке.

Классы¶

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

Создаёт новый драйвер модема. Конструктор инициализирует (или автоматически создаёт) UART и выводы сброса/загрузки, выполняет аппаратный сброс модуля, производит автоматическую синхронизацию скорости передачи, перезагружает модуль, запрашивает версию его прошивки и настраивает запрошенный региональный диапазон band.

Параметры:

uart – Предварительно настроенный экземпляр machine.UART, используемый для связи с модемом. Если None, драйвер открывает UART(8, 19200) с кадрированием 8N2 (значение по умолчанию для Portenta Vision Shield).
rst_pin – Экземпляр machine.Pin, управляющий линией сброса модема. Если None, "PC6" настраивается как двухтактный выход.
boot_pin – Экземпляр machine.Pin, управляющий линией выбора режима загрузки модема. Если None, "PG7" настраивается как двухтактный выход, подтянутый к низкому уровню.
band – Региональный диапазон для настройки. Одна из констант BAND_*.
poll_ms – Интервал в миллисекундах между автоматическими пустыми восходящими пакетами, инициируемыми poll(), чтобы держать окно нисходящего канала открытым.
debug – Если True, весь трафик UART выводится через print().

LoraErrors: dict¶: Сопоставление строк ответов об ошибках модема (например, "+ERR_BUSY") с соответствующим классом исключения. Используется внутренне методом handle_error().

init_modem() → None¶: Лениво инициализирует self.uart, self.rst_pin и self.boot_pin значениями по умолчанию для Portenta Vision Shield, если они ещё не заданы. Вызывается из конструктора; обычно не вызывается из пользовательского кода.

debug_print(data: str) → None¶: Выводит data, если при создании был включён режим debug, иначе ничего не делает.

is_arduino_firmware() → bool¶: Возвращает True, если модем работает с прошивкой Arduino MKRWAN ARD-078 (определяется по кэшированной строке fw_version).

configure_class(_class: str) → None¶

Настраивает класс устройства LoRaWAN.

Параметры:: _class – Одно из CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool¶

Настраивает региональный диапазон и, на прошивке Arduino с BAND_EU868, включает ограничитель рабочего цикла ETSI. Возвращает True в случае успеха.

Параметры:: band – Одна из констант BAND_*.

set_baudrate(baudrate: int) → None¶

Изменяет скорость передачи UART модема (AT+UART).

Параметры:: baudrate – Новая скорость передачи, в битах в секунду.

set_autobaud(timeout: int = 10000) → bool¶

Отправляет пустые команды AT, пока модем не ответит +OK или пока не истечёт timeout миллисекунд. Возвращает True, если синхронизация удалась.

Параметры:: timeout – Максимальное время на попытки, в миллисекундах.

get_fw_version() → str¶: Запрашивает строку устройства модема (AT+DEV?) и версию прошивки (AT+VER?) и возвращает их в виде единой строки, разделённой пробелом.

get_device_eui() → str¶: Возвращает 64-битный Device EUI модема в виде шестнадцатеричной строки.

factory_default() → None¶: Восстанавливает заводские настройки через AT+FACNEW.

restart() → None¶: Повторно синхронизирует скорость передачи, перезагружает модем, заново считывает версию прошивки и повторно применяет настроенный региональный диапазон. Возбуждает LoraError при сбое.

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

Настраивает выходной RF-каскад модема (AT+RFPOWER).

Параметры:

mode – Одно из RF_MODE_RFO, RF_MODE_PABOOST.
power – Индекс выходной мощности, в единицах, специфичных для прошивки.

set_port(port: int) → None¶

Настраивает порт приложения LoRaWAN (1..223), используемый последующими вызовами send_data().

Параметры:: port – FPort LoRaWAN.

set_public_network(enable: bool) → None¶

Включает или отключает синхрослово публичной сети.

Параметры:: enable – True для синхрослова публичной сети LoRaWAN, False для приватного.

sleep(enable: bool) → None¶: Переводит модем в режим энергосбережения (True) или выводит его из него (False).

format(hexMode: bool) → None¶

Выбирает формат данных, используемый по UART для байтов полезной нагрузки.

Параметры:: hexMode – True для формата полезной нагрузки ASCII-hex, False для необработанного двоичного.

set_datarate(dr: int) → None¶

Устанавливает индекс скорости передачи данных LoRaWAN (AT+DR).

Параметры:: dr – Индекс скорости передачи данных, специфичный для региона.

get_datarate() → int¶: Возвращает текущий индекс скорости передачи данных LoRaWAN.

set_adr(adr: bool) → None¶

Включает или отключает адаптивную скорость передачи данных (Adaptive Data Rate).

Параметры:: adr – True для включения ADR, False для отключения.

get_adr() → int¶: Возвращает текущую настройку ADR (1, если включено, иначе 0).

get_devaddr() → str¶: Возвращает текущий 32-битный DevAddr в виде шестнадцатеричной строки.

get_nwk_skey() → str¶: Возвращает текущий сетевой сеансовый ключ (Network Session Key) в виде шестнадцатеричной строки.

get_appskey() → str¶: Возвращает текущий сеансовый ключ приложения (Application Session Key) в виде шестнадцатеричной строки.

get_rx2dr() → int¶: Возвращает индекс скорости передачи данных, используемый для приёмного окна RX2.

set_rx2dr(dr: int) → None¶

Устанавливает индекс скорости передачи данных, используемый для приёмного окна RX2.

Параметры:: dr – Индекс скорости передачи данных, специфичный для региона.

get_ex2freq() → int¶: Возвращает частоту в Гц, используемую для приёмного окна RX2.

set_rx2freq(freq: int) → None¶

Устанавливает частоту, используемую для приёмного окна RX2.

Параметры:: freq – Частота в Гц.

set_fcu(fcu: int) → None¶

Устанавливает счётчик восходящих кадров (AT+FCU).

Параметры:: fcu – Новое значение счётчика восходящих кадров.

get_fcu() → int¶: Возвращает текущий счётчик восходящих кадров.

set_fcd(fcd: int) → None¶

Устанавливает счётчик нисходящих кадров (AT+FCD).

Параметры:: fcd – Новое значение счётчика нисходящих кадров.

get_fcd() → int¶: Возвращает текущий счётчик нисходящих кадров.

change_mode(mode: int) → None¶

Переключает режим активации.

Параметры:: mode – Одно из MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool¶

Выполняет AT+JOIN и ожидает событие принятия подключения. Возвращает True, если модем сообщает +EVENT=1,1 (подключение успешно) в течение timeout_ms.

Параметры:: timeout_ms – Максимальное время ожидания как +ACK, так и последующего события подключения, в миллисекундах.

get_join_status() → bool¶: Возвращает True, если модем в настоящее время подключён к сети.

get_max_size() → int¶: Возвращает максимальный размер полезной нагрузки LoRaWAN в байтах для текущей скорости передачи данных. На прошивке Arduino он фиксирован и равен 64.

poll() → None¶: Если с момента последнего вызова прошло более poll_ms миллисекунд, отправляет пустой подтверждённый восходящий пакет для сброса ожидающих нисходящих пакетов. Предназначен для частого вызова из основного цикла приложения.

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

Передаёт восходящий пакет LoRaWAN. Возбуждает LoraError, если buff больше get_max_size().

Параметры:

buff – Байты полезной нагрузки для передачи.
confirmed – Если True, отправляет подтверждённый восходящий пакет (+CTX) и ожидает +ACK от сетевого сервера. Если False, отправляет неподтверждённый восходящий пакет (+UTX).

Результат:

True, если модем принял пакет (и, для подтверждённых восходящих пакетов, сеть подтвердила его), иначе False.

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

Ожидает нисходящий пакет. Возвращает None, если событие +RECV не было получено в течение timeout миллисекунд, иначе словарь {"port": str, "data": str}, содержащий FPort и байты полезной нагрузки.

Параметры:: timeout – Максимальное время ожидания, в миллисекундах.

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

Низкоуровневое чтение из UART. Считывает символы из модема, пока не будет найден разделитель, не будет прочитано max_bytes символов или не истечёт timeout миллисекунд, затем возвращает накопленную строку с удалённым завершающим \r.

Параметры:

delimiter – Либо одиночный символ для сопоставления в конце буфера, либо многосимвольная строка для сопоставления со всем обрезанным буфером, либо список таких строк.
max_bytes – Если задано, возвращает результат, как только будет прочитано ровно столько байтов.
timeout – Общий тайм-аут чтения, в миллисекундах.

available() → int¶: Возвращает количество байтов, доступных в данный момент в приёмном буфере UART модема.

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

Переключает модем в режим OTAA, программирует предоставленные ключи и EUI, затем пытается подключиться к сети. Возвращает True, если подключение удалось.

Параметры:

appEui – 64-битный Application/Join EUI в виде шестнадцатеричной строки.
appKey – 128-битный Application Key в виде шестнадцатеричной строки.
devEui – Необязательный 64-битный Device EUI в виде шестнадцатеричной строки. Если None, используется заводской Device EUI.
timeout – Тайм-аут подключения, в миллисекундах.

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

Переключает модем в режим ABP, программирует предоставленные адреса и ключи, затем пытается подключиться. Возвращает результат get_join_status().

Параметры:

nwkId – Идентификатор сети (в настоящее время игнорируется прошивкой).
devAddr – 32-битный адрес устройства (Device Address) в виде шестнадцатеричной строки.
nwkSKey – 128-битный сетевой сеансовый ключ (Network Session Key) в виде шестнадцатеричной строки.
appSKey – 128-битный сеансовый ключ приложения (Application Session Key) в виде шестнадцатеричной строки.
timeout – Тайм-аут подключения, в миллисекундах.

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

Анализирует ответ модема и возбуждает соответствующий подкласс LoraError, если он представляет ошибку. Ничего не делает для ответов без ошибок.

Параметры:

command – AT-команда (без префикса AT), которая породила data.
data – Строка ответа, возвращённая модемом.

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

Формирует AT-команду из cmd и args, при необходимости добавляет необработанную полезную нагрузку data, передаёт её и возвращает ответ модема. Для команд-запросов, заканчивающихся на ?, возвращается только часть со значением (подстрока после =).

Параметры:

cmd – Суффикс AT-команды (например, "+JOIN", "+DR="); префикс "AT" и завершающий \r добавляются автоматически.
args – Дополнительные аргументы, добавляемые к cmd после преобразования в строку.
delimiter – Разделитель, передаваемый методу receive().
data – Необязательные необработанные байты, записываемые сразу после AT-команды (используются для двоичных полезных нагрузок восходящих пакетов).
timeout – Тайм-аут ответа, в миллисекундах.
raise_error – Если True, ответы об ошибках преобразуются в исключения LoraError; если False, вызывающей стороне возвращается необработанный ответ.

lora — драйвер LoRa-модема¶

Константы¶

Режимы активации¶

Режимы RF-выхода¶

Диапазоны¶

Классы устройств¶

Исключения¶

Классы¶

`lora` — драйвер LoRa-модема¶