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 -- وضع نقطة الوصول. تهيئة نقطة الوصول عبر config() وقبول اتصالات العملاء.

تدعم وحدة الراديو الفيزيائية نفسها كلتا الواجهتين؛ وإنشاء إحداهما لا يمنع الأخرى.

الطرق¶

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

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

بدون وسيطة، تُعيد الحالة الحالية -- True بينما الراديو قيد التشغيل، و False خلاف ذلك.

تشغّل active(True) وحدة MCU الخاصة بـ WiFi، وتحمّل برنامجها الثابت (تجلب CYW43 كتلة البرنامج الثابت من ذاكرة الفلاش؛ بينما تتحقق NINA من إصدار البرنامج الثابت المُثبّت حالياً)، وتشغّل واجهة netif الخاصة بـ lwIP لهذه الواجهة. وتتطلب جميع الطرق الأخرى -- connect() و scan() و ipconfig() وما يشبهها -- أن تكون الواجهة نشطة.

تعيد active(False) إيقاف تشغيل الراديو. وعلى واجهة STA يؤدي هذا أيضاً إلى فصل الارتباط بنقطة الوصول الحالية وتحرير 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) -- قصر الارتباط على نقطة الوصول ذات عنوان MAC هذا المكوّن من 6 بايت. يتجاهله مشغّل NINA.

channel (كلمة مفتاحية فقط) -- القناة الراديوية المفضّلة. الافتراضي هو "دع المشغّل يختار".

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

isconnected() → bool¶

في وضع STA تُعيد True عند الارتباط بنقطة وصول و الحصول على عنوان IPv4 من DHCP (أو تعيينه ثابتاً عبر ipconfig()). وتُعيد False بينما لا يزال الاتصال في مرحلة المصادقة/الارتباط/DHCP.

في وضع نقطة الوصول تُعيد 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، يُستخدم مسح سلبي بدلاً من مسح طلب الاستكشاف النشط الافتراضي.

ssid -- قصر المسح على معرّف SSID واحد.

bssid -- قصر المسح على معرّف BSSID واحد.

المسح ذو معنى فقط على واجهة STA.

status() → int¶

status(param: str) → Any

الاستعلام عن حالة الاتصال.

بدون وسيطة، تُعيد حالة الاتصال كعدد صحيح صغير (ترميز خاص بالمشغّل -- القيمة الصادقة تعني "مرتبط").

مع وسيطة سلسلة نصية:

"rssi" -- في وضع STA، تُعيد قوة الإشارة RSSI الحالية بوحدة dBm.

"stations" -- في وضع نقطة الوصول، تُعيد قائمة بالمحطات المتصلة. تُعيد 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 أو تعيينها.

مع وسيطة سلسلة نصية موضعية واحدة، تُعيد قيمة ذلك المعامل. ومع الوسائط المفتاحية، تعيّن معاملاً واحداً أو أكثر دفعة واحدة -- التغييرات التي تؤثر على نقطة وصول قيد التشغيل تتسبب في إيقاف نقطة الوصول وإعادة تشغيلها تلقائياً.

مثال:

# 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" -- وضع المصادقة الخاص بنقطة الوصول (واحد من SEC_*).

"mac" -- عنوان MAC للواجهة (6 bytes).

"pm" -- قيمة إدارة الطاقة.

"txpower" -- قدرة الإرسال بوحدة dBm.

"hostname" -- اسم مضيف DHCP/mDNS. مهمل؛ استخدم network.hostname() بدلاً منه.

مشغّل CYW43 -- المعاملات القابلة للتعيين:

antenna=<int> -- محدّد الهوائي.

channel=<int> -- قناة نقطة الوصول.

ssid=<str> / essid=<str> -- معرّف SSID لنقطة الوصول.

key=<str> / password=<str> -- المفتاح المشترك مسبقاً لنقطة الوصول.

security=<int> -- وضع مصادقة نقطة الوصول (واحد من SEC_*).

pm=<int> -- وضع إدارة الطاقة (واحد من PM_NONE أو PM_PERFORMANCE أو PM_POWERSAVE).

monitor=<int> -- تمكين وضع المراقبة / كل البث المتعدد.

txpower=<int> -- قدرة الإرسال بوحدة dBm.

trace=<int> -- قناع بِتّي لتتبّع المشغّل الداخلي.

hostname=<str> -- اسم مضيف DHCP/mDNS. مهمل؛ استخدم network.hostname() بدلاً منه.

مشغّل NINA -- المعاملات القابلة للقراءة:

"ssid" -- معرّف SSID الحالي (سلسلة نصية).

"security" -- وضع المصادقة الخاص بنقطة الوصول.

"mac" / "bssid" -- عنوان MAC للواجهة (6 bytes).

"fw_version" -- مجموعة ثلاثية (major, minor, patch).

مشغّل NINA -- المعاملات القابلة للتعيين: يُحيل الاستدعاء إلى connect() ويقبل الوسائط المفتاحية نفسها (ssid و key و security و channel). صالح فقط على واجهة نقطة الوصول.

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 هو مخزن مؤقت قابل للتعديل يُستخدم لكل من حمولة الأمر والاستجابة. مجموعة قيم cmd الصالحة خاصة بالمشغّل وغير قابلة للنقل بين CYW43 و NINA. تُستخدم في الغالب من قِبل برامج الاختبار منخفضة المستوى وأكواد تشغيل الرقاقة الأولي.

الثوابت¶

IF_STA: int¶: معرّف واجهة المحطة / العميل. مرّره إلى المُنشئ لاختيار وضع STA.

IF_AP: int¶: معرّف واجهة نقطة الوصول. مرّره إلى المُنشئ لاختيار وضع نقطة الوصول.

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 (الخصوصية المكافئة للشبكة السلكية). مُتاحة للتوافق مع نقاط الوصول القديمة -- 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 فقط.