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, התגובה הגולמית מוחזרת לקורא.