التحكم بإضاءة RGB للوحة مفاتيح ASUS ROG Flow Z13 دون الحاجة إلى Armoury Crate

يملك جهاز ASUS ROG Flow Z13 الخاص بي منطقتي إضاءة RGB — لوحة المفاتيح وشريط إضاءة حول حافة اللوحة (tablet) — والدعم الجاهز على لينكس لأي منهما هو "بالتوفيق". Armoury Crate غير موجود في هذا العالم. لذا كتبته بنفسي: واجهة CLI، وتطبيق GTK4، ولوحة متصفح تتحدث مباشرة إلى العتاد، إضافة إلى الجزء الذي لا يكلّف أحد نفسه عناءه: جعل اللون يصمد أمام السكون، وإعادة التشغيل، وفصل لوحة المفاتيح.

ما تحصل عليه

إليك لوحة المتصفح وهي تؤدي عملها:

ملاحظة بصراحة: تظهر المنطقتان أعلاه باللون الأبيض (#ffffff). هذا ليس خللًا. التقطت هذه اللقطات من نسخة معزولة بملف حالة فارغ، ولا يمكن سؤال بروتوكول Aura عن اللون الذي يعرضه حاليًا. آخر لون كتبته الأداة هو الحقيقة الوحيدة الموجودة — وهذه بالضبط هي معضلة التصميم التي بُني حولها هذا المشروع بأكمله. المزيد أدناه.

أربع طرق لتغيير اللون

الخلفية واحدة، وأربعة أبواب أمامية:

الواجهة	الأمر / الوصول	الأنسب لـ
CLI	rgb set all '#00ddcc'	السكربتات، الحفظ اليدوي، SSH
واجهة GTK4	rgb-gui	منتقي ألوان حقيقي بمنزلقات، دون طرفية
لوحة الويب	http://127.0.0.1:3003	هاتف على نفس المكتب، دون تثبيت أي تطبيق
وضع الحفلة	rgb-reactive.py	لون عشوائي جديد مع كل ضغطة زر، للمتعة فقط

# the CLI in one breath
rgb list                       # what zones exist, current known state
rgb set all '#00ddcc'          # set every zone to teal
rgb brightness keyboard 2      # 0-3
rgb on / rgb off               # per-zone or all
rgb restore                    # reapply the last saved color (what the restore service runs)

تُغلّف الواجهة الرسومية (GUI) العمليات ذاتها في مربع حوار ألوان لكل منطقة، ومنزلقات سطوع، وتسع عينات ألوان جاهزة، ومفتاح مزامنة يطبّق تغييرًا واحدًا على كل المناطق. لوحة الويب تطبّق الفكرة نفسها داخل تبويب واحد: منتقي ألوان، مربع hex، منزلق سطوع، مفتاح إيقاف، صف ألوان جاهزة، وAll On / All Off.

بروتوكول Aura HID

تتحدث كلتا المنطقتين — لوحة المفاتيح (USB 0b05:1a30) وشريط الإضاءة (USB 0b05:18c6) — بروتوكول Aura HID الذي فكّك مشروعا g-helper وz13ctl شيفرته أولًا. لا يوثّقه أي مصدر رسمي؛ توصّل إليه أشخاص بتحديق طويل في التقاطات USB، وهذه الأداة تبني على عملهم بدلًا من إعادة اختراعه.

الآلية بسيطة إلى حد يكاد يكون مهينًا:

• تقارير إخراج بحجم 64 بايت، معرّف تقرير 0x5D، محشوة بالأصفار.
• حزمة SetMode: 5d b3 <zone> <mode> <r> <g> <b> <speed> — الوضع 0x00 هو اللون الثابت، وهو كل ما تستخدمه هذه الأداة.
• ثم حزمة Save (5d b5) وحزمة Apply (5d b4) لتثبيت التغيير.
• بايت المنطقة: 0x00 للوحة المفاتيح، 0x01 لشريط الإضاءة. تقف عقدتا hidraw كلتاهما خلف جهاز واحد مُعدَّد عبر USB باسم "N-KEY Device"، وتتجاهل كل واحدة بصمت الحزم الموجّهة إلى المنطقة الأخرى — لذا تعمل نفس الكتابة الثلاثية الحزم على أي من العقدتين.

الحقيقة التي تحكم كل قرار تصميم هنا: البروتوكول للكتابة فقط. يمكنك ضبط لون؛ لكن لا يمكنك أبدًا قراءته مرة أخرى. لذا تحتفظ الأداة بذاكرتها الخاصة — كل لون وسطوع مُطبَّق ينتهي به المطاف في ~/.local/state/rgb-control/state.json، وهذا الملف، لا العتاد، هو السجل الوحيد لما يُفترض أن تبدو عليه لوحة مفاتيحك. خدمة الاستعادة، وخدمة الخمول، ومعالجة إعادة التركيب: كل ذلك موجود لدفع هذا الملف مجددًا نحو عتاد ينسى باستمرار.

يمر الاكتشاف عبر /sys/class/hidraw، ويطابق معرّف البائع/المنتج، ثم يتحقق من وجود معرّف التقرير 0x5D فعليًا في واصف تقرير العقدة قبل الوثوق بها. توجد أيضًا خلفية احتياطية: يعرض برنامج تشغيل النواة asus-wmi فئة LED متعددة الألوان عند /sys/class/leds/asus-*:rgb:*، بملفي multi_intensity وbrightness. تتولى hidraw الكتابة حين تكون متاحة؛ وتوفّر sysfs الحالة الأولية، لأنها بخلاف HID قابلة للقراءة.

كيف تتحول النقرة إلى لون

المسار الكامل من النقرة إلى مصباح LED:

الصمود أمام السكون وإعادة التركيب

كل أداة RGB وجدتها على لينكس كانت قادرة على ضبط لون. لا واحدة منها تذكّرته بعد أول سكون تالٍ، أو إعادة تشغيل، أو — بما أن لوحة مفاتيح Z13 قابلة للفصل — أول إعادة تركيب. كل واحدة من هذه الحالات تعيد ضبط العتاد إلى العتمة، والبروتوكول أحادي الاتجاه (كتابة فقط) يعني أن العتاد لا يملك أدنى فكرة عمّا كان يعرضه. الإصلاح يجب أن يعيش خارج العتاد:

ميزانية إعادة المحاولة البالغة نحو 6 ثوانٍ مهمة: لوحة المفاتيح المُركَّبة حديثًا تحتاج إلى لحظة كي تظهر على الناقل (bus)، ويُطلق udev دفعة من الأحداث أثناء عملية السرد. تنام وحدة الاستعادة ثانية واحدة للسماح للدفعة بالاستقرار، ثم تعيد محاولة الاكتشاف بدلًا من الاستسلام عند أول محاولة فاشلة.

توجد أيضًا خدمة خمول، rgb-idled، مقتصرة على GNOME/Wayland لأنها تنصت لإشارتي D-Bus محددتين: org.gnome.ScreenSaver ActiveChanged (قفل الشاشة ← تعتيم إلى سطوع 1) وorg.gnome.Mutter.IdleMonitor WatchFired (نفس ساعة الخمول التي يستخدمها GNOME لإطفاء الشاشة ← إطفاء الأضواء). عند فتح القفل، تستعيد الحالة من state.json. التفصيلة التي أحبها فعلًا: التعتيم والإطفاء يمران عبر مسار persist=False، لذا لا تكتب هذه الحالات المؤقتة أبدًا فوق لونك المحفوظ. تستيقظ فتجد اللون الذي اخترته أنت، لا آخر ما فعلته الخدمة.

الإعداد

اختبار سريع، دون تثبيت:

cd rgb-control
./rgb-cli list
./rgb-cli set all '#00ddcc'

التثبيت الكامل يربط قاعدة udev، وrgb-restore.service، وخطاف السكون، وقاعدة tmpfiles، ورابطًا رمزيًا ~/.local/bin/rgb، ومُدخَل سطح مكتب، وخدمة المستخدم rgb-idled:

cd rgb-control
sudo ./install.sh

مسارات المُثبِّت قوالب جاهزة (__RGB_DIR__، __RGB_STATE__) تُملأ وقت التثبيت، لذا يعمل من أي مكان فككت فيه الضغط. لوحة الويب خطوة منفصلة واختيارية:

cd rgb-web
node server.js
# → http://127.0.0.1:3003
# PORT= and RGB_CLI= env vars override the defaults

كما يدعم تفعيل مقبس systemd — صفر استهلاك موارد حتى وصول أول طلب، ويخرج بعد 10 دقائق من الخمول. ووضع الحفلة، بلون عشوائي جديد مع كل ضغطة زر، يبعد أمرًا واحدًا: ./rgb-toggle.sh start (سيطلب صلاحيات sudo).

نقاط يجب الانتباه إليها

• الصلاحيات على التوزيعات الأكثر تشددًا. على Fedora/Bazzite، يكون /dev/hidraw* قابلًا للكتابة من الجميع افتراضيًا، لذا يعمل الأمر مباشرة. التوزيعات الأخرى تحتاج عادة إلى قاعدة uaccess من udev (مثال في دليل الإعداد). هذا هو السبب الأول رقم واحد لـ"لا يحدث شيء".
• عُقد LED في sysfs مملوكة للمستخدم root. تقوم قاعدة udev المرفقة بتغيير مجموعتها (chgrp) إلى wheel. لست ضمن تلك المجموعة؟ أضف نفسك إليها أو عدّل القاعدة.
• أسماء عُقد LED تحمل لاحقة خاصة بكل جهاز. شيء مثل asus-0003:0B05:18C6.0008 — ذلك الرقم في النهاية قد يختلف من جهاز لآخر. تحقق من ls /sys/class/leds وعدّل الإعداد إذا لم تجد الخلفية الاحتياطية شيئًا.
• أجهزة rpm-ostree (مثل Bazzite وSilverblue) تملك /usr للقراءة فقط. يستهدف المُثبِّت عن قصد /etc لخطاف السكون. لا "تُصلحه" وتعيده.
• لا تعمل rgb-idled إلا على GNOME. على KDE أو X11 المجرّد، تبدأ التشغيل بلا مشكلة لكنها لا تفعل شيئًا أبدًا. هذا متوقّع، وليس عطلًا.
• لوحة الويب بلا تسجيل دخول، عن قصد. ترتبط بـ 127.0.0.1 فقط، لأنها تستدعي التحكم بالعتاد عبر الصدفة دون أي مصادقة أمامها. يقول كود الخادم ذلك بوضوح: لا تربطه بـ 0.0.0.0 دون إضافة مصادقة أولًا. توجد حماية من اجتياز المسارات (path traversal) على الملفات الثابتة، لكن الحماية ليست بديلًا عن تسجيل الدخول.
• إعادة التركيب تتسابق مع نفسها قليلًا. إعادة تركيب فعلية واحدة قد تُطلق عدة أحداث udev؛ يغفو مسار الاستعادة لبرهة قصيرة لدمجها معًا، لذا قد تعود الأضواء للومان متأخرة قليلًا. تلك نافذة الدمج تؤدي عملها، وليست تأخيرًا.

التنزيلات

• تنزيل الكود المصدري لـ rgb-keyboard (zip) 39 KB

مجاني للاستخدام الشخصي. إذا وفّر لك عصرًا كاملًا من الوقت، فزر القهوة قريب منك.