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 (הספק גבוה) של המודם.

תחומים (Bands)

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 היברידית (תת-תחום).

מחלקות התקן

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

מועלית בתגובת +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) עם מסגור 8N2 (ברירת המחדל של ה-Portenta Vision Shield).

• rst_pin – מופע machine.Pin המניע את קו האיפוס של המודם. אם None, "PC6" מוגדר כפלט דחיפה-משיכה (push-pull).

• boot_pin – מופע machine.Pin המניע את קו בחירת האתחול (boot-select) של המודם. אם None, "PG7" מוגדר כפלט דחיפה-משיכה (push-pull) המושך כלפי מטה.

• band – התחום האזורי שיוגדר. אחד מהקבועים BAND_*.

• poll_ms – מרווח במילישניות בין קישורי-עולה (uplinks) ריקים אוטומטיים המופעלים על ידי poll() כדי לשמור את חלון הקישור-יורד פתוח.

• debug – כאשר True, כל תעבורת ה-UART מודפסת באמצעות print().

LoraErrors: dict

מיפוי ממחרוזות תגובת שגיאה של המודם (לדוגמה "+ERR_BUSY") למחלקת החריגה המתאימה. משמש באופן פנימי על ידי handle_error().

init_modem() → None

מאתחל באופן עצל (lazy) את 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, מפעיל את מגביל מחזור-העבודה (duty-cycle) של ETSI. מחזיר True בהצלחה.

פרמטרים:

band – אחד מהקבועים BAND_*.

set_baudrate(baudrate: int) → None

משנה את קצב הבָּאוּד (baud rate) של ה-UART של המודם (AT+UART).

פרמטרים:

baudrate – קצב בָּאוּד (baud rate) חדש, בביטים לשנייה.

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

מסנכרן מחדש את קצב הבָּאוּד (baud rate), מאתחל מחדש את המודם, קורא מחדש את גרסת הקושחה, ומיישם מחדש את התחום האזורי שהוגדר. מעלה 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 – LoRaWAN FPort.

set_public_network(enable: bool) → None

מפעיל או מבטל את מילת הסנכרון (sync word) של הרשת הציבורית.

פרמטרים:

enable – True עבור מילת הסנכרון הציבורית של LoRaWAN, False עבור הפרטית.

sleep(enable: bool) → None

מכניס את המודם למצב שינה בהספק נמוך (True) או מעיר אותו (False).

format(hexMode: bool) → None

בוחר את תבנית הנתונים המשמשת על גבי ה-UART עבור בייטי המטען (payload).

פרמטרים:

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

מחזיר את ה-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 והן לאירוע ההצטרפות שלאחריו, במילישניות.

get_join_status() → bool

מחזיר True אם המודם מחובר כעת לרשת.

get_max_size() → int

מחזיר את גודל המטען (payload) המרבי של LoRaWAN, בבייטים, עבור קצב הנתונים הנוכחי. בקושחת Arduino ערך זה קבוע על 64.

poll() → None

אם חלפו יותר מ-poll_ms מילישניות מאז הקריאה האחרונה, שולח קישור-עולה (uplink) מאושר ריק כדי לרוקן קישורי-יורד (downlinks) ממתינים. מיועד להיקרא לעיתים תכופות מהלולאה הראשית של היישום.

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

משדר קישור-עולה (uplink) של LoRaWAN. מעלה LoraError אם buff גדול מ-get_max_size().

פרמטרים:

• buff – בייטי המטען (payload) לשידור.

• confirmed – כאשר True, שולח קישור-עולה (uplink) מאושר (+CTX) וממתין ל-+ACK משרת הרשת. כאשר False, שולח קישור-עולה (uplink) לא מאושר (+UTX).

מחזיר:

True אם המודם קיבל את המנה (ועבור קישורי-עולה (uplinks) מאושרים, הרשת אישרה אותה), False אחרת.

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

ממתין לקישור-יורד (downlink). מחזיר None אם לא התקבל אירוע +RECV בתוך timeout מילישניות, אחרת מילון {"port": str, "data": str} המכיל את ה-FPort ואת בייטי המטען (payload).

פרמטרים:

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, מתכנת את המפתחות וה-EUIs שסופקו, ואז מנסה להצטרף לרשת. מחזיר 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, מתכנת את הכתובות והמפתחות שסופקו, ואז מנסה להצטרף. מחזיר את תוצאת 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 גולמי, משדר אותה, ומחזיר את תגובת המודם. עבור פקודות שאילתה המסתיימות ב-?, מוחזר רק חלק הערך (תת-המחרוזת שאחרי =).

פרמטרים:

• cmd – סיומת פקודת AT (לדוגמה "+JOIN", "+DR="); הקידומת "AT" ו-\r העוקב מתווספים אוטומטית.

• args – ארגומנטים נוספים המשורשרים ל-cmd לאחר המרה למחרוזת.

• delimiter – תו מפריד המועבר ל-receive().

• data – בייטים גולמיים אופציונליים הנכתבים מיד לאחר פקודת ה-AT (משמשים למטעני קישור-עולה (uplink) בינאריים).

• timeout – פרק הזמן הקצוב לתגובה, במילישניות.

• raise_error – כאשר True, תגובות שגיאה מומרות לחריגות LoraError; כאשר False, התגובה הגולמית מוחזרת לקורא.