lora --- ไดรเวอร์โมเด็ม LoRa

โมดูล lora เป็นไดรเวอร์สำหรับโมเด็ม LoRa รุ่น Murata CMWX1ZZABZ บน Arduino Portenta Vision Shield โดยเปิดเผยคลาส Lora ระดับสูงที่ห่อหุ้มชุดคำสั่ง AT ที่โมเด็มเฟิร์มแวร์ใช้งาน (รวมถึงเฟิร์มแวร์ ARD-078 ของ Arduino MKRWAN) เพื่อให้แอปพลิเคชันสามารถเชื่อมต่อกับเครือข่าย 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 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 end-device Class A

lora.CLASS_B: str

LoRaWAN end-device Class B

lora.CLASS_C: str

LoRaWAN end-device Class 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 เมื่อเกิดข้อผิดพลาดระหว่างรับ downlink

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 และพินรีเซ็ต/บูต รีเซ็ตฮาร์ดแวร์ของโมดูล ทำการซิงโครไนซ์ autobaud รีบูตโมดูล สอบถามเวอร์ชันเฟิร์มแวร์ และกำหนดค่า band ตามภูมิภาคที่ระบุ

พารามิเตอร์:

• uart -- อินสแตนซ์ machine.UART ที่กำหนดค่าไว้ล่วงหน้าสำหรับสื่อสารกับโมเด็ม หาก None ไดรเวอร์จะเปิด UART(8, 19200) พร้อม framing แบบ 8N2 (ค่าเริ่มต้นของ Portenta Vision Shield)

• rst_pin -- machine.Pin ที่ขับเส้น reset ของโมเด็ม หาก None จะกำหนดค่า "PC6" เป็นเอาต์พุต push-pull

• boot_pin -- machine.Pin ที่ขับเส้น boot-select ของโมเด็ม หาก None จะกำหนดค่า "PG7" เป็นเอาต์พุต push-pull แบบ pull-low

• band -- แบนด์ความถี่ตามภูมิภาคที่ต้องการกำหนดค่า ระบุค่าคงที่ BAND_* ตัวใดตัวหนึ่ง

• poll_ms -- ช่วงเวลาเป็นมิลลิวินาทีระหว่าง uplink ว่างที่ส่งโดยอัตโนมัติซึ่งเรียกจาก poll() เพื่อรักษาหน้าต่างรับ downlink ให้เปิดอยู่

• debug -- เมื่อเป็น True ทราฟฟิก UART ทั้งหมดจะถูกพิมพ์ผ่าน print()

LoraErrors: dict

การแมปจากสตริงการตอบสนองข้อผิดพลาดของโมเด็ม (เช่น "+ERR_BUSY") ไปยังคลาสข้อยกเว้นที่สอดคล้องกัน ใช้ภายในโดย handle_error()

init_modem() → None

เริ่มต้น self.uart, self.rst_pin และ self.boot_pin แบบ lazy ให้เป็นค่าเริ่มต้นของ 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 duty-cycle limiter ด้วย คืนค่า 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

คืนค่า Device EUI 64 บิตของโมเด็มเป็นสตริงฐานสิบหก

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 application port (1..223) ที่ใช้โดยการเรียก send_data() ถัดไป

พารามิเตอร์:

port -- LoRaWAN FPort

set_public_network(enable: bool) → None

เปิดหรือปิดใช้งาน sync word สำหรับเครือข่ายสาธารณะ

พารามิเตอร์:

enable -- True สำหรับ LoRaWAN sync word สาธารณะ, False สำหรับแบบส่วนตัว

sleep(enable: bool) → None

ทำให้โมเด็มเข้าสู่โหมดพักกำลังต่ำ (True) หรือปลุกให้ทำงาน (False)

format(hexMode: bool) → None

เลือกรูปแบบข้อมูลที่ใช้ผ่าน UART สำหรับไบต์เพย์โหลด

พารามิเตอร์:

hexMode -- True สำหรับรูปแบบเพย์โหลด ASCII-hex, False สำหรับแบบ raw binary

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

คืนค่า DevAddr 32 บิตปัจจุบันเป็นสตริงฐานสิบหก

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

คืนค่าความถี่ในหน่วย Hz ที่ใช้สำหรับหน้าต่างรับ RX2

set_rx2freq(freq: int) → None

ตั้งค่าความถี่ที่ใช้สำหรับหน้าต่างรับ RX2

พารามิเตอร์:

freq -- ความถี่ในหน่วย Hz

set_fcu(fcu: int) → None

ตั้งค่าตัวนับเฟรม uplink (AT+FCU)

พารามิเตอร์:

fcu -- ค่าตัวนับเฟรม uplink ใหม่

get_fcu() → int

คืนค่าตัวนับเฟรม uplink ปัจจุบัน

set_fcd(fcd: int) → None

ตั้งค่าตัวนับเฟรม downlink (AT+FCD)

พารามิเตอร์:

fcd -- ค่าตัวนับเฟรม downlink ใหม่

get_fcd() → int

คืนค่าตัวนับเฟรม downlink ปัจจุบัน

change_mode(mode: int) → None

สลับโหมดการเปิดใช้งาน

พารามิเตอร์:

mode -- ระบุค่าใดค่าหนึ่งจาก MODE_ABP, MODE_OTAA

join(timeout_ms: int) → bool

ส่งคำสั่ง AT+JOIN และรอสัญญาณ join-accept คืนค่า True หากโมเด็มรายงาน +EVENT=1,1 (เชื่อมต่อสำเร็จ) ภายใน timeout_ms

พารามิเตอร์:

timeout_ms -- เวลาสูงสุดในการรอทั้ง +ACK และสัญญาณ join ที่ตามมา เป็นมิลลิวินาที

get_join_status() → bool

คืนค่า True หากโมเด็มเชื่อมต่อกับเครือข่ายอยู่ในขณะนี้

get_max_size() → int

คืนค่าขนาดเพย์โหลด LoRaWAN สูงสุดเป็นไบต์สำหรับอัตราข้อมูลปัจจุบัน บนเฟิร์มแวร์ Arduino ค่านี้กำหนดคงที่ที่ 64

poll() → None

หากผ่านมาเกิน poll_ms มิลลิวินาทีนับตั้งแต่การเรียกครั้งล่าสุด ให้ส่ง confirmed uplink ว่างเพื่อล้าง downlink ที่ค้างอยู่ ควรเรียกบ่อยๆ จาก main loop ของแอปพลิเคชัน

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

ส่ง LoRaWAN uplink ยก LoraError หาก buff มีขนาดใหญ่กว่าที่ get_max_size() ระบุ

พารามิเตอร์:

• buff -- ไบต์เพย์โหลดที่จะส่ง

• confirmed -- เมื่อเป็น True ส่ง confirmed uplink (+CTX) และรอ +ACK จาก network server เมื่อเป็น False ส่ง unconfirmed uplink (+UTX)

ค่าที่คืน:

True หากโมเด็มรับแพ็กเก็ตไว้ (และสำหรับ confirmed uplink เครือข่ายได้รับทราบแล้ว), False มิฉะนั้น

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

รอรับ downlink คืนค่า None หากไม่ได้รับสัญญาณ +RECV ภายใน timeout มิลลิวินาที หรือคืน dict {"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 ตั้งค่า keys และ EUI ที่ระบุ แล้วพยายามเชื่อมต่อเครือข่าย คืนค่า True หากเชื่อมต่อสำเร็จ

พารามิเตอร์:

• appEui -- Application/Join EUI 64 บิตเป็นสตริงฐานสิบหก

• appKey -- Application Key 128 บิตเป็นสตริงฐานสิบหก

• devEui -- Device EUI 64 บิตที่ไม่บังคับเป็นสตริงฐานสิบหก หาก None จะใช้ Device EUI ที่โปรแกรมจากโรงงาน

• timeout -- ระยะเวลาหมดเวลาการเชื่อมต่อ เป็นมิลลิวินาที

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

สลับโมเด็มเป็นโหมด ABP ตั้งค่าที่อยู่และ keys ที่ระบุ แล้วพยายามเชื่อมต่อ คืนค่าผลลัพธ์ของ get_join_status()

พารามิเตอร์:

• nwkId -- ตัวระบุเครือข่าย (ปัจจุบันถูกเฟิร์มแวร์ละเว้น)

• devAddr -- Device Address 32 บิตเป็นสตริงฐานสิบหก

• nwkSKey -- Network Session Key 128 บิตเป็นสตริงฐานสิบหก

• appSKey -- Application Session Key 128 บิตเป็นสตริงฐานสิบหก

• 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 เพย์โหลด raw ตามต้องการ ส่งคำสั่ง และคืนการตอบสนองของโมเด็ม สำหรับคำสั่งสอบถามที่ลงท้ายด้วย ? จะคืนเฉพาะส่วนค่า (สตริงหลัง =)

พารามิเตอร์:

• cmd -- คำต่อท้ายคำสั่ง AT (เช่น "+JOIN", "+DR="); คำนำหน้า "AT" และ \r ท้ายจะถูกเพิ่มโดยอัตโนมัติ

• args -- อาร์กิวเมนต์เพิ่มเติมที่ต่อท้าย cmd หลังจากแปลงเป็นสตริง

• delimiter -- ตัวคั่นที่ส่งต่อไปยัง receive()

• data -- ไบต์ raw ที่ไม่บังคับซึ่งเขียนทันทีหลังคำสั่ง AT (ใช้สำหรับเพย์โหลด uplink แบบ binary)

• timeout -- ระยะเวลาหมดเวลาการตอบสนอง เป็นมิลลิวินาที

• raise_error -- เมื่อเป็น True การตอบสนองข้อผิดพลาดจะถูกแปลงเป็นข้อยกเว้น LoraError; เมื่อเป็น False จะคืนการตอบสนองดิบให้ผู้เรียก