uhubctl

uhubctl هي أداة للتحكم في طاقة USB لكل منفذ على موزعات USB الذكية. الموزع الذكي هو الذي يطبق تبديل الطاقة لكل منفذ.

الفكرة الأصلية لهذا الكود مستوحاة من hub-ctrl.c بقلم Niibe Yutaka: https://www.gniibe.org/development/ac-power-control-by-USB-hub

موزعات USB المتوافقة

لاحظ أن عددًا قليلاً فقط من موزعات USB يدعم تبديل الطاقة لكل منفذ بشكل صحيح. بعضها لم يعد يُصنّع وقد يكون من الصعب العثور عليه.

هذه قائمة بموزعات USB المتوافقة المعروفة:

هذه القائمة ليست شاملة بأي حال من الأحوال. إذا كان الموزع لديك يعمل مع uhubctl، ولكنه غير مدرج أعلاه، فيرجى الإبلاغ عنه بفتح issue جديدة على https://github.com/mvp/uhubctl/issues، حتى نتمكن من إضافته إلى جدول الأجهزة المدعومة. في تقريرك، يرجى تقديم طراز المنتج المحدد وإضافة مخرجات uhubctl، ويرجى أيضًا اختبار دعم إيقاف VBUS كما هو موضح أدناه في الأسئلة الشائعة.

لاحظ أن عددًا غير قليل من اللوحات الأم الحديثة تحتوي على موزعات جذرية مدمجة تدعم هذه الميزة - قد لا تحتاج حتى إلى شراء أي موزع خارجي.

ملاحظة حول ازدواجية USB 3.0

إذا كان لديك موزع USB 3.0 متصل بمنفذ USB3 العلوي (upstream)، فسيتم اكتشافه كموزعين افتراضيين مستقلين: USB2 وUSB3، وستتصل أجهزة USB الخاصة بك بأحد الموزعين الافتراضيين USB2 أو USB3 اعتمادًا على قدراتها وسرعة الاتصال. للتحكم في الطاقة لمثل هذه الموزعات، من الضروري إيقاف/تشغيل الطاقة على كلٍّ من الموزعين الافتراضيين USB2 وUSB3 حتى تسري تغييرات إيقاف/تشغيل الطاقة. سيحاول uhubctl القيام بذلك تلقائيًا (إلا إذا عطّلت هذا السلوك باستخدام الخيار -e).

لسوء الحظ، بينما تقطع معظم الموزعات اتصال بيانات USB، قد لا يقطع البعض منها VBUS عن المنفذ، مما يعني أن الهاتف المتصل قد يستمر في الشحن من منفذ تم إيقاف تشغيله بواسطة uhubctl.

التثبيت

بالنسبة إلى Linux وMacOS، يتوفر uhubctl في مديري الحزم القياسيين ويمكن تثبيته بالأوامر التالية:

• MacOS: brew install uhubctl أو sudo port install uhubctl
  • ⚠️ MacOS 26+ يتطلب libusb 1.0.30 أو أحدث!
• Ubuntu/Debian/Raspbian: sudo apt install uhubctl
• Redhat/EPEL/Fedora/CentOS: sudo yum install uhubctl
• OpenSUSE: sudo zypper install uhubctl
• FreeBSD: cd /usr/ports/sysutils/uhubctl && sudo make install

لكن إصدار uhubctl المثبت من مدير الحزم القياسي قد لا يكون بالضرورة أحدث إصدار، أو قد يكون متأخرًا بشكل كبير عن الإصدار الحالي. إذا كان أحدث إصدار منشور من uhubctl أحدث مما يوفره مدير الحزم لديك، فقد تحتاج إلى تجميعه وتثبيته من المصدر كما هو موضح أدناه.

التجميع

تم اختبار هذه الأداة لتُجمَّع وتعمل على Linux (Ubuntu/Debian/Raspbian، Redhat/EPEL/Fedora/CentOS، Arch Linux، Gentoo، openSUSE، Buildroot)، وFreeBSD، وNetBSD، وSunOS، وMacOS.

بينما يُجمَّع uhubctl على Windows، فإن تبديل طاقة USB لا يعمل على Windows لأن libusb يستخدم برنامج تشغيل winusb.sys، والذي وفقًا لمايكروسوفت لا يدعم طلبات التحكم في USB اللازمة. قد يتم إصلاح هذا إذا بدأ libusb في دعم برنامج تشغيل مختلف على Windows.

لاحظ أنه يُنصح بشدة بتثبيت الأداة pkgconf (أو pkg-config) (غالبًا تكون مثبتة افتراضيًا).

أولاً، تحتاج إلى تثبيت مكتبة libusb-1.0 (الإصدار 1.0.13 أو أحدث مطلوب، ويُوصى بالإصدار 1.0.23 أو أحدث):

• Ubuntu: sudo apt-get install libusb-1.0-0-dev pkgconf
• Redhat: sudo yum install libusb1-devel pkgconf
• OpenSUSE: sudo zypper install libusb-1_0-devel pkgconf
• MacOS: brew install libusb pkgconf، أو sudo port install libusb-devel pkgconf
• FreeBSD: pkg install gmake pkgconf (libusb مضمنة افتراضيًا)
• NetBSD: sudo pkgin install libusb1 gmake pkgconf
• Windows: غير محدد بعد؟

للحصول على مصدر uhubctl وتجميعه:

git clone https://github.com/mvp/uhubctl
cd uhubctl
make

سيؤدي هذا إلى إنشاء ملف ثنائي uhubctl. يمكنك تثبيته في نظامك كـ /usr/sbin/uhubctl باستخدام:

sudo make install

لاحظ أنه على بعض أنظمة التشغيل (مثل FreeBSD/NetBSD) تحتاج إلى استخدام gmake بدلاً من ذلك للبناء.

الاستخدام

⚠️ على Linux، استخدم sudo أو قم بتهيئة صلاحيات USB كما هو موضح أدناه!

لسرد جميع الموزعات المدعومة:

uhubctl

يمكنك التحكم في الطاقة على منفذ/منافذ USB كما يلي:

uhubctl -a off -p 2

هذا يعني التعامل مع الموزع الذكي الافتراضي وإيقاف تشغيل الطاقة (-a off، أو -a 0) على المنفذ 2 (-p 2). الإجراءات المدعومة هي off/on/cycle/toggle (أو 0/1/2/3). cycle تعني إيقاف تشغيل الطاقة، وانتظار بعض التأخير (قابل للضبط باستخدام -d)، ثم إعادة تشغيلها. يمكن أن تكون المنافذ قائمة مفصولة بفواصل، ويمكن استخدام - للنطاقات، مثل 2، أو ، أو ، أو .> ⚠️ قد يؤدي إيقاف تشغيل منافذ USB المدمجة إلى قطع اتصال لوحة المفاتيح أو الماوس، لذا كن حذرًا بشأن المنافذ التي تقوم بإيقاف تشغيلها!

إذا كان لديك أكثر من موزع USB ذكي واحد متصل، يجب عليك اختيار موزع محدد للتحكم فيه باستخدام معامل -l (الموقع). للعثور على مواقع الموزعات، ما عليك سوى تشغيل uhubctl بدون أي معاملات. تبدو مواقع الموزعات مثل b-x.y.z، حيث b هو رقم ناقل USB، وx, y, z... هي أرقام المنافذ لجميع الموزعات في السلسلة، بدءًا من الموزع الجذر لناقل USB معين. هذا العنوان شبه مستقر - لن يتغير إذا قمت بفصل/إعادة توصيل (أو إيقاف تشغيل/تشغيل) جهاز USB في نفس المنفذ الفعلي (تُستخدم هذه الطريقة أيضًا في نواة لينكس).

أذونات USB في لينكس

على لينكس، يجب عليك تكوين أذونات USB الخاصة بـ udev (وإلا سيتعين عليك تشغيله كجذر باستخدام sudo uhubctl).

ابتداءً من نواة لينكس 6.0، توجد واجهة قياسية لتشغيل منافذ موزع USB أو إيقاف تشغيلها، وسيحاول uhubctl استخدامها (بدلاً من libusb) لضبط حالة المنفذ. ولهذا السبب توجد قواعد إضافية لنواة 6.0+. لا ضرر من وجود هذه القواعد على الأنظمة التي تعمل بإصدارات أقدم من النواة.

لإصلاح أذونات USB، قم أولاً بتشغيل sudo uhubctl ولاحظ جميع vid:pid للموزعات التي تحتاج إلى التحكم فيها. ثم أضف قواعد udev كما في الأسفل إلى الملف /etc/udev/rules.d/52-usb.rules (استبدل 2001 بمعرّف البائع الخاص بموزعك، أو أزل مرشح ATTR{idVendor} تمامًا للسماح بالوصول إلى أي موزع USB):

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="2001"
# Linux 6.0 or later (its ok to have this block present for older Linux kernels):
SUBSYSTEM=="usb", DRIVER=="hub|usb", \
  RUN="/bin/sh -c \"chmod -f 666 $sys$devpath/*port*/disable || true\""

لاحظ أنه بالنسبة لموزعات USB3، تستخدم بعض الموزعات معرّف بائع مختلفًا لمكونات USB2 مقابل USB3 لنفس الشريحة، وكلاهما يحتاج إلى أذونات لجعل uhubctl يعمل بشكل صحيح. على سبيل المثال، بالنسبة لـ Raspberry Pi 4B، تحتاج إلى إضافة هذين السطرين (أو إزالة مرشح idVendor):

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="2109"
SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0666", ATTR{idVendor}=="1d6b"

إذا لم تعجبك الأوضاع المفتوحة على نطاق واسع 0666، يمكنك تقييد الوصول حسب المجموعة كالتالي:

SUBSYSTEM=="usb", DRIVER=="hub|usb", MODE="0664", GROUP="dialout"
# Linux 6.0 or later (its ok to have this block present for older Linux kernels):
SUBSYSTEM=="usb", DRIVER=="hub|usb", \
  RUN+="/bin/sh -c \"chown -f root:dialout $sys$devpath/*port*/disable || true\"" \
  RUN+="/bin/sh -c \"chmod -f 660 $sys$devpath/*port*/disable || true\""

ثم أضف المستخدمين المسموح لهم إلى مجموعة dialout:

sudo usermod -a -G dialout $USER

لكي تدخل تغييرات قاعدة udev حيز التنفيذ، أعد التشغيل أو نفّذ:

sudo udevadm trigger --attr-match=subsystem=usb

لراحتك، تم توفير قاعدة udev جاهزة للاستخدام هنا.

الأسئلة الشائعة

ما هو تبديل الطاقة لكل منفذ في USB؟

وفقًا لمواصفة USB 2.0، يمكن لموزعات USB الإعلان عن عدم وجود تبديل للطاقة، أو تبديل طاقة مجمّع (جميع المنافذ في وقت واحد)، أو تبديل طاقة لكل منفذ (فردي). لاحظ أن uhubctl افتراضيًا سيكتشف فقط موزعات USB التي تدعم تبديل الطاقة لكل منفذ (ولكن يمكنك إجباره على محاولة العمل على موزعات غير مدعومة باستخدام الخيار -f). يمكنك معرفة نوع تبديل الطاقة الذي يدعمه جهازك باستخدام sudo lsusb -v:

لا يوجد تبديل للطاقة:

wHubCharacteristic 0x000a
  No power switching (usb 1.0)
  Per-port overcurrent protection

تبديل طاقة مجمّع:

wHubCharacteristic 0x0008
  Ganged power switching
  Per-port overcurrent protection

تبديل طاقة لكل منفذ:

wHubCharacteristic 0x0009
  Per-port power switching
  Per-port overcurrent protection

كيف أتحقق مما إذا كان موزع USB الخاص بي مدعومًا بواسطة uhubctl؟

1. شغّل sudo uhubctl. إذا لم يكن موزعك مدرجًا، فهو غير مدعوم. بدلاً من ذلك، يمكنك تشغيل sudo lsusb -v والتحقق من وجود Per-port power switching - إذا لم تتمكن من رؤية مثل هذا السطر في مخرجات lsusb، فإن الموزع غير مدعوم.
2. تحقق من دعم إيقاف تشغيل VBUS (الجهد): قم بتوصيل هاتف أو ضوء USB أو مروحة USB بمنفذ USB في موزعك. حاول استخدام uhubctl لإيقاف تشغيل الطاقة على هذا المنفذ، وتحقق من أن الهاتف يتوقف عن الشحن، أو أن ضوء USB يتوقف عن الإضاءة، أو أن مروحة USB تتوقف عن الدوران. إذا لم يتم إيقاف تشغيل VBUS، فإن الشركة المصنعة لموزعك لم تضمّن دارة لقطع الطاقة فعليًا. سيظل هذا الموزع يعمل لقطع اتصال بيانات USB، لكنه لا يمكنه إيقاف تشغيل الطاقة، ولا نعتبره جهازًا مدعومًا.
3. إذا نجحت الاختبارات أعلاه، فيرجى الإبلاغ عن موزعك عن طريق فتح مشكلة جديدة على https://github.com/mvp/uhubctl/issues، حتى نتمكن من إضافته إلى قائمة الأجهزة المدعومة. يرجى عدم الإبلاغ عن موزعات غير مدعومة، إلا إذا كانت مراجعة أجهزة مختلفة لطراز مدعوم مذكور بالفعل.

لا تتم إزالة أجهزة USB بعد إيقاف تشغيل طاقة المنفذ على لينكس

بعد إيقاف تشغيل طاقة منفذ USB، لا يتلقى udev أي حدث، لذا يبقي ملفات الأجهزة موجودة. ومع ذلك، فإن محاولة الوصول إلى ملفات الأجهزة ستؤدي إلى خطأ إدخال/إخراج.

هذه مشكلة في نواة لينكس وتم إصلاحها منذ uhubctl 2.5.0 للأنظمة التي تعمل بنواة لينكس 6.0 أو أحدث.

إذا كنت لا تزال تستخدم لينكس 5.x أو أقدم، يمكنك استخدام هذا الحل البديل لهذه المشكلة:

sudo uhubctl -a off -l ${location} -p ${port}
sudo udevadm trigger --action=remove /sys/bus/usb/devices/${location}.${port}/

ستتم إزالة ملف الجهاز بواسطة udev، لكن جهاز USB سيظل ظاهرًا في lsusb. لاحظ أن المسار /sys/bus/usb/devices/${location}.${port} سيكون موجودًا فقط إذا تم اكتشاف الجهاز على هذا المنفذ. عند إعادة تشغيل الطاقة، يجب أن يعيد الجهاز التعداد بشكل صحيح (لا حاجة لاستدعاء udevadm مرة أخرى).

تعود الطاقة للتشغيل بعد بضع ثوانٍ على لينكس

بعض برامج تشغيل الأجهزة في النواة تتفاجأ بإيقاف تشغيل جهاز USB وتحاول تلقائيًا إعادة تشغيله.

هذه مشكلة في نواة لينكس وتم إصلاحها منذ uhubctl 2.5.0 للأنظمة التي تعمل بنواة لينكس 6.0 أو أحدث.

إذا كنت لا تزال تستخدم لينكس 5.x أو أقدم:

يمكنك استخدام الخيار -r N، حيث N هو رقم من 10 إلى 1000 لإصلاح ذلك - سيحاول uhubctl إيقاف تشغيل الطاقة عدة مرات متتالية بسرعة، ويجب أن يؤدي ذلك إلى كبت المشكلة.

تعطيل تفويض USB للجهاز المعني قبل إيقاف تشغيل الطاقة باستخدام uhubctl قد يساعد:

echo 0 > sudo tee /sys/bus/usb/devices/${location}.${port}/authorized

إذا كان جهازك وحدة تخزين ضخمة USB، فإن استدعاء udisksctl قبل استدعاء uhubctl قد يساعد أيضًا:

sudo udisksctl power-off --block-device /dev/disk/...`
sudo uhubctl -a off ...

يتم اكتشاف عدة موزعات بأربعة منافذ، لكن لدي موزع واحد فقط بسبعة منافذ متصل

تبني العديد من الشركات المصنعة للموزعات موزعات USB الخاصة بها باستخدام رقائق USB أساسية بأربعة منافذ. على سبيل المثال، لصنع موزع بسبعة منافذ، يقومون بتوصيل موزعين بأربعة منافذ على التوالي - يُفقد منفذ واحد بسبب التوصيل التسلسلي، لذا يصبح موزعًا 4+4-1=7 منافذ. وبالمثل، يمكن بناء موزع بعشرة منافذ كثلاثة موزعات بأربعة منافذ موصولة على التوالي معًا، مما يعطي 4+4+4-2=10 منافذ قابلة للاستخدام.

لاحظ أنه لا يجب أبدًا محاولة تغيير حالة الطاقة للمنافذ المستخدمة لتوصيل الموزعات الداخلية معًا على التوالي. القيام بذلك سيؤدي إلى إرباك دارة الموزع الداخلية وسيتسبب في سلوك غير متوقع.

Raspberry Pi يوقف الطاقة على جميع المنافذ، وليس فقط المنفذ الذي حددته

هذا هو قيد تصميم عتاد Raspberry Pi. كحل بديل، يمكنك شراء أي موزع USB خارجي من القائمة المدعومة أعلاه، وتوصيله بأي منفذ USB في Raspberry Pi، والتحكم في الطاقة على منافذه بشكل مستقل. أيضًا، توجد موزعات مدعومة مصممة خصيصًا لـ Raspberry Pi، مثل UUGear MEGA4.

كمرجع، طرز Raspberry Pi المدعومة لديها البنية الداخلية التالية لـ USB:

Raspberry Pi B+,2B,3B

• موزع واحد 1-1، المنافذ 2-5 مجمّعة، جميعها يتم التحكم بها عبر المنفذ 2:

  root@kitploit:~

  uhubctl -l 1-1 -p 2 -a 0
  

  محاولة التحكم في المنافذ 3,4,5 لن تفعل شيئًا. المنفذ 1 يتحكم في طاقة Ethernet+WiFi.

Raspberry Pi 3B+

• الموزع الرئيسي 1-1، جميع المنافذ الأربعة مجمّعة، يتم التحكم بها جميعًا عبر المنفذ 2 (يقوم أيضًا بإيقاف تشغيل منافذ الموزع الثانوي). المنفذ 1 يربط الموزع 1-1.1 أدناه، المنفذان 2 و 3 موصولان خارجيًا، المنفذ 4 غير موصول.

  root@kitploit:~

  uhubctl -l 1-1 -p 2 -a 0
  

• الموزع الثانوي 1-1.1 (موصول على التوالي بالرئيسي): 3 منافذ، المنفذ 1 يستخدم لـ Ethernet+WiFi، والمنفذان 2 و 3 موصولان خارجيًا.

Raspberry Pi 4B

⚠️ إذا كان برنامج VL805 الثابت أقدم من 00137ad (تحقق باستخدام sudo rpi-eeprom-update)، عليك تحديث البرنامج الثابت لجعل تبديل الطاقة يعمل على RPi 4B.

• موزع USB2 1، منفذ واحد، يربط فقط الموزع 1-1 أدناه.

• موزع USB2 1-1، 4 منافذ مجمّعة، مطابق لموزع USB3 2 أدناه:

  root@kitploit:~

  uhubctl -l 1-1 -a 0
  

• موزع USB3 2، 4 منافذ مجمّعة، مطابق لموزع USB2 1-1 أعلاه:

  root@kitploit:~

  uhubctl -l 2 -a 0
  

• موزع USB2 3، منفذ واحد، وحدة تحكم OTG. تبديل الطاقة غير مدعوم.

Raspberry Pi 5

يحتوي Raspberry Pi 5 على منفذي USB2 ومنفذي USB3 (إجمالي 4). هذه المنافذ متصلة بأربعة موزعات USB مميزة 1,2,3,4 في تكوين غريب حقًا (ولكن اعتمادًا على نظام التشغيل ومراجعة العتاد، يمكن أن تكون الموزعات ذات الصلة 2,3,4,5). إذا كان جهاز USB3 متصلاً بمقبس أزرق، فسيتم اكتشافه على موزع USB3 2 أو 4. إذا كان جهاز USB2 متصلاً بأي مقبس أو جهاز USB3 متصلاً بمقبس أسود، فسيتم اكتشافه على موزع USB2 1 أو 3. بغض النظر عن نوع اتصال USB2/USB3، تكون المقابس الزرقاء دائمًا المنفذ 1، والمقابس السوداء دائمًا المنفذ 2.

يعلن كل من موزعات USB الأربعة المدمجة عن دعمه لتبديل الطاقة لكل منفذ، لكن هذا غير صحيح. في الواقع، جميع منافذ Raspberry Pi 5 الأربعة مجمّعة معًا في مجموعة واحدة، على الرغم من أنها تنتمي إلى أربعة موزعات USB منطقية مختلفة.

لإيقاف تشغيل طاقة VBUS، يجب تعطيلها عبر جميع الموزعات والمنافذ المدمجة باستخدام: ``` uhubctl -l 2 -a 0 uhubctl -l 4 -a 0

لإعادة تشغيله:   ```
uhubctl -l 2 -a 1
uhubctl -l 4 -a 1

لاحظ أن طاقة VBUS تنخفض فقط إذا كانت جميع المنافذ متوقفة - تشغيل أي منفذ واحد يعيد طاقة VBUS لجميع المنافذ الأربعة.

مشاريع بارزة تستخدم uhubctl

حقوق النشر

حقوق النشر (C) 2009-2026 Vadim Mikhailov

يمكن توزيع هذا الملف وفقًا لشروط وأحكام رخصة جنو العمومية العامة الإصدار الثاني.