baiyibai/pico-usb-wifiبرنامج ثابت لـ Raspberry Pi Pico W ينشئ محول USB Wi-Fi بدون برامج تشغيل مع جسر شفاف من الطبقة 2، ومصادقة WPA2/WPA3، ووحدة تحكم إدارة خارج النطاق.
= pico-usb-wifi :toc: macro :toclevels: 3 :idprefix: :idseparator: -
pico-usb-wifi هو برنامج ثابت (فيرموير) لـ Raspberry Pi Pico W يحوّله إلى محوّل USB Wi-Fi بدون برامج تشغيل، حيث يتعرّف عليه النظام كجهاز USB CDC-NCM.
:figure-caption: محتوى الذكاء الاصطناعي الرديء
.مخطط pico-usb-wifi image::images/openrouter-banana2-rpi-pico.png[]
يعمل البرنامج الثابت كجسر شفاف للطبقة 2 يمرّر الإطارات بين الواجهة اللاسلكية لـ Pico W وواجهة USB الخاصة بها. تتبنّى واجهة USB على المضيف عنوان MAC الخاص بمحطة Wi-Fi في Pico W، مما يوفر هوية MAC وعنوان IP واحدة من الطرف إلى الطرف.
لا يلزم أي برنامج تشغيل على جانب المضيف، أو وحدة نواة، أو مكدس لاسلكي؛ انظر <<no-host-side-wi-fi-stack,لا حاجة لمكدس Wi-Fi على جانب المضيف>>.
يحتاج المضيف فقط إلى برنامجي التشغيل المدمجين cdc_ncm وcdc_acm اللذين يأتيان مع كل نظام Linux وmacOS وWindows ونظام تشغيل هواتف حديث.
== الميزات
يوفر pico-usb-wifi هذه الميزات:
.سيناريو من الواقع الفعلي image::images/slop_2.png[]
== لماذا وُجد هذا المشروع
كنت بحاجة إلى محوّل USB Wi-Fi لاستخدامه في مشروع Linux مضمّن قادم. لم يكن لديّ دونجل USB Wi-Fi رخيص، فبدلًا من الذهاب وشراء واحد من متجر فعلي بخمسة دولارات أمريكية، أمضيت يومين من عطلة نهاية أسبوع طويلة وحوالي مليون رمز (token) من Claude Code في بناء هذا البرنامج الثابت.
白一百، مؤلف pico-usb-wifi
قالت Google إن الأمر غير ممكن:
.pico-usb-wifi «غير ممكن» image::images/gemini_says_not_possible.png[]
toc::[]
== لا حاجة لمكدس Wi-Fi على جانب المضيف
بخلاف دونجل USB Wi-Fi، يعرض هذا المحوّل للمضيف واجهة شبيهة بإيثرنت فقط. يحتوي Pico W على الجانب اللاسلكي بأكمله: الراديو، والاقتران (association)، وعميل WPA2/WPA3 (supplicant)، والنطاق التنظيمي.
يتيح ذلك للأنظمة تجنّب تثبيت wpa_supplicant، ومكدس cfg80211/mac80211 اللاسلكي، وقاعدة بيانات تنظيمية، وبرنامج تشغيل خاص بالرقاقة أو من البائع.
يتم توفير بيانات اعتماد Wi-Fi على الجهاز نفسه، عبر وحدة التحكم الإدارية خارج النطاق، وليس من خلال أي أداة لاسلكية على جانب المضيف.
بهذا يظل المضيف محدود الموارد، أو الجهاز المخصّص (appliance)، أو المضيف الذي لا يملك برامج تشغيل لاسلكية أو الذي تفتقر نواة البائع لديه إليها، قادرًا على الاتصال بالشبكات اللاسلكية باستخدام برامج تشغيل CDC العامة فقط.
== كيف يعمل
[#fig-topology] .مخطط الطوبولوجيا image::images/topology.svg[طوبولوجيا جسر الطبقة 2 الشفاف,820]
تُمنح واجهة USB على المضيف عنوان MAC الخاص بمحطة Wi-Fi في Pico W، بحيث توجد هوية MAC واحدة من الطرف إلى الطرف ويستطيع Pico W تمرير إطارات إيثرنت كما هي بين USB وWi-Fi. لا يمكن لمحطة Wi-Fi أن تجسر عدة عناوين MAC، لذا فإن دمج المضيف والمحطة في عنوان MAC واحد هو ما يجعل الجسر الشفاف ممكنًا أصلًا. المنطق الكامل، ومسار البيانات، ومعالجة IPv6/البث المتعدد موصوفة في <<architecture,البنية>>.
== متطلبات المضيف
يتطلب المضيف برنامجي التشغيل المدمجين في الشجرة cdc_ncm وcdc_acm.
كلاهما جزء من نواة Linux الرئيسية منذ أكثر من عقد من الزمن، لذا فإن أي نواة مدعومة حاليًا تشملهما.
لا حاجة لأي وحدة خارج الشجرة، أو blob برنامج ثابت، أو برنامج تشغيل من البائع.
توجد برامج التشغيل نفسها على macOS وWindows 10 والإصدارات الأحدث وAndroid وiOS.
[NOTE] لم تُختبر أي أنظمة تشغيل أخرى.
== البناء
المشروع هو مشروع CMake قياسي يعتمد على pico-sdk. يتطلب سلسلة أدوات ARM المضمّنة، وCMake، ومحرك بناء (Ninja أو Make)، وPython 3، ونسخة مستنسخة من pico-sdk مع وحداته الفرعية. يُستخدم TinyUSB وlwIP المرفقان مع pico-sdk كما هما دون تعديل.
=== التبعيات
على الأنظمة المبنية على Arch (Arch وCachyOS وManjaro)، تأتي السلسلة من المستودعات الرسمية:
يوفر arm-none-eabi-newlib مكتبة C المضمّنة والملفات الرأسية؛ وبدونه لا يستطيع المترجم المتقاطع العثور على stdint.h والملفات الرأسية المشابهة.
libusb مطلوب فقط من أجل picotool، الذي يبنيه pico-sdk من المصدر أثناء أول إعداد (configure) لتوليد ملف UF2؛ ولا يلزم أي حزمة picotool منفصلة.
=== خطوات البناء
git clone -b 2.2.0 --recurse-submodules https://github.com/raspberrypi/pico-sdk export PICO_SDK_PATH="$PWD/pico-sdk"
cp src/wifi_config.h.example src/wifi_config.h # then edit SSID/password, or leave blank cmake -S . -B build -G Ninja -DPICO_BOARD=pico_w -DCMAKE_BUILD_TYPE=Release cmake --build build
العلامة -G Ninja اختيارية؛ احذفها لاستخدام مولد Make الافتراضي (ثم نفّذ cmake --build build -j).
يحتفظ wifi_config.h ببيانات الاعتماد الافتراضية وقت البناء، وهو مستثنى من Git (gitignored).
تركه فارغًا ينتج صورة بدون بيانات اعتماد مدمجة (baked)، تُزوَّد لاحقًا في زمن التشغيل عبر وحدة التحكم الإدارية (<<management-console,وحدة التحكم الإدارية>>)؛ وملؤه يدمج شبكة افتراضية في الصورة.
== كتابة البرنامج الثابت
الخطوات هنا تحمّل البرنامج الثابت على اللوحة.
. اضغط مع الاستمرار على زر BOOTSEL أثناء توصيل اللوحة عبر USB.
تظهر كوحدة تخزين USB كتلي باسم RPI-RP2، عادةً تحت /run/media/<user>/RPI-RP2 أو /media/<user>/RPI-RP2.
. انسخ pico-usb-wifi.uf2 إلى تلك الوحدة.
تعيد اللوحة تشغيل نفسها تلقائيًا لتعمل بالبرنامج الثابت.
. وصّل اللوحة بالمضيف الذي سيستقبل الاتصال اللاسلكي.
== الاستخدام على مضيف Linux
وصّل الجهاز بالمضيف وزوّده ببيانات اعتماد Wi-Fi مرة واحدة عبر وحدة التحكم الإدارية (<<management-console,وحدة التحكم الإدارية>>). بعدها تتصرف واجهة المضيف مثل أي اتصال سلكي على شبكة نقطة الوصول.
المضيف الذي يدير واجهاته تلقائيًا (NetworkManager، أو systemd-networkd، أو dhcpcd) لا يحتاج إلى أي إعداد: فهو يشغّل DHCP وSLAAC عبر الجسر ويستلم عنوان IPv4 واحدًا وعنوان IPv6 وبوابة نقطة الوصول وخوادم DNS، تمامًا كما يفعل أي عميل سلكي.
لا يوجد عنوان أو بوابة على جانب الجهاز لتكوينها، لأن Pico لا يحمل أيًّا منها.
عنوان MAC للواجهة هو عنوان MAC الخاص بمحطة Wi-Fi، وبهذه الطريقة تُقدَّم هوية واحدة للشبكة.
يُظهر مخرج أمر ip هنا الواجهة الناتجة: عميل DHCP/SLAAC عادي على الشبكة الفرعية الخاصة بنقطة الوصول، بعنوان MAC الخاص بالمحطة ودون أي أثر لـ Pico.
== وحدة التحكم الإدارية
وحدة التحكم الإدارية هي الواجهة الأمامية للتكوين، وتعمل على أول وظيفة تسلسلية CDC-ACM (عادةً /dev/ttyACM0).
يمكن الوصول إليها فور أن يتعرّف النظام على الجهاز، قبل اقتران Wi-Fi، لذا لا يتطلب تزويد البيانات أي شبكة.
افتحها باستخدام طرفية تسلسلية مثل picocom أو screen؛ لا يهم معدل الباود مع USB CDC.
تعيد وحدة التحكم عرض ما تكتبه وتظهر صيغة انتظار أوامر (prompt)، ويطبع كل أمر حالة الجهاز الكاملة.
مصادقة Wi-Fi تكون إما WPA2-PSK أو WPA3-SAE (AES).
كلمة المرور هي عبارة مرور الشبكة، أو تظل الشبكة مفتوحة عند تركها فارغة.
يستخدم الملف المحمي بكلمة مرور وضع الانتقال WPA2/WPA3، لذا ينضم إلى أيٍّ من نوعي نقاط الوصول.
تخزّن وحدة التحكم حتى ثمانية ملفات تعريف لبيانات الاعتماد؛ أحدها هو الملف النشط ويقترن به الجهاز.
يعدّل set ssid/set pass الملف النشط، وتدير list/use/del مجموعة الملفات، ويكتشف scan الشبكات القريبة وينضم إلى إحداها من قائمة مرقّمة — وهو أمر مفيد عندما تحتوي SSID على أحرف يصعب كتابتها.
كلمات الأوامر غير حساسة لحالة الأحرف؛ وتعرضها وحدة التحكم بأحرف صغيرة.
في الجلسة هنا، تُزوَّد الشبكة بالبيانات عبر مسحها.
$ picocom /dev/ttyACM0
