بناء البرنامج الثابت من المصدر

تحذير

لسنا مسؤولين عن تعطّل لوحات المفاتيح بشكل دائم، وهذه المعلومات مقدمة للمستخدمين المتقدمين الذين يتحملون جميع المخاطر المرتبطة بتثبيت البرامج الثابتة على أجهزتهم.

سيؤدي ذلك إلى استبدال أي تخطيطات مفاتيح مخصصة أنشأتها!

إذا أردت إجراء أي تغييرات على تخطيط مفاتيح (keymap) لوحة مفاتيح أو إضافة دعم للوحات مفاتيح جديدة إلى بروتوكول SignalRGB QMK، فستحتاج إلى بنائه من المصدر.

خطوات البناء من المصدر:

1. نزّل QMK MSYS من هنا وثبّته.

افتح QMK MSYS ونفّذ أمر git clone لنسخة QMK المشتقة / المصدر الذي تحتاجه. (قد يكون ذلك QMK Mainline _أو SonixQMK).

بعد ذلك، ستحتاج إلى إضافة الوحدة الفرعية (submodule) لبروتوكول SignalRGB إلى النسخة المشتقة / المصدر الذي تبني عليه:

// cd to your source fork you will be compiling against in the terminal (QMK_MSYS, bash, etc)
git submodule add https://github.com/SRGBmods/QMK_Community_Module modules/signalrgb
git submodule update --init --recursive

2. الصق الأمرين أعلاه في نافذة الطرفية (QMK_MSYS أو bash أو غيرها).
3. ستحتاج إلى إضافة ملف keymap.json بالمحتوى التالي في مجلد العلامة التجارية الخاص بلوحة مفاتيحك:

{
    "modules": [
        "signalrgb"
    ]
}

ملاحظة: استبدل KEYBOARD BRAND بالعلامة التجارية للوحة مفاتيحك، وMODEL بطراز لوحة المفاتيح، واستبدل KM بنوع تخطيط المفاتيح (default / via / keychron / إلخ).

أنواع تخطيطات المفاتيح:

• default: هذا هو تخطيط المفاتيح الذي ستستخدمه إذا لم تكن تبني من أجل VIA
• via: هذا هو تخطيط المفاتيح الذي تستخدمه إذا كنت تبني من أجل VIA (يُفضّل أن تجرّب هذا أولًا - يمكنك العثور على تخطيط via الخاص بك هنا)

• إذا فشل بناء البرنامج الثابت، انضم إلى Discord واطلب المساعدة في قنوات QMK.

الآن بعد أن بنيت البرنامج الثابت، ستحتاج إلى تثبيته على لوحة مفاتيحك.

• ستحتاج إلى البحث عبر الإنترنت عن تعليمات التثبيت الخاصة بلوحة مفاتيحك، لأن تعليمات التثبيت تختلف من لوحة مفاتيح إلى أخرى.

4. بعد تثبيت البرنامج الثابت على لوحة مفاتيحك، ستحتاج إلى تعديل إضافة لوحة المفاتيح أدناه لجعل SignalRGB يعمل مع لوحة مفاتيحك.

مجلد يحتوي على أمثلة لإضافات QMK

• بعد تنزيل إضافة لوحة المفاتيح أعلاه، افتحها في محرر نصوص.

export function Name() { return "QMK Keyboard"; }
export function Version() { return "X.X.X"; }
export function VendorId() { return 0x0000; }
export function ProductId() { return 0x0000; }
export function Publisher() { return "WhirlwindFX"; }
export function Size() { return [14, 5]; }
export function DefaultPosition(){return [10, 100]; }
export function DefaultScale(){return 8.0;}
/* global
shutdownColor:readonly
LightingMode:readonly
forcedColor:readonly
*/
export function ControllableParameters()
{
  return [
    {"property":"shutdownColor", "group":"lighting", "label":"Shutdown Color", "min":"0", "max":"360", "type":"color", "default":"009bde"},
    {"property":"LightingMode", "group":"lighting", "label":"Lighting Mode", "type":"combobox", "values":["Canvas", "Forced"], "default":"Canvas"},
    {"property":"forcedColor", "group":"lighting", "label":"Forced Color", "min":"0", "max":"360", "type":"color", "default":"009bde"},
  ];
}

5. بعد فتح إضافة لوحة المفاتيح، ستظهر لك شاشة مشابهة للشاشة أعلاه.

• ستحتاج إلى ملء بعض هذه الحقول، بدءًا من الحقل Name.
• يجب ملء الحقل Name باسم لوحة المفاتيح التي طوّرت البرنامج الثابت من أجلها.

export function Name() { return "Massdrop CTRL QMK Keyboard"; }

6. بعد ذلك، نحتاج إلى ملء VendorId الخاص بلوحة المفاتيح.

• للعثور على VendorId الخاص بلوحة المفاتيح، افتح SignalRGB.
• ثم انقر على ترس الإعدادات في الزاوية السفلية اليسرى.

ثم انقر على معلومات الجهاز.

ثم ابحث عن لوحة مفاتيحك ودوّن قيمتي VendorID وProductID الخاصتين بها.

الآن املأ الحقلين VendorId وProductId بهاتين القيمتين.

export function Name() { return "Massdrop CTRL QMK Keyboard"; }
export function VendorId() { return 0x04d8; }
export function ProductId() { return 0xEED2; }

7. الحقل التالي الذي يجب ملؤه هو الحقل Publisher. في الحقل Publisher، يمكنك وضع اسمك أو اسم المستخدم أو المعرّف الخاص بك.

export function Name() { return "Massdrop CTRL QMK Keyboard"; }
export function VendorId() { return 0x04d8; }
export function ProductId() { return 0xEED2; }
export function Publisher() { return "WhirlwindFX"; }

8. الآن انتهينا من ملء الحقول، وننتقل إلى المصفوفات.

هناك 3 مصفوفات تحتاج إلى تعديل: vKeys وvKeynames وvKeyPositions

• تربط المصفوفة vKeys كل مفتاح في لوحة المفاتيح بموضعه داخل بيانات RGBData المُرسلة إلى لوحة المفاتيح.
• تخبرنا المصفوفة vKeyNames بالمفتاح المقابل لكل vKey وvKeyPosition.
• تخبر المصفوفة vKeyPositions برنامج SignalRGB بموضع كل مفتاح على لوحة المفاتيح.
• أولًا، غيّر المصفوفة vKeyNames لتعكس لوحة مفاتيحك.
• هذا يعني أنك تحتاج إلى إعادة ترتيب vKeyNames بحيث تطابق لوحة مفاتيحك.
  • في حالتنا، اضطررنا إلى إزالة بعض المفاتيح وإعادة تنظيم المفاتيح المتبقية لأن لوحتنا من نوع TKL.

ثم حدّث المصفوفة vKeyPositions بنفس الطريقة التي حدّثت بها المصفوفة vKeyNames.

أخيرًا، حدّث المصفوفة vKeys بحيث تطابق المصفوفتين vKeyNames وvKeysPositions.

9. الآن، احفظ ملف الإضافة في %userprofile%/Documents/WhirlwindFX/plugins، ثم أعد تشغيل SignalRGB.

• من المفترض أن تبدأ لوحة مفاتيحك بالإضاءة والتفاعل مع SignalRGB.

إذا لم تُضئ لوحة المفاتيح أو لم تتفاعل بشكل صحيح مع SignalRGB:

1. انتقل إلى صفحة الأجهزة في SignalRGB.

2. بعد ذلك، انتقل إلى لوحة مفاتيحك، ثم انقر على ترس الإعدادات.

3. ثم انقر على مفتاح التبديل إظهار وحدة التحكم.

• يجب أن يظهر في وحدة التحكم إجمالي عدد مصابيح LED في الجهاز (Device Total LED Count). قارن هذا العدد بعدد مصابيح LED التي خصصتها.
  • في حالتنا، يوجد 119 مصباح LED إجمالًا.

إذا كان عدد مصابيح LED يطابق عدد vKeys لديك:

• تأكد من أن حقل Size في إضافتك أكبر بمقدار 1 في كل اتجاه من أعلى إحداثي لمصابيح LED:
  • في حالتنا، يقع أبعد مصباح LED في الموضع [17,6]، لذا يجب أن يكون حقل Size هو [18,7].

export function Size() { return [18, 7]; }

إذا كان عدد مصابيح LED لا يطابق عدد vKeys لديك:

• ستحتاج إلى إضافة vKeys وvKeyPositions وvKeyNames لتطابق إجمالي عدد مصابيح LED.
  • في حالتنا، كان الجهاز يحتوي على 119 مصباح LED، لذا احتجنا إلى إضافة 32 مصباح LED للإضاءة السفلية للوحة المفاتيح.

• إذا كان عدد vKeys يطابق إجمالي عدد مصابيح LED وكان حجم الجهاز مضبوطًا بشكل صحيح، لكن مصابيح LED مربوطة بشكل غير صحيح:
• انضم إلى Discord واطلب المساعدة في قنوات QMK.

كيفية إصلاح وميض مصابيح LED المؤشرات (CAPSLOCK وNUMLOCK وSCROLL-LOCK) عندما يكون SignalRGB والمفتاح نشطين.

يتطلب هذا بعض الجهد لأنه يستلزم معرفة مسبقة بقيم الفهرس (Index) الخاصة بمؤشراتك (CAPS وNUM وSCROLL). (يمكن العثور على ذلك عادةً في النوع الفرعي للجهاز ansi/iso أو مباشرةً في <keyboard_name.c>، ابحث عن g_led_config واربط الفهرس بصريًا بالمفتاح الذي يمثله، أو بعد أن تعمل إضافة SignalRGB لديك يمكنك الحصول على المعرّف منها وإعادة البناء مع هذا التعديل!)

ملاحظة

تُظهر الصورة أدناه فهرس Keychron Q6، لذا سيكون 61 هو caps lock، و14 هو scroll lock، و37 هو num lock عند مراجعة الملف ansi_encoder.c — ليس من السهل ربطها بصريًا، لذا سيكون الجمع بين هذا الملف وvKeys في الإضافة مفيدًا!

بمجرد معرفة القيمة (القيم) أعلاه، يلزم إجراء تعديل بسيط على signalrgb.c أو via.c حسب بنية البرنامج الثابت لديك. استبدل CAPSLOCK_LED_INDEX_،_ NUM___LOCK_LED_INDEX، أو SCROLL_LOCK_LED_INDEX بقيم الفهرس الخاصة بلوحة مفاتيحك.

فإذا كان فهرس CAPS_LOCK هو 61، فإن هذا السطر:

if ((index + i) == CAPS_LOCK_LED_INDEX && host_keyboard_led_state().caps_lock) {

يصبح هذا السطر:

if ((index + i) == 61 && hostkeyboard led_state().caps_lock) {

يلي ذلك مثال على الشيفرة الكاملة (يستبدل هذا الدالة “led_streaming” بالكامل):

void led_streaming(uint8_t *data) //Stream data from HID Packets to Keyboard.
{
    uint8_t index = data[1];
    uint8_t numberofleds = data[2];

    if(numberofleds >= 10)
    {
        packet[1] = DEVICE_ERROR_LEDS;
        raw_hid_send(packet,32);
        return;
    }

    for (uint8_t i = 0; i < numberofleds; i++)
    {
      uint8_t offset = (i * 3) + 3;
      uint8_t  r = data[offset];
      uint8_t  g = data[offset + 1];
      uint8_t  b = data[offset + 2];

      /* ONLY USE ONE OF THESE */
      /* Remove the // from the beginning of the line you wish to use and update the INDEX accordingly */

      /* This is for all three CAPS, NUM, and SCROLL LOCKS */
      // if ( ((index + i) == CAPS_LOCK_LED_INDEX && host_keyboard_led_state().caps_lock) || ((index + i) == NUM_LOCK_LED_INDEX && host_keyboard_led_state().num_lock) || ((index + i) == SCROLL_LOCK_LED_INDEX && host_keyboard_led_state().scroll_lock))   {

      /* This is for CAPS and NUM LOCK */
      // if ( ((index + i) == CAPS_LOCK_LED_INDEX && host_keyboard_led_state().caps_lock) || ((index + i) == NUM_LOCK_LED_INDEX && host_keyboard_led_state().num_lock))   {

      /* This is for CAPS LOCK */
      // if ((index + i) == CAPS_LOCK_LED_INDEX && host_keyboard_led_state().caps_lock)   {

      /* This is for NUM LOCK */
      // if ((index + i) == NUM_LOCK_LED_INDEX && host_keyboard_led_state().num_lock)  {

      /* ONLY USE ONE OF THE ABOVE */

      rgb_matrix_set_color(index + i, 255, 255, 255);
      } else {
      rgb_matrix_set_color(index + i, r, g, b);
      }
     }
}

** انضم إلى Discord واطلب المساعدة في قناة QMK custom-builds إذا واجهت أي مشكلات في التعليمات أعلاه! **

تنبيه

يُرجى ملاحظة أن SignalRGB وVIA لا يعملان معًا بشكل جيد في الوقت نفسه. يجب عليك إغلاق VIA (أو إغلاق علامة تبويب المتصفح) قبل تشغيل SignalRGB، أو إغلاق SignalRGB قبل محاولة استخدام VIA، لأن آلية raw_hid_receive التي يستخدمها كلا البرنامجين تتعارض مع بعضها.

ملاحظة

حاليًا، لوحات مفاتيح QMK مدعومة في الوضع السلكي فقط. أوضاع Bluetooth واللاسلكي 2.4Ghz غير مدعومة حاليًا. قد لا يُدعم Bluetooth أبدًا بوضعه الحالي بسبب قيود عرض النطاق الترددي؛ وقد يُدعم 2.4Ghz في المستقبل اعتمادًا على طريقة تنفيذ المستقبِل اللاسلكي (dongle) والبرنامج الثابت.