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 المدمج) حسبما يناسب الكاميرا. النمط عالي المستوى المتمثل في الإنشاء -> التفعيل -> الاتصال -> استخدام المقابس هو نفسه في الحالات الثلاث جميعها.

واجهة محول الشبكة المشتركة

يصف هذا القسم فئة أساس مجرّدة (ضمنية) لجميع فئات واجهة الشبكة المُنفّذة من قِبل منافذ MicroPython لمختلف العتاد. وهذا يعني أن 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 لإشارة نقطة الوصول

• WiFi AP: استخدم 'stations' لاسترجاع قائمة بجميع محطات STA المتصلة بنقطة الوصول. تحتوي القائمة على مجموعات من الصيغة (MAC, RSSI).

ipconfig(param: str) → Any

ipconfig(**kwargs: Any) → None

الحصول على معاملات تهيئة IP الخاصة بالواجهة أو تعيينها. المعاملات المدعومة هي التالية (يعتمد توفر معامل معيّن على المنفذ وواجهة الشبكة المحددة):

• 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). وهذا يشمل العناوين المحلية للرابط و 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 وتوفر طريقة للتحكم في واجهات الشبكة بمختلف أنواعها.

• class WINC -- مشغّل درع WiFi
• class WLAN -- التحكم في واجهات WiFi المدمجة
• class LAN -- التحكم في واجهة Ethernet

دوال الشبكة

فيما يلي الدوال المتاحة في وحدة 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 في معظم المنافذ لا يهيّئ اسم المضيف إلا مرة واحدة أثناء الاتصال. ولهذا السبب، يجب عليك تعيين اسم المضيف قبل تفعيل/توصيل واجهات شبكتك.

طول اسم المضيف محدود بـ 32 حرفاً. وقد تختار منافذ MicroPython تعيين حد أدنى لأسباب تتعلق بالذاكرة. وإذا لم يتسع الاسم المُعطى، يُثار ValueError.

عادةً ما يكون اسم المضيف الافتراضي هو اسم اللوحة.

network.ipconfig(param: str) → Any

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

الحصول على معاملات تهيئة IP العامة أو تعيينها. المعاملات المدعومة هي التالية (يعتمد توفر معامل معيّن على المنفذ وواجهة الشبكة المحددة):

• dns الحصول على/تعيين خادم DNS. يمكن أن تدعم هذه الطريقة كلاً من عناوين IPv4 و IPv6.

• prefer (4/6) تحديد نوع العنوان المراد إعادته، إذا كان اسم نطاق ما يملك سجلي A و AAAA معاً. لاحظ أن هذا لا يمسح ذاكرة التخزين المؤقت المحلية لـ DNS، بحيث قد لا تتغير أي عناوين تم الحصول عليها مسبقاً.