class WINC -- مشغّل درع WiFi¶

يشغّل الصنف WINC وحدة WiFi من نوع Atmel WINC1500 802.11 b/g/n على درع OpenMV WiFi Shield. وهو متوفر على OpenMV Cam M4 و M7 و H7 و H7 Plus و Pure Thermal (لوحات STM32 التي صُمم لها درع WiFi). أما اللوحات ذات WiFi المدمج (OpenMV Cam N6 و OpenMV Cam RT1062 و Arduino Giga) فاستخدم WLAN بدلاً من ذلك.

مثال -- الاتصال بنقطة وصول وطباعة العنوان:

import network

wlan = network.WINC()
wlan.connect("SSID", "KEY", security=network.WINC.WPA_PSK)

print("status:    ", "connected" if wlan.isconnected() else "off")
print("rssi:      ", wlan.rssi(), "dBm")
print("interface: ", wlan.ifconfig())
print("netinfo:   ", wlan.netinfo())

مثال -- رفع نقطة وصول مفتوحة وانتظار عميل:

import network

wlan = network.WINC(mode=network.WINC.MODE_AP)
wlan.start_ap("OpenMV-Cam", security=network.WINC.OPEN, channel=6)

print("waiting for a station to associate...")
print(wlan.wait_for_sta(timeout=None))

المُنشئات¶

class network.WINC(mode: int = WINC.MODE_STA) → None¶

أنشئ كائن مشغّل WINC وارفع درع WiFi.

تختار mode وضع التشغيل الذي تبدأ به الوحدة:

WINC.MODE_STA -- محطة / عميل. اتصل بنقطة وصول باستخدام connect(). هذا هو الوضع الافتراضي.

WINC.MODE_AP -- نقطة وصول. هيّئ نقطة الوصول باستخدام start_ap()، ثم اقبل اتصالات العملاء.

WINC.MODE_P2P -- WiFi Direct.

WINC.MODE_BSP -- رفع BSP فقط (دون راديو).

WINC.MODE_FIRMWARE -- وضع تحديث البرنامج الثابت؛ مطلوب لـ fw_dump() و fw_update().

ملاحظة

في وضع نقطة الوصول، تكون لدى WINC1500 حدود عتادية:

يمكن لعميل واحد فقط الاتصال في كل مرة.
يُدعَم أمان OPEN أو WEP فقط.
يتسبب خطأ برمجي في البرنامج الثابت لوحدة WiFi في توقف أي مقابس مربوطة عن العمل عند قطع اتصال العميل. اضبط مهلة على مقبس الخادم بحيث يثير استثناءً يمكنك استخدامه لإعادة فتحه.

الطرق¶

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

تشغيل درع WiFi أو إيقافه.

بدون وسيطة، تُرجِع الحالة الراهنة -- True أثناء تهيئة الدرع ورفع الراديو، و False خلاف ذلك.

تنفّذ active(True) مصافحة البرنامج الثابت لـ WINC1500 عبر SPI وترفع الراديو في الوضع mode المُهيّأ. وهي عملية لا تأثير لها إذا كانت الواجهة نشطة بالفعل. وتستدعي connect() هذه تلقائياً إن لم تكن قد استُدعيت بعد؛ أما لأي طريقة أخرى (scan()، rssi()، netinfo()، ...) فيجب عليك استدعاء active(True) أولاً.

توقف active(False) الراديو مجدداً (تنخفض WINC إلى وضع BSP فقط) وتحرر أطراف SPI.

connect(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None¶

ارتبط بشبكة WiFi ssid باستخدام كلمة المرور key، ووضع الأمان security (واحد من OPEN أو WPA_PSK أو ثابت 802.1X) على القناة channel. تُمرَّر security و channel بالكلمات المفتاحية فقط.

بعد الاتصال استخدم الوحدة socket لفتح منافذ TCP/UDP.

تحجب هذه الطريقة حتى يكتمل الارتباط أو يفشل.

config(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None¶: اسم بديل لـ connect(). مُتاح للتوافق مع الشيفرة التي تستدعي config على واجهات network الأخرى.

start_ap(ssid: str, key: str | None = None, *, security: int = WINC.OPEN, channel: int = 1) → None¶: اسم بديل لـ connect() يُستخدم بعد إنشاء الكائن بـ mode=MODE_AP لتهيئة نقطة الوصول وتشغيلها. تدعم نقطة الوصول أمان OPEN أو WEP فقط؛ وإذا استُخدم WEP فإن key مطلوب.

disconnect() → None¶: في وضع المحطة، افصل الارتباط عن نقطة الوصول المرتبط بها حالياً. يبقى الدرع نشطاً؛ استدعِ connect() لإعادة الارتباط. لا تأثير لها عند عدم وجود ارتباط حالي.

isconnected() → bool¶: في وضع المحطة تُرجِع True عند الارتباط بنقطة وصول و الحصول على عنوان IPv4 (عبر DHCP أو ifconfig()). وتُرجِع False أثناء وجودها في مرحلة المصادقة / الارتباط / DHCP.

connected_sta() → List[str]¶: في وضع نقطة الوصول، تُرجِع قائمة تحتوي على عنوان IP للعميل المتصل حالياً (أو قائمة فارغة إذا لم يكن هناك عميل متصل).

wait_for_sta(timeout: int | None) → List[str]¶: في وضع نقطة الوصول، تحجب حتى يتصل عميل وتُرجِع قائمة تحتوي على عنوان IP الخاص بالعميل. timeout هو أقصى مدة انتظار بالميلي ثانية؛ مرّر None للانتظار إلى أجل غير مسمى.

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

اقرأ أو اضبط معاملات واجهة IPv4. يحتوي الصف الرباعي على (ip, subnet, gateway, dns) كسلاسل نصية رباعية النقاط.

عند الاستدعاء بدون وسيطة: تُرجِع التهيئة الحالية.

عند الاستدعاء بصف رباعي: تضبط تهيئة IP ثابتة بدلاً من التهيئة المكتسَبة عبر DHCP.

مثال -- تثبيت عنوان IP ثابت قبل الاتصال:

wlan = network.WINC()
wlan.ifconfig(("192.168.1.100", "255.255.255.0",
               "192.168.1.1", "192.168.1.1"))
wlan.connect(SSID, key=KEY, security=network.WINC.WPA_PSK)

ملاحظة

WINC لا تطبّق واجهة AbstractNIC.ipconfig() الحديثة؛ استخدم ifconfig() هنا.

netinfo() → Tuple[int, int, str, str, str]¶

تُرجِع صفاً خماسياً يصف الارتباط الحالي:

[0] RSSI كعدد صحيح (dBm).

[1] وضع الأمان -- واحد من ثوابت الأمان.

[2] سلسلة SSID النصية.

[3] BSSID كسلسلة عنوان MAC بالشكل "XX:XX:XX:XX:XX:XX".

[4] عنوان IPv4 كسلسلة نصية رباعية النقاط.

scan() → List[Tuple[str, str, int, int, int, int]]¶

ابحث عن نقاط الوصول القريبة. تُرجِع قائمة من صفوف سداسية:

[0] سلسلة SSID النصية.

[1] BSSID كسلسلة عنوان MAC بالشكل "XX:XX:XX:XX:XX:XX".

[2] رقم القناة.

[3] RSSI بوحدة dBm.

[4] وضع الأمان -- واحد من ثوابت الأمان.

[5] محجوز (دائماً 1).

يمكن استدعاؤها دون الارتباط بشبكة أولاً.

rssi() → int¶: أرجع RSSI بوحدة dBm لنقطة الوصول المرتبط بها حالياً. تقريباً: -30 ممتاز، و -67 مقبول للبث، و -80 حدّي، و -90 فما دون غير قابل للاستخدام. لا معنى له إلا في وضع المحطة بينما isconnected() تساوي True.

fw_version() → Tuple[int, int, int, int, int, int, int]¶

تُرجِع صفاً سباعياً يصف إصدارات البرنامج الثابت والمشغّل لـ WINC1500:

[0] الإصدار الرئيسي للبرنامج الثابت.

[1] الإصدار الفرعي للبرنامج الثابت.

[2] رقعة (patch) البرنامج الثابت.

[3] الإصدار الرئيسي للمشغّل.

[4] الإصدار الفرعي للمشغّل.

[5] رقعة (patch) المشغّل.

[6] مراجعة عتاد الشريحة.

fw_dump(path: str) → None¶

اقرأ ذاكرة الفلاش الداخلية لـ WINC1500 واكتب صورة البرنامج الثابت الناتجة إلى الملف في path على نظام ملفات OpenMV. استخدم هذا للنسخ الاحتياطي للصورة المثبّتة حالياً قبل استدعاء fw_update().

يتطلب أن تكون الوحدة قد أُنشئت بـ mode=MODE_FIRMWARE.

fw_update(path: str) → None¶

امسح ذاكرة الفلاش الداخلية لـ WINC1500 وبرمجها بالصورة الثنائية في path. يجب أن تطابق الصورة التخطيط الذي يتوقعه البرنامج الثابت لـ OpenMV (تُورَّد عادةً من Atmel / Microchip مع WINC SDK).

يحجب الاستدعاء لعدة ثوانٍ أثناء برمجة الفلاش والتحقق منها. أعِد تدوير الطاقة لـ OpenMV Cam بعد عودة الاستدعاء بحيث تبدأ WINC1500 من الصورة الجديدة.

يتطلب أن تكون الوحدة قد أُنشئت بـ mode=MODE_FIRMWARE.

الثوابت¶

OPEN: int¶: قيمة أمان لشبكة غير مشفّرة. مرّرها إلى الوسيطة security في connect() / start_ap().

WPA_PSK: int¶: قيمة أمان لـ WPA/WPA2 بمفتاح مشترك مسبقاً. القيمة الافتراضية لـ connect().

ملاحظة

توجد أيضاً قيمة أمان WPA/WPA2 Enterprise (802.1X). يعرضها البرنامج الثابت تحت الاسم 802_1X، وهو ليس معرّفاً صالحاً في Python -- اصل إليها عبر getattr(network.WINC, "802_1X").

MODE_STA: int¶: وضع المحطة -- الاتصال بنقطة وصول كعميل. وضع المُنشئ الافتراضي.

MODE_AP: int¶: وضع نقطة الوصول -- تصبح WINC نقطة الوصول التي يرتبط بها العملاء.

MODE_P2P: int¶: وضع WiFi-Direct (الند للند).

MODE_BSP: int¶: تهيئة حزمة دعم اللوحة لـ WINC فقط -- لا يُرفع الراديو. يُستخدم في مسار تحديث البرنامج الثابت.

MODE_FIRMWARE: int¶: وضع تحديث البرنامج الثابت. مطلوب لـ fw_dump() و fw_update().