`lora` --- LoRa 數據機驅動程式¶

lora 模組為 Arduino Portenta Vision Shield 上的 Murata CMWX1ZZABZ LoRa 數據機提供驅動程式。它公開了一個高階的 Lora 類別，用於封裝數據機韌體（包含 Arduino MKRWAN ARD-078 韌體）所使用的 AT 命令集，使應用程式能夠加入 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¶: 使用數據機的 RFO（低功率）RF 輸出。

lora.RF_MODE_PABOOST: int¶: 使用數據機的 PA_BOOST（高功率）RF 輸出。

頻段¶

lora.BAND_AS923: int¶: AS923（亞洲 923 MHz）區域頻段。

lora.BAND_AU915: int¶: AU915（澳洲 915 MHz）區域頻段。

lora.BAND_EU868: int¶: EU868（歐洲 868 MHz）區域頻段。

lora.BAND_KR920: int¶: KR920（韓國 920 MHz）區域頻段。

lora.BAND_IN865: int¶: IN865（印度 865 MHz）區域頻段。

lora.BAND_US915: int¶: US915（美國 915 MHz）區域頻段。

lora.BAND_US915_HYBRID: int¶: US915 hybrid（子頻段）區域計畫。

裝置類別¶

lora.CLASS_A: str¶: LoRaWAN 端裝置 Class A。

lora.CLASS_B: str¶: LoRaWAN 端裝置 Class B。

lora.CLASS_C: str¶: LoRaWAN 端裝置 Class C。

例外¶

exception lora.LoraError¶: 由數據機或驅動程式回傳的任何錯誤所引發的基礎例外。

exception lora.LoraErrorTimeout¶: 當數據機在設定的逾時時間內未回應時引發（接收緩衝區為空）。

exception lora.LoraErrorParam¶: 當以無效參數發出 AT 命令而收到 +ERR_PARAM 回應時引發。

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 與 reset/boot 接腳、對模組進行硬體重設、執行自動鮑率同步、重新啟動模組、查詢其韌體版本，並設定所要求的區域 band。

參數:

uart -- 用於與數據機通訊的預先設定 machine.UART 實例。若為 None，驅動程式會以 8N2 框架開啟 UART(8, 19200)（Portenta Vision Shield 的預設值）。
rst_pin -- 驅動數據機 reset 線路的 machine.Pin。若為 None，則將 "PC6" 設定為推挽式輸出。
boot_pin -- 驅動數據機 boot-select 線路的 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¶: 若在建構時啟用了 debug，則列印 data，否則不執行任何動作。

is_arduino_firmware() → bool¶: 若數據機正在執行 Arduino MKRWAN ARD-078 韌體（從快取的 fw_version 字串偵測），則回傳 True。

configure_class(_class: str) → None¶

設定 LoRaWAN 裝置類別。

參數:: _class -- CLASS_A、CLASS_B、CLASS_C 之一。

configure_band(band: int) → bool¶

設定區域頻段，並在使用 BAND_EU868 的 Arduino 韌體上啟用 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¶

設定後續 send_data() 呼叫所使用的 LoRaWAN 應用程式埠（1..223）。

參數:: port -- LoRaWAN FPort。

set_public_network(enable: bool) → None¶

啟用或停用公用網路同步字。

參數:: enable -- True 代表公用 LoRaWAN 同步字，False 代表私用的。

sleep(enable: bool) → None¶: 將數據機置於低功率睡眠（True）或將其喚醒（False）。

format(hexMode: bool) → None¶

選擇透過 UART 用於酬載位元組的資料格式。

參數:: hexMode -- True 代表 ASCII 十六進位酬載格式，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 接收視窗的頻率，以 Hz 為單位。

set_rx2freq(freq: int) → None¶

設定用於 RX2 接收視窗的頻率。

參數:: freq -- 頻率，以 Hz 為單位。

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 並等待 join-accept 事件。若數據機在 timeout_ms 內回報 +EVENT=1,1（加入成功），則回傳 True。

參數:: 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 上行鏈路。若 buff 大於 get_max_size()，則引發 LoraError。

參數:

buff -- 要傳送的酬載位元組。
confirmed -- 當為 True 時，傳送已確認的上行鏈路（+CTX）並等待網路伺服器的 +ACK。當為 False 時，傳送未確認的上行鏈路（+UTX）。

回傳:

若數據機接受了該封包（且對於已確認的上行鏈路，網路已確認該封包），則回傳 True，否則回傳 False。

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

等待下行鏈路。若在 timeout 毫秒內未收到 +RECV 事件，則回傳 None，否則回傳一個包含 FPort 與酬載位元組的字典 {"port": str, "data": str}。

參數:: 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 -- 產生 data 的 AT 命令（不含 AT 前綴）。
data -- 數據機回傳的回應字串。

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

從 cmd 與 args 建構一個 AT 命令，選擇性地附加原始 data 酬載，傳送它，並回傳數據機的回應。對於以 ? 結尾的查詢命令，只會回傳值的部分（= 之後的子字串）。

參數:

cmd -- AT 命令後綴（例如 "+JOIN"、"+DR="）；"AT" 前綴與結尾的 \r 會自動加入。
args -- 經字串轉換後串接到 cmd 之後的額外引數。
delimiter -- 轉發給 receive() 的分隔符號。
data -- 緊接在 AT 命令之後寫入的選用原始位元組（用於二進位上行鏈路酬載）。
timeout -- 回應逾時，以毫秒為單位。
raise_error -- 當為 True 時，錯誤回應會轉換為 LoraError 例外；當為 False 時，原始回應會回傳給呼叫者。

lora --- LoRa 數據機驅動程式¶

常數¶

啟用模式¶

RF 輸出模式¶

頻段¶

裝置類別¶

例外¶

類別¶

`lora` --- LoRa 數據機驅動程式¶