network — הגדרת רשת

מודול זה מספק מנהלי התקן לרשת והגדרת ניתוב. כדי להשתמש במודול זה, יש להתקין וריאנט/בנייה של MicroPython עם יכולות רשת. מנהלי התקן לרשת עבור חומרה ספציפית זמינים בתוך מודול זה ומשמשים להגדרת ממשק(י) רשת חומרתיים. שירותי הרשת המסופקים על ידי הממשקים המוגדרים זמינים אז לשימוש דרך המודול socket.

לדוגמה:

import network
import socket
import time

nic = network.WLAN(network.WLAN.IF_STA)
nic.active(True)
nic.connect("your-ssid", "your-key")

print("Waiting for connection...")
while not nic.isconnected():
    time.sleep(1)
print(nic.ipconfig("addr4"))

# Open a TCP socket as usual.
addr = socket.getaddrinfo("micropython.org", 80)[0][-1]
s = socket.socket()
s.connect(addr)
s.send(b"GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n")
data = s.recv(1000)
s.close()

החלף את WLAN ב-WINC (מגן WiFi ישן) או ב-LAN (Ethernet מובנה) כמתאים למצלמה. התבנית ברמה הגבוהה של בנייה -> הפעלה -> חיבור -> שימוש בשקעים (sockets) זהה בכל שלושת המקרים.

ממשק מתאם רשת משותף

סעיף זה מתאר מחלקת בסיס מופשטת (מרומזת) עבור כל מחלקות ממשק הרשת המיושמות על ידי MicroPython ports עבור חומרה שונה. משמעות הדבר היא ש-MicroPython אינו מספק בפועל מחלקת AbstractNIC, אך כל מחלקת NIC ממשית, כמתואר בסעיפים הבאים, מממשת מתודות כמתואר כאן.

class network.AbstractNIC(id: int | None = None, *args: Any, **kwargs: Any) → None

יצירת מופע של אובייקט ממשק רשת. הפרמטרים תלויים בממשק הרשת. אם קיים יותר מממשק אחד מאותו סוג, הפרמטר הראשון צריך להיות id.

active(is_active: bool | None = None, /) → bool

הפעלת או כיבוי ממשק הרשת.

ללא ארגומנט, מוחזר המצב הנוכחי – True כאשר הממשק פעיל, False אחרת.

העבר True כדי להפעיל את הממשק: הפעל / אפס את בקר הרשת הבסיסי, טען קושחה במקום בו ישים, והפעל את מחסנית ה-IP בממשק זה. קריאות עוקבות המתקשרות עם הרשת (connect(), scan(), ipconfig(), …) דורשות שהממשק יהיה פעיל.

העבר False כדי להשבית את הממשק: פרק את מחסנית ה-IP ושחרר את משאבי מנהל ההתקן. בממשקים אלחוטיים פעולה זו גם מבטלת את השיוך מכל רשת המצורפת כעת.

ההתנהגות של קריאה למתודות אחרות בממשק לא פעיל אינה מוגדרת.

connect(service_id: str | None = None, key: str | None = None, *, bssid: bytes | None = None, **kwargs: Any) → None

חיבור הממשק לרשת. מתודה זו אופציונלית, וזמינה רק עבור ממשקים שאינם ”מחוברים תמיד“. אם לא ניתנים פרמטרים, התחבר לשירות ברירת המחדל (או היחיד). אם ניתן פרמטר יחיד, הוא המזהה הראשי של שירות להתחבר אליו. הוא עשוי להיות מלווה במפתח (סיסמה) הנדרש לגישה לאותו שירות. ייתכנו פרמטרים נוספים שרירותיים מסוג מילת מפתח בלבד, בהתאם לסוג מדיום הרשת ו/או למכשיר מסוים. ניתן להשתמש בפרמטרים כדי: א) לציין סוגי מזהי שירות חלופיים; ב) לספק פרמטרי חיבור נוספים. עבור סוגי מדיום שונים, קיימות קבוצות שונות של פרמטרים מוגדרים מראש/מומלצים, ובהן:

  • WiFi: מילת המפתח bssid כדי להתחבר ל-BSSID ספציפי (כתובת MAC)

disconnect() → None

ניתוק מהרשת.

isconnected() → bool

מוחזר True אם קיים חיבור לרשת, אחרת מוחזר False.

scan(**kwargs: Any) → List[Tuple]

סריקה לאיתור שירותי/חיבורי הרשת הזמינים. מוחזרת רשימה של רביעיות עם פרמטרי השירות שהתגלו. עבור מדיות רשת שונות, קיימות וריאציות שונות של פורמטי רביעיות מוגדרים מראש/מומלצים, ובהן:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). ייתכנו שדות נוספים, ספציפיים למכשיר מסוים.

הפונקציה עשויה לקבל ארגומנטי מילות מפתח נוספים כדי לסנן את תוצאות הסריקה (למשל סריקה עבור שירות מסוים, בערוץ מסוים, עבור שירותים של קבוצה מסוימת וכו«), וכדי להשפיע על משך הסריקה ועל פרמטרים אחרים. במקום שבו אפשר, שמות הפרמטרים צריכים להתאים לאלה שב-connect().

status(param: str | None = None) → Any

שאילתת מידע סטטוס דינמי של הממשק. כאשר נקראת ללא ארגומנט הערך המוחזר מתאר את סטטוס קישור הרשת. אחרת param צריך להיות מחרוזת המציינת את פרמטר הסטטוס המסוים שיש לאחזר.

סוגי הערכים המוחזרים והערכים תלויים במדיום/בטכנולוגיה של הרשת. חלק מהפרמטרים שעשויים להיתמך הם:

  • WiFi STA: השתמש ב-'rssi' כדי לאחזר את ה-RSSI של אות ה-AP

  • WiFi AP: השתמש ב-'stations' כדי לאחזר רשימה של כל ה-STA-ים המחוברים ל-AP. הרשימה מכילה רביעיות מהצורה (MAC, RSSI).

ipconfig(param: str) → Any
ipconfig(**kwargs: Any) → None

קבלה או הגדרה של פרמטרי הגדרת IP ספציפיים לממשק. הפרמטרים הנתמכים הם הבאים (זמינות פרמטר מסוים תלויה ב-port ובממשק הרשת הספציפי):

  • dhcp4 (True/False) השג כתובת IPv4, שער ושרת dns דרך DHCP. מתודה זו אינה חוסמת ואינה ממתינה להשגת כתובת. כדי לבדוק אם הושגה כתובת, השתמש במאפיין לקריאה בלבד has_dhcp4.

  • gw4 קבלה/הגדרה של שער ברירת המחדל של IPv4.

  • dhcp6 (True/False) השג שרת DNS דרך DHCPv6 חסר מצב. השגת כתובות IP דרך DHCPv6 אינה ממומשת כעת.

  • autoconf6 (True/False) השג כתובת IPv6 חסרת מצב דרך תחילית הרשת המשותפת בהכרזות הנתב. כדי לבדוק אם הושגה כתובת חסרת מצב, השתמש במאפיין לקריאה בלבד has_autoconf6.

  • addr4 (למשל 192.168.0.4/24) השג את כתובת ה-IPv4 הנוכחית ואת מסיכת הרשת כרביעייה (ip, subnet), ללא קשר לאופן השגת כתובת זו. ניתן להשתמש במתודה זו כדי להגדיר כתובת IPv4 סטטית, או כרביעייה (ip, subnet) או בסימון CIDR.

  • addr6 (למשל fe80::1234:5678) השג רשימה של כתובות IPv6 נוכחיות כרביעייה (ip, state, preferred_lifetime, valid_lifetime). זה כולל כתובות link-local, slaac וסטטיות. preferred_lifetime ו-valid_lifetime מייצגים את משך החיים התקף והמועדף הנותר של כל כתובת IPv6, בשניות. state מציין את המצב הנוכחי של הכתובת:

    • 0x08 - 0x0f מציין שהכתובת ניסיונית, ומונה את מספר הבדיקות שנשלחו.

    • 0x10 הכתובת הוצאה משימוש (אך עדיין תקפה)

    • 0x30 הכתובת מועדפת (ותקפה)

    • 0x40 הכתובת כפולה ולא ניתן להשתמש בה.

    ניתן להשתמש במתודה זו כדי להגדיר כתובת IPv6 סטטית, על ידי הגדרת פרמטר זה לכתובת, כמו fe80::1234:5678.

ifconfig(config: Tuple[str, str, str, str] | None = None) → Tuple[str, str, str, str] | None

הערה

פונקציה זו הוצאה משימוש, השתמש ב-ipconfig() במקום.

קבלה/הגדרה של פרמטרי ממשק רשת ברמת ה-IP: כתובת IP, מסיכת רשת, שער ושרת DNS. כאשר נקראת ללא ארגומנטים, מתודה זו מחזירה רביעייה עם המידע הנ“ל. כדי להגדיר את הערכים הנ“ל, העבר רביעייה עם המידע הנדרש. לדוגמה:

nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
config(param: str) → Any
config(**kwargs: Any) → None

קבלה או הגדרה של פרמטרי ממשק רשת כלליים. מתודות אלה מאפשרות לעבוד עם פרמטרים נוספים מעבר להגדרת ה-IP הסטנדרטית (כפי שמטופלת על ידי ipconfig()). אלה כוללים פרמטרים ספציפיים לרשת וספציפיים לחומרה. להגדרת פרמטרים, יש להשתמש בתחביר ארגומנט מילת מפתח, וניתן להגדיר מספר פרמטרים בבת אחת. לשם שאילתה, יש לצטט שם פרמטר כמחרוזת, וניתן לבצע שאילתה על פרמטר אחד בלבד בכל פעם:

# Set WiFi access point name (formally known as SSID) and WiFi channel
ap.config(ssid='My AP', channel=11)
# Query params one by one
print(ap.config('ssid'))
print(ap.config('channel'))

מימושי מחלקות רשת ספציפיים

המחלקות הקונקרטיות הבאות מממשות את ממשק AbstractNIC ומספקות דרך לשלוט בממשקי רשת מסוגים שונים.

פונקציות רשת

להלן הפונקציות הזמינות במודול network.

network.country(code: str | None = None) → str | None

קבלה או הגדרה של קוד המדינה ISO 3166-1 Alpha-2 בן שתי האותיות שישמש לתאימות רדיו.

אם הפרמטר code מסופק, המדינה תוגדר לערך זה. אם הפונקציה נקראת ללא פרמטרים, מוחזרת המדינה הנוכחית.

קוד ברירת המחדל "XX" מייצג את האזור ”העולמי“.

network.hostname(name: str | None = None) → str | None

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

שם מארח זה משמש עבור:

  • שליחה לשרת ה-DHCP בבקשת הלקוח. (אם משתמשים ב-DHCP)

  • שידור דרך mDNS. (אם מופעל)

אם הפרמטר name מסופק, שם המארח יוגדר לערך זה. אם הפונקציה נקראת ללא פרמטרים, מוחזר שם המארח הנוכחי.

שינוי בשם המארח מיושם בדרך כלל רק במהלך החיבור. עבור DHCP זאת משום ששם המארח הוא חלק מבקשת לקוח ה-DHCP, ומימוש ה-mDNS ברוב ה-ports מאתחל את שם המארח רק פעם אחת במהלך החיבור. מסיבה זו, עליך להגדיר את שם המארח לפני הפעלת/חיבור ממשקי הרשת שלך.

אורך שם המארח מוגבל ל-32 תווים. MicroPython ports עשויים לבחור להגדיר מגבלה נמוכה יותר מטעמי זיכרון. אם השם הנתון אינו מתאים, מועלית שגיאת ValueError.

שם המארח של ברירת המחדל הוא בדרך כלל שם הלוח.

network.ipconfig(param: str) → Any
network.ipconfig(**kwargs: Any) → None

קבלה או הגדרה של פרמטרי הגדרת IP גלובליים. הפרמטרים הנתמכים הם הבאים (זמינות פרמטר מסוים תלויה ב-port ובממשק הרשת הספציפי):

  • dns קבלה/הגדרה של שרת DNS. מתודה זו יכולה לתמוך בשתיהן, כתובות IPv4 ו-IPv6.

  • prefer (4/6) ציין איזה סוג כתובת להחזיר, אם לשם מתחם יש גם רשומות A וגם AAAA. שים לב, שזה אינו מנקה את מטמון ה-DNS המקומי, כך שכתובות שהושגו קודם לכן עשויות שלא להשתנות.