lora --- Trình điều khiển modem LoRa#

Mô-đun lora cung cấp trình điều khiển cho modem LoRa Murata CMWX1ZZABZ trên Arduino Portenta Vision Shield. Nó cung cấp một lớp Lora cấp cao bao bọc tập lệnh AT được sử dụng bởi firmware modem (bao gồm cả firmware Arduino MKRWAN ARD-078) để ứng dụng có thể tham gia mạng LoRaWAN và gửi/nhận các gói tin.

Ví dụ:

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)

Hằng số#

Chế độ kích hoạt#

lora.MODE_ABP: int#

Chế độ Activation By Personalization.

lora.MODE_OTAA: int#

Chế độ Over-The-Air Activation.

Chế độ đầu ra RF#

lora.RF_MODE_RFO: int#

Sử dụng đầu ra RF RFO (công suất thấp) của modem.

lora.RF_MODE_PABOOST: int#

Sử dụng đầu ra RF PA_BOOST (công suất cao) của modem.

Dải tần#

lora.BAND_AS923: int#

Dải tần khu vực AS923 (Châu Á 923 MHz).

lora.BAND_AU915: int#

Dải tần khu vực AU915 (Úc 915 MHz).

lora.BAND_EU868: int#

Dải tần khu vực EU868 (Châu Âu 868 MHz).

lora.BAND_KR920: int#

Dải tần khu vực KR920 (Hàn Quốc 920 MHz).

lora.BAND_IN865: int#

Dải tần khu vực IN865 (Ấn Độ 865 MHz).

lora.BAND_US915: int#

Dải tần khu vực US915 (Hoa Kỳ 915 MHz).

lora.BAND_US915_HYBRID: int#

Kế hoạch khu vực US915 hybrid (dải con).

Lớp thiết bị#

lora.CLASS_A: str#

Thiết bị đầu cuối LoRaWAN Lớp A.

lora.CLASS_B: str#

Thiết bị đầu cuối LoRaWAN Lớp B.

lora.CLASS_C: str#

Thiết bị đầu cuối LoRaWAN Lớp C.

Ngoại lệ#

exception lora.LoraError#

Ngoại lệ cơ sở được ném ra cho bất kỳ lỗi nào được trả về bởi modem hoặc trình điều khiển.

exception lora.LoraErrorTimeout#

Được ném ra khi modem không phản hồi trong thời gian chờ đã cấu hình (bộ đệm nhận trống).

exception lora.LoraErrorParam#

Được ném ra khi nhận được phản hồi +ERR_PARAM khi một lệnh AT được phát ra với tham số không hợp lệ.

exception lora.LoraErrorBusy#

Được ném ra khi nhận được phản hồi +ERR_BUSY khi modem đang bận xử lý lệnh trước đó.

exception lora.LoraErrorOverflow#

Được ném ra khi nhận được phản hồi +ERR_PARAM_OVERFLOW khi một tham số vượt quá độ dài tối đa cho phép.

exception lora.LoraErrorNoNetwork#

Được ném ra khi nhận được phản hồi +ERR_NO_NETWORK khi modem chưa tham gia mạng.

exception lora.LoraErrorRX#

Được ném ra khi nhận được phản hồi +ERR_RX khi có lỗi xảy ra trong khi nhận downlink.

exception lora.LoraErrorUnknown#

Được ném ra khi nhận được phản hồi +ERR_UNKNOWN hoặc khi modem báo cáo lỗi không có tài liệu.

Lớp#

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

Tạo trình điều khiển modem mới. Hàm tạo khởi tạo (hoặc tự động tạo) UART và các chân reset/boot, reset phần cứng mô-đun, thực hiện đồng bộ hóa autobaud, khởi động lại mô-đun, truy vấn phiên bản firmware, và cấu hình band khu vực được yêu cầu.

Tham số:

  • uart -- Phiên bản machine.UART đã cấu hình sẵn dùng để giao tiếp với modem. Nếu là None, trình điều khiển sẽ mở UART(8, 19200) với khung 8N2 (mặc định của Portenta Vision Shield).

  • rst_pin -- machine.Pin điều khiển đường reset của modem. Nếu là None, "PC6" được cấu hình như một đầu ra push-pull.

  • boot_pin -- machine.Pin điều khiển đường chọn boot của modem. Nếu là None, "PG7" được cấu hình như một đầu ra push-pull kéo xuống thấp.

  • band -- Dải tần khu vực để cấu hình. Một trong các hằng số BAND_*.

  • poll_ms -- Khoảng thời gian tính bằng mili giây giữa các uplink trống tự động được kích hoạt bởi poll() để giữ cửa sổ downlink mở.

  • debug -- Khi là True, tất cả lưu lượng UART được in thông qua print().

LoraErrors: dict#

Ánh xạ từ các chuỗi phản hồi lỗi của modem (ví dụ: "+ERR_BUSY") đến lớp ngoại lệ tương ứng. Được sử dụng nội bộ bởi handle_error().

init_modem() → None#

Khởi tạo chậm self.uart, self.rst_pin và self.boot_pin về các giá trị mặc định của Portenta Vision Shield nếu chúng chưa được đặt. Được gọi từ hàm tạo; thường không được gọi trực tiếp bởi mã người dùng.

debug_print(data: str) → None#

In data nếu debug được bật lúc khởi tạo, ngược lại không làm gì.

is_arduino_firmware() → bool#

Trả về True nếu modem đang chạy firmware Arduino MKRWAN ARD-078 (được phát hiện từ chuỗi fw_version đã lưu trong bộ nhớ cache).

configure_class(_class: str) → None#

Cấu hình lớp thiết bị LoRaWAN.

Tham số:

_class -- Một trong các giá trị CLASS_A, CLASS_B, CLASS_C.

configure_band(band: int) → bool#

Cấu hình dải tần khu vực và, trên firmware Arduino với BAND_EU868, bật bộ giới hạn chu kỳ nhiệm vụ ETSI. Trả về True khi thành công.

Tham số:

band -- Một trong các hằng số BAND_*.

set_baudrate(baudrate: int) → None#

Thay đổi tốc độ baud UART của modem (AT+UART).

Tham số:

baudrate -- Tốc độ baud mới, tính bằng bit trên giây.

set_autobaud(timeout: int = 10000) → bool#

Gửi các lệnh AT trống cho đến khi modem phản hồi bằng +OK hoặc cho đến khi timeout mili giây trôi qua. Trả về True nếu đồng bộ hóa thành công.

Tham số:

timeout -- Thời gian tối đa để thử, tính bằng mili giây.

get_fw_version() → str#

Truy vấn chuỗi thiết bị modem (AT+DEV?) và phiên bản firmware (AT+VER?) và trả về chúng dưới dạng một chuỗi phân cách bằng khoảng trắng.

get_device_eui() → str#

Trả về EUI thiết bị 64-bit của modem dưới dạng chuỗi hex.

factory_default() → None#

Khôi phục cài đặt gốc thông qua AT+FACNEW.

restart() → None#

Đồng bộ hóa lại tốc độ baud, khởi động lại modem, đọc lại phiên bản firmware, và áp dụng lại dải tần khu vực đã cấu hình. Ném ra LoraError khi thất bại.

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

Cấu hình giai đoạn đầu ra RF của modem (AT+RFPOWER).

Tham số:

  • mode -- Một trong các giá trị RF_MODE_RFO, RF_MODE_PABOOST.

  • power -- Chỉ số công suất đầu ra, theo đơn vị dành riêng cho firmware.

set_port(port: int) → None#

Cấu hình cổng ứng dụng LoRaWAN (1..223) được sử dụng bởi các lệnh gọi send_data() tiếp theo.

Tham số:

port -- FPort của LoRaWAN.

set_public_network(enable: bool) → None#

Bật hoặc tắt từ đồng bộ hóa mạng công cộng.

Tham số:

enable -- True cho từ đồng bộ LoRaWAN công cộng, False cho từ đồng bộ riêng tư.

sleep(enable: bool) → None#

Đặt modem vào chế độ ngủ tiêu thụ điện thấp (True) hoặc đánh thức nó dậy (False).

format(hexMode: bool) → None#

Chọn định dạng dữ liệu được sử dụng qua UART cho các byte payload.

Tham số:

hexMode -- True cho định dạng payload ASCII-hex, False cho dạng nhị phân thô.

set_datarate(dr: int) → None#

Đặt chỉ số tốc độ dữ liệu LoRaWAN (AT+DR).

Tham số:

dr -- Chỉ số tốc độ dữ liệu theo từng khu vực.

get_datarate() → int#

Trả về chỉ số tốc độ dữ liệu LoRaWAN hiện tại.

set_adr(adr: bool) → None#

Bật hoặc tắt Adaptive Data Rate.

Tham số:

adr -- True để bật ADR, False để tắt.

get_adr() → int#

Trả về cài đặt ADR hiện tại (1 nếu được bật, 0 nếu không).

get_devaddr() → str#

Trả về DevAddr 32-bit hiện tại dưới dạng chuỗi hex.

get_nwk_skey() → str#

Trả về Network Session Key hiện tại dưới dạng chuỗi hex.

get_appskey() → str#

Trả về Application Session Key hiện tại dưới dạng chuỗi hex.

get_rx2dr() → int#

Trả về chỉ số tốc độ dữ liệu được sử dụng cho cửa sổ nhận RX2.

set_rx2dr(dr: int) → None#

Đặt chỉ số tốc độ dữ liệu được sử dụng cho cửa sổ nhận RX2.

Tham số:

dr -- Chỉ số tốc độ dữ liệu theo từng khu vực.

get_ex2freq() → int#

Trả về tần số, tính bằng Hz, được sử dụng cho cửa sổ nhận RX2.

set_rx2freq(freq: int) → None#

Đặt tần số được sử dụng cho cửa sổ nhận RX2.

Tham số:

freq -- Tần số tính bằng Hz.

set_fcu(fcu: int) → None#

Đặt bộ đếm khung hình uplink (AT+FCU).

Tham số:

fcu -- Giá trị bộ đếm khung hình uplink mới.

get_fcu() → int#

Trả về bộ đếm khung hình uplink hiện tại.

set_fcd(fcd: int) → None#

Đặt bộ đếm khung hình downlink (AT+FCD).

Tham số:

fcd -- Giá trị bộ đếm khung hình downlink mới.

get_fcd() → int#

Trả về bộ đếm khung hình downlink hiện tại.

change_mode(mode: int) → None#

Chuyển đổi chế độ kích hoạt.

Tham số:

mode -- Một trong các giá trị MODE_ABP, MODE_OTAA.

join(timeout_ms: int) → bool#

Phát lệnh AT+JOIN và chờ sự kiện join-accept. Trả về True nếu modem báo cáo +EVENT=1,1 (tham gia thành công) trong vòng timeout_ms.

Tham số:

timeout_ms -- Thời gian tối đa để chờ cả +ACK và sự kiện tham gia tiếp theo, tính bằng mili giây.

get_join_status() → bool#

Trả về True nếu modem hiện đang tham gia mạng.

get_max_size() → int#

Trả về kích thước payload LoRaWAN tối đa, tính bằng byte, cho tốc độ dữ liệu hiện tại. Trên firmware Arduino, giá trị này cố định là 64.

poll() → None#

Nếu hơn poll_ms mili giây đã trôi qua kể từ lần gọi cuối, gửi một uplink đã xác nhận trống để xả các downlink đang chờ. Dự kiến được gọi thường xuyên từ vòng lặp chính của ứng dụng.

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

Truyền một uplink LoRaWAN. Ném ra LoraError nếu buff lớn hơn get_max_size().

Tham số:

  • buff -- Các byte payload để truyền.

  • confirmed -- Khi là True, gửi một uplink đã xác nhận (+CTX) và chờ +ACK từ máy chủ mạng. Khi là False, gửi một uplink chưa xác nhận (+UTX).

Trả về:

True nếu modem chấp nhận gói tin (và, đối với uplink đã xác nhận, mạng đã xác nhận nó), False trong trường hợp khác.

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

Chờ một downlink. Trả về None nếu không có sự kiện +RECV nào được nhận trong vòng timeout mili giây, ngược lại trả về một dict {"port": str, "data": str} chứa FPort và các byte payload.

Tham số:

timeout -- Thời gian tối đa để chờ, tính bằng mili giây.

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

Đọc UART cấp thấp. Đọc các ký tự từ modem cho đến khi một dấu phân cách khớp, đã đọc đủ max_bytes ký tự, hoặc timeout mili giây trôi qua, sau đó trả về chuỗi đã tích lũy với bất kỳ ký tự \r ở cuối nào bị xóa bỏ.

Tham số:

  • delimiter -- Một ký tự đơn để khớp ở cuối bộ đệm, một chuỗi nhiều ký tự để khớp với toàn bộ bộ đệm đã được cắt xén, hoặc một danh sách các chuỗi như vậy.

  • max_bytes -- Nếu được đặt, trả về ngay khi đã đọc đúng bằng này số byte.

  • timeout -- Thời gian chờ đọc tổng thể, tính bằng mili giây.

available() → int#

Trả về số byte hiện có trong bộ đệm nhận UART của modem.

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

Chuyển modem sang chế độ OTAA, lập trình các khóa và EUI được cung cấp, sau đó cố gắng tham gia mạng. Trả về True nếu tham gia thành công.

Tham số:

  • appEui -- Application/Join EUI 64-bit dưới dạng chuỗi hex.

  • appKey -- Application Key 128-bit dưới dạng chuỗi hex.

  • devEui -- Device EUI 64-bit tùy chọn dưới dạng chuỗi hex. Nếu là None, Device EUI được lập trình tại nhà máy sẽ được sử dụng.

  • timeout -- Thời gian chờ tham gia, tính bằng mili giây.

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

Chuyển modem sang chế độ ABP, lập trình các địa chỉ và khóa được cung cấp, sau đó cố gắng tham gia. Trả về kết quả của get_join_status().

Tham số:

  • nwkId -- Định danh mạng (hiện tại bị firmware bỏ qua).

  • devAddr -- Device Address 32-bit dưới dạng chuỗi hex.

  • nwkSKey -- Network Session Key 128-bit dưới dạng chuỗi hex.

  • appSKey -- Application Session Key 128-bit dưới dạng chuỗi hex.

  • timeout -- Thời gian chờ tham gia, tính bằng mili giây.

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

Kiểm tra phản hồi của modem và ném ra lớp con LoraError phù hợp nếu nó đại diện cho một lỗi. Không làm gì với các phản hồi không phải lỗi.

Tham số:

  • command -- Lệnh AT (không có tiền tố AT) đã tạo ra data.

  • data -- Chuỗi phản hồi được trả về bởi modem.

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

Xây dựng một lệnh AT từ cmd và args, tùy chọn thêm payload data thô, truyền nó, và trả về phản hồi của modem. Đối với các lệnh truy vấn kết thúc bằng ?, chỉ phần giá trị (chuỗi con sau =) được trả về.

Tham số:

  • cmd -- Hậu tố lệnh AT (ví dụ: "+JOIN", "+DR="); tiền tố "AT" và \r ở cuối được thêm tự động.

  • args -- Các đối số bổ sung được nối vào cmd sau khi chuyển đổi chuỗi.

  • delimiter -- Dấu phân cách được chuyển tiếp đến receive().

  • data -- Các byte thô tùy chọn được ghi ngay sau lệnh AT (được sử dụng cho payload uplink nhị phân).

  • timeout -- Thời gian chờ phản hồi, tính bằng mili giây.

  • raise_error -- Khi là True, các phản hồi lỗi được chuyển đổi thành ngoại lệ LoraError; khi là False, phản hồi thô được trả về cho người gọi.