class WLAN – שליטה בממשקי WiFi מובנים¶

המחלקה WLAN מפעילה את רכיבי הרדיו של WiFi המובנים במצלמות OpenMV Cam מודרניות. אותה מחלקה עוטפת שני מנהלי התקן שונים בהתאם ל-MCU של ה-WiFi בלוח:

CYW43 (מודול WiFi מסוג Infineon CYW43xxx של Murata). בשימוש על ידי OpenMV Cam N6, OpenMV Cam RT1062, Arduino Portenta H7, Arduino Nicla Vision ו-Arduino Giga R1 WiFi.
NINA W10 (u-blox NINA-W10 / ESP32-WROOM). בשימוש על ידי Arduino Nano RP2040 Connect.

שני מנהלי ההתקן חושפים את אותם שמות מתודות אך נבדלים בכמה ארגומנטים ובקבוצת מפתחות config() הקבילים. ההבדלים מסומנים להלן.

מצלמות OpenMV עם מגן WiFi מסוג WINC1500 ישן (M4 / M7 / H7 / H7 Plus / Pure Thermal) משתמשות ב-WINC במקום.

דוגמת שימוש:

import network

# Enable the station interface and connect to a WiFi AP.
nic = network.WLAN(network.WLAN.IF_STA)
nic.active(True)
nic.connect("your-ssid", "your-key")
while not nic.isconnected():
    pass

print(nic.ipconfig("addr4"))

בנאים¶

class network.WLAN(interface_id: int = WLAN.IF_STA) → None¶

יצירת אובייקט ממשק WLAN.

interface_id בוחר על איזה ממשק לפעול:

WLAN.IF_STA – מצב תחנה / לקוח. התחבר לנקודת גישה במעלה הזרם באמצעות connect(). זוהי ברירת המחדל.

WLAN.IF_AP – מצב נקודת גישה. הגדר את ה-AP באמצעות config() וקבל חיבורי לקוחות.

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

מתודות¶

active(is_active: bool | None = None) → bool¶

הפעלת או כיבוי רכיב הרדיו של ה-WiFi.

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

active(True) מספק חשמל ל-MCU של ה-WiFi, טוען את הקושחה שלו (CYW43 מאחזר את blob הקושחה מזיכרון הפלאש (flash); NINA מאמת את גרסת הקושחה המותקנת כעת) ומפעיל את ה-netif של lwIP עבור ממשק זה. כל שאר המתודות – connect(), scan(), ipconfig() ושכמותן – דורשות שהממשק יהיה פעיל.

active(False) מכבה שוב את הרדיו. בממשק ה-STA פעולה זו גם מנתקת את השיוך מה-AP הנוכחי ומשחררת את ה-netif.

connect(ssid: str, key: str | None = None, *, security: int = -1, bssid: bytes | None = None, channel: int = -1) → None¶

שיוך ממשק ה-STA לנקודת הגישה הנתונה.

ssid – ה-SSID של הרשת (מחרוזת או bytes).

key – סיסמה / מפתח משותף מראש. העבר None עבור רשת פתוחה.

security (מילת מפתח בלבד) – אחד מקבועי SEC_*. -1 (ברירת המחדל) בוחר אוטומטית: SEC_OPEN כאשר key ריק, SEC_WPA_WPA2 אחרת.

bssid (מילת מפתח בלבד, CYW43 בלבד) – הגבל את השיוך ל-AP בעל כתובת MAC זו בת 6 בתים. מתעלם ממנו מנהל ההתקן NINA.

channel (מילת מפתח בלבד) – ערוץ הרדיו המועדף. ברירת המחדל היא ”תן למנהל ההתקן לבחור“.

disconnect() → None¶: במצב STA, ביטול השיוך מנקודת הגישה המשויכת כעת. הממשק נשאר פעיל; קרא ל-connect() שוב כדי לשייך מחדש, או ל-active() (False) כדי לכבות לחלוטין את הרדיו. ללא פעולה כאשר אין שיוך נוכחי.

isconnected() → bool¶

במצב STA מוחזר True כאשר קיים שיוך לנקודת גישה וגם הושגה כתובת IPv4 מ-DHCP (או הוקצתה באופן סטטי דרך ipconfig()). מוחזר False בעוד הקישור עדיין בשלב האימות/השיוך/DHCP.

במצב AP מוחזר True כאשר לפחות תחנה אחת הצטרפה.

scan(*, passive: bool = False, ssid: bytes | None = None, bssid: bytes | None = None) → List[Tuple[bytes, bytes, int, int, int, int]]¶

סריקה לאיתור נקודות גישה סמוכות והחזרת רשימה של רביעיות-שש:

[0] SSID (bytes; ריק עבור רשתות מוסתרות).

[1] BSSID (כתובת MAC בת 6 בתים, bytes). המר באמצעות binascii.hexlify().

[2] מספר ערוץ.

[3] RSSI ביחידות dBm.

[4] מצב אבטחה (אחד מקבועי SEC_*).

[5] שמור (תמיד 1).

כל ארגומנטי מילות המפתח הם עבור CYW43 בלבד:

passive – אם True, השתמש בסריקה פסיבית במקום בסריקת בקשות-בדיקה (probe-request) אקטיבית המהווה ברירת מחדל.

ssid – הגבל את הסריקה ל-SSID אחד.

bssid – הגבל את הסריקה ל-BSSID אחד.

סריקה משמעותית רק בממשק STA.

status() → int¶

status(param: str) → Any

שאילתת סטטוס חיבור.

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

עם ארגומנט מחרוזת:

"rssi" – במצב STA, מוחזר ה-RSSI הנוכחי ביחידות dBm.

"stations" – במצב AP, מוחזרת רשימה של תחנות מחוברות. CYW43 מחזיר [(mac_bytes,), ...]; NINA מחזיר [ip_string, ...].

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

קבלה או הגדרה של פרמטרי ממשק IPv4 כרביעייה של מחרוזות נקודה-מרובעת (ip, subnet, gateway, dns).

הערה

עדיף להשתמש ב-ipconfig() עבור קוד חדש:

nic.ipconfig(addr4="192.168.0.4/24", gw4="192.168.0.1")
network.ipconfig(dns="8.8.8.8")

ipconfig(param: str) → Any¶
ipconfig(**kwargs: Any) → None: קבלה או הגדרה של פרמטרי ממשק IPv4 / IPv6. מנהל ההתקן CYW43 מאציל למימוש lwIP הסטנדרטי ותומך במלוא קבוצת המפתחות המתועדת ב-AbstractNIC.ipconfig(). מנהל ההתקן NINA מממש תת-קבוצה קטנה יותר לכל ממשק – dhcp4 ו-has_dhcp4 (לקריאה בלבד), בנוסף ל-addr4 ו-gw4 עבור קבלה / הגדרה.

config(param: str) → Any¶

config(**kwargs: Any) → None

קבלה או הגדרה של פרמטרי ממשק ספציפיים ל-WiFi.

עם ארגומנט מחרוזת מיקומי יחיד, מוחזר ערך אותו פרמטר. עם ארגומנטי מילות מפתח, ניתן להגדיר פרמטר אחד או יותר בבת אחת – שינויים המשפיעים על AP פועל גורמים לכך שה-AP מכובה ומופעל מחדש באופן אוטומטי.

דוגמה:

# Set up the access-point name and channel.
ap.config(ssid="My AP", channel=11)
# Query params one at a time.
print(ap.config("ssid"))
print(ap.config("mac"))

מנהל ההתקן CYW43 – פרמטרים הניתנים לקבלה:

"antenna" – בורר אנטנה (int).

"channel" – הערוץ הנוכחי.

"ssid" / "essid" – ה-SSID הנוכחי (מחרוזת).

"security" – מצב האימות של ה-AP (אחד מ-SEC_*).

"mac" – כתובת ה-MAC של הממשק (6 bytes).

"pm" – ערך ניהול צריכת חשמל.

"txpower" – עוצמת שידור ביחידות dBm.

"hostname" – שם מארח של DHCP/mDNS. הוצא משימוש; השתמש ב-network.hostname() במקום.

מנהל ההתקן CYW43 – פרמטרים הניתנים להגדרה:

antenna=<int> – בורר אנטנה.

channel=<int> – ערוץ ה-AP.

ssid=<str> / essid=<str> – SSID של ה-AP.

key=<str> / password=<str> – מפתח משותף מראש של ה-AP.

security=<int> – מצב אימות של ה-AP (אחד מ-SEC_*).

pm=<int> – מצב ניהול צריכת חשמל (אחד מ-PM_NONE, PM_PERFORMANCE, PM_POWERSAVE).

monitor=<int> – הפעלת מצב ניטור / כל-multicast.

txpower=<int> – עוצמת שידור ביחידות dBm.

trace=<int> – מסיכת ביטים פנימית למעקב אחר מנהל ההתקן.

hostname=<str> – שם מארח של DHCP/mDNS. הוצא משימוש; השתמש ב-network.hostname() במקום.

מנהל ההתקן NINA – פרמטרים הניתנים לקבלה:

"ssid" – ה-SSID הנוכחי (מחרוזת).

"security" – מצב האימות של ה-AP.

"mac" / "bssid" – כתובת ה-MAC של הממשק (6 bytes).

"fw_version" – שלשה (major, minor, patch).

מנהל ההתקן NINA – פרמטרים הניתנים להגדרה: הקריאה מועברת ל-connect() ומקבלת את אותם ארגומנטי מילות מפתח (ssid, key, security, channel). תקפה רק בממשק ה-AP.

deinit() → None¶: ביצוע מחזור הפעלה ל-MCU של ה-WiFi ושחרור כל משאב שמנהל ההתקן מחזיק (חוצצי קושחה, netif של lwIP, אפיק SPI/SDIO). לאחר קריאה לפעולה זו יש לבנות מחדש את אובייקט WLAN לפני השימוש. השתמש בכך במקום ב-active() (False) כאשר נדרשת איפוס מלא (למשל, לפני צריבה מחדש של קושחת הרדיו או כדי להתאושש ממצב מנהל התקן תקוע). CYW43 בלבד.

send_ethernet(buf: bytes) → None¶: הזרקת פריים Ethernet גולמי buf ישירות לנתיב השידור של מנהל ההתקן, תוך עקיפת מחסנית ה-IP. מיועד לצרכנים ברמת L2 בלבד – גישור, פרוטוקולי EtherType מותאמים אישית וכדומה. הפריים חייב לכלול כתובת MAC של יעד/מקור ו-EtherType (ללא FCS – החומרה מוסיפה אותו). CYW43 בלבד.

ioctl(cmd: int, buf: bytearray) → None¶: הנפקת פקודת בקרה ספציפית למנהל ההתקן. cmd הוא קוד ה-ioctl המספרי המוגדר על ידי קושחת הרדיו הבסיסית ו-buf הוא חוצץ (buffer) ניתן לשינוי המשמש הן למטען הפקודה והן לתגובה. קבוצת ערכי cmd התקפים היא ספציפית למנהל ההתקן ואינה ניתנת להעברה בין CYW43 ל-NINA. בשימוש בעיקר על ידי סקריפטי בדיקה ברמה נמוכה וקוד הבאת השבב לחיים.

קבועים¶

IF_STA: int¶: מזהה ממשק תחנה / לקוח. העבר לבנאי כדי לבחור במצב STA.

IF_AP: int¶: מזהה ממשק נקודת גישה. העבר לבנאי כדי לבחור במצב AP.

SEC_OPEN: int¶: ערך אבטחה עבור רשת לא מוצפנת. זמין בשני מנהלי ההתקן.

SEC_WPA_WPA2: int¶: ערך אבטחה עבור WPA / WPA2 עם מפתח משותף מראש. ברירת המחדל כאשר מסופק מפתח ל-connect(). זמין בשני מנהלי ההתקן.

SEC_WPA3: int¶: ערך אבטחה עבור WPA3 (SAE) עם מפתח משותף מראש. CYW43 בלבד.

SEC_WPA2_WPA3: int¶: ערך אבטחה עבור מצב המעבר WPA2 / WPA3. CYW43 בלבד.

SEC_WEP: int¶: ערך אבטחה עבור WEP (Wired Equivalent Privacy). מסופק לצורך תאימות עם נקודות גישה ישנות – WEP שבור מבחינה קריפטוגרפית ואין להשתמש בו בפריסות חדשות. NINA בלבד.

OPEN: int¶: כינוי לתאימות לאחור עבור SEC_OPEN. קוד חדש צריך להשתמש ב-SEC_OPEN. NINA בלבד.

WEP: int¶: כינוי לתאימות לאחור עבור SEC_WEP. קוד חדש צריך להשתמש ב-SEC_WEP. NINA בלבד.

WPA_PSK: int¶: כינוי לתאימות לאחור עבור SEC_WPA_WPA2. קוד חדש צריך להשתמש ב-SEC_WPA_WPA2. NINA בלבד.

PM_NONE: int¶: העבר ל-config(pm=...) כדי להשבית את ניהול צריכת החשמל של WiFi. CYW43 בלבד.

PM_PERFORMANCE: int¶: העבר ל-config(pm=...) כדי להפעיל ניהול צריכת חשמל של WiFi המכוונן לביצועים. CYW43 בלבד.

PM_POWERSAVE: int¶: העבר ל-config(pm=...) כדי להפעיל ניהול צריכת חשמל של WiFi המכוונן לאורך חיי סוללה מרבי. CYW43 בלבד.