تحديد نوع الكتابة للجهاز

بعد أن تعرف نوع البروتوكول لجهازك، قد تظل بحاجة إلى تحديد دالة الكتابة المحددة التي يجب استخدامها. فأجهزة HID على وجه الخصوص لديها طريقتا كتابة مختلفتان تستهدفان آليتي نقل USB مختلفتين.

device.write

ترسل device.write() البيانات باستخدام نقل الجملة أو المقاطعة على نقطة نهاية HID المحددة حاليًا للجهاز. هذا هو مسار الكتابة القياسي ويعمل مع غالبية الأجهزة.

استخدم device.write() عندما:

يرسل الجهاز ويستقبل تقارير ثابتة الطول عبر نقل المقاطعة
يُظهر التقاط Wireshark عمليات نقل URB_INTERRUPT
لا يستخدم الجهاز معرّف تقرير HID (Report ID) على نقطة النهاية المحددة (مما يتطلب حشوًا صفريًا — انظر أدناه)

var packet = [];
packet[0] = 0xEC;
packet[1] = 0x40;
packet[2] = channel;
packet = packet.concat(RGBData);

device.write(packet, 65);

device.send_report

ترسل device.send_report() البيانات باستخدام عملية نقل تحكم HID من نوع SET_REPORT. وهي تستهدف آلية تقارير ميزات HID بدلًا من نقطة نهاية المقاطعة.

استخدم device.send_report() عندما:

يُظهر التقاط Wireshark عمليات نقل URB_CONTROL مع طلب SET_REPORT (رمز الطلب 0x09)
تُرجع device.write() الخطأ “incorrect function” على جميع نقاط النهاية
يستخدم الجهاز صراحةً تقارير ميزات HID لواجهة الأوامر الخاصة به

device.send_report([0x07, 0x03, 0x06, 0x01, 0x00], 65);

دالة القراءة المرافقة لتقارير الميزات هي device.get_report()، التي تُصدر عملية نقل تحكم من نوع GET_REPORT. استخدمها عندما تحتاج إلى قراءة الإعدادات عبر آلية تقارير الميزات نفسها.

أيهما تجرّب أولًا

إذا لم تكن متأكدًا، فابدأ بـ device.write(). فهي تعمل مع غالبية أجهزة HID. إذا ظهر لك الخطأ “incorrect function”، فانتقل إلى device.send_report(). وإذا فشلت كلتاهما، فتحقق من أنك اخترت نقطة النهاية الصحيحة.

العَرَض	جرّب
يعمل كما هو متوقع	لقد انتهيت
الخطأ “Incorrect function”	انتقل إلى `device.send_report()`
الخطأ “Access is denied”	نقطة نهاية خاطئة — راجع اختيار نقاط النهاية
لا يوجد خطأ، لكن الجهاز لا يستجيب	نقطة نهاية خاطئة، أو نوع جهاز خاطئ

الحشو الصفري

تتطلب بعض أجهزة HID أن يكون البايت الأول من كل حزمة 0x00. يحدث هذا عندما لا يكون للجهاز معرّف تقرير (Report ID) مخصص لنقطة النهاية المحددة — إذ يحذف برنامج تشغيل HID البايت 0 قبل تمرير البيانات إلى الجهاز، لذا تحتاج إلى إزاحة كل شيء بمقدار موضع واحد للتعويض.

علامات تدل على أنك بحاجة إلى الحشو الصفري:

يُظهر التقاط Wireshark أول بايت أمر ذي معنى عند الإزاحة 1، وليس عند الإزاحة 0
بدون البايت الصفري، يتجاهل الجهاز الحزمة أو يُنتج مخرجات عشوائية

كيفية تطبيقه:

// Without zero padding (packet size 64)
packet[0] = 0xEC;  // command
packet[1] = 0x40;
device.write(packet, 64);

// With zero padding (packet size 65)
packet[0] = 0x00;  // padding byte — consumed by HID driver
packet[1] = 0xEC;  // command now at offset 1
packet[2] = 0x40;
device.write(packet, 65);

القاعدة العامة: إذا أظهر التقاط Wireshark حزمة بحجم 64 بايت لكن device.write(packet, 64) لا تعمل، فجرّب device.write(packet, 65) مع packet[0] = 0x00 وإزاحة جميع البايتات الأخرى بمقدار موضع واحد.

قراءة البيانات

تتبع دوال القراءة المقابلة التقسيم نفسه:

طريقة الكتابة	طريقة القراءة المقابلة	نوع النقل
`device.write()`	`device.read()`	الجملة / المقاطعة
`device.send_report()`	`device.get_report()`	التحكم (GET_REPORT)

لقراءة تقارير الإدخال تحديدًا (وليس تقارير الميزات)، استخدم device.input_report(). راجع الاتصال المتقدم لمزيد من التفاصيل.