`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¶: Режим активації за персоналізацією (ABP).

lora.MODE_OTAA: int¶: Режим активації через ефір (OTAA).

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

lora.RF_MODE_RFO: int¶: Використовувати RFO (малопотужний) RF-вихід модему.

lora.RF_MODE_PABOOST: int¶: Використовувати PA_BOOST (високопотужний) RF-вихід модему.

Діапазони¶

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" налаштовується як push-pull вихід.
boot_pin – machine.Pin для керування лінією вибору режиму завантаження модему. Якщо None, "PG7" налаштовується як push-pull вихід із підтяжкою до низького рівня.
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-бітний EUI пристрою модему у вигляді hex-рядка.

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¶

Увімкнути або вимкнути адаптивну швидкість передачі даних (ADR).

Параметри:: adr – True для увімкнення ADR, False для вимкнення.

get_adr() → int¶: Повернути поточне налаштування ADR (1 якщо увімкнено, 0 в іншому випадку).

get_devaddr() → str¶: Повернути поточний 32-бітний DevAddr у вигляді hex-рядка.

get_nwk_skey() → str¶: Повернути поточний мережевий сесійний ключ у вигляді hex-рядка.

get_appskey() → str¶: Повернути поточний сесійний ключ застосунку у вигляді hex-рядка.

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-бітний EUI застосунку/приєднання у вигляді hex-рядка.
appKey – 128-бітний ключ застосунку у вигляді hex-рядка.
devEui – Необов’язковий 64-бітний EUI пристрою у вигляді hex-рядка. Якщо None, використовується запрограмований на заводі EUI пристрою.
timeout – Таймаут приєднання, у мілісекундах.

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

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

Параметри:

nwkId – Мережевий ідентифікатор (наразі ігнорується мікропрограмою).
devAddr – 32-бітна адреса пристрою у вигляді hex-рядка.
nwkSKey – 128-бітний мережевий сесійний ключ у вигляді hex-рядка.
appSKey – 128-бітний сесійний ключ застосунку у вигляді hex-рядка.
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-модему¶