12.3. صيغة الحزمة¶

كل بايت يعبر الإرسال بين الكاميرا والمضيف هو جزء من حزمة. تبدأ الحزمة بترويسة من 10 بايتات، ثم تأتي حمولة متغيرة الطول، وتنتهي بـ CRC في الذيل من 4 بايتات. ولا تظهر أي بايتات أخرى على الإرسال -- فبمجرد أن يرى المضيف كلمة المزامنة ذات البايتين، تكون البايتات التالية ترويسة بهذا التسلسل بالضبط.

A horizontal layout of a protocol packet showing the 10-byte header (sync word, sequence number, channel ID, flags, opcode, payload length, header CRC) followed by the variable-length payload and a 4-byte payload CRC.

12.3.1. الترويسة¶

عشرة بايتات، محزومة دون حشو. كل حقل:

sync -- الكلمة ذات الـ 16 بت 0xD5AA بترتيب صغير الطرف (little-endian). البايت 0 على الإرسال هو 0xAA والبايت 1 هو 0xD5. يستطيع المستقبِل الذي يمسح البايتات أن يجد بداية حزمة بالبحث عن الزوج AA D5؛ وأي شيء قبله يُعامل كنفاية. واختيار القيمة متعمّد: نادرًا ما تظهر 0xAA و0xD5 في النص القابل للطباعة، ومن غير المرجح أن يحدث الزوج بالصدفة في منتصف حمولة.
seq -- بايت واحد. عدّاد يتزايد بمقدار واحد لكل حزمة تُرسل في اتجاه معيّن. يتحقق المستقبِل من أن رقم تسلسل الحزمة التالية هو المتوقع؛ وإن لم يكن، تطلب طبقة الموثوقية إعادة الإرسال.
chan -- بايت واحد. معرّف القناة التي تنتمي إليها هذه الحزمة. القنوات 0..31 قابلة للاستخدام؛ وتأخذ القنوات المدمجة stdin وstdout وstream و(اختياريًا) profile معرّفات ثابتة تحجزها الكاميرا.
flags -- بايت واحد. حقل بتات يخبر المستقبِل بكيفية تفسير الحزمة:
- البت 0 ACK -- هذه الحزمة إقرار بحزمة سابقة.
- البت 1 NAK -- هذه الحزمة ترفض حزمة سابقة.
- البت 2 RTX -- هذه الحزمة هي إعادة إرسال.
- البت 3 ACK_REQ -- يريد المرسِل إقرارًا بهذه الحزمة.
- البت 4 FRAGMENT -- تتبع هذه الحزمة أجزاء أخرى في رسالة أكبر.
- البت 5 EVENT -- تحمل هذه الحزمة حدث قناة بدلًا من بيانات.
- البتان 6 و7 محجوزان.
opcode -- بايت واحد. رمز الأمر أو الرد. تحجز مكتبة البروتوكول نطاقات رموز التشغيل بحسب الغرض:
- 0x00..0x0F -- أوامر البروتوكول (SYNC وGET_CAPS وSET_CAPS وSTATS وVERSION).
- 0x10..0x1F -- أوامر النظام (RESET وBOOT وINFO وEVENT وMEMORY).
- 0x20..0x2F -- أوامر القنوات (LIST وPOLL وLOCK وUNLOCK وSHAPE وSIZE وREAD وWRITE وIOCTL وEVENT).
len -- بايتان، صغيرا الطرف (little-endian). عدد بايتات الحمولة التي تلي الترويسة. الطول صفر مشروع -- فكثير من الإقرارات والأوامر الصغيرة لا تحمل حمولة.
crc -- بايتان. CRC-16 على بايتات الترويسة الثمانية السابقة. والمستقبِل الذي يحصل على ترويسة بـ CRC سيئ يُسقط الحزمة بأكملها دون حتى النظر إلى الحمولة.

12.3.2. الحمولة¶

صفر بايت أو أكثر، تعاملها طبقة التأطير كبيانات معتمة. وما في الحمولة يعتمد على رمز التشغيل: ففي رد CHANNEL_READ تكون بيانات القناة الفعلية؛ وفي رد GET_CAPS تكون بنية صغيرة ثابتة؛ وفي كتابة قناة تكون ما أرسله المضيف أيًّا كان.

يعتمد أقصى حجم للحمولة على حجم مخزن البروتوكول المؤقت في الكاميرا (راجع جدول كل لوحة في protocol.init()). والرسائل الأطول من الحد الأقصى تُقسَّم إلى أجزاء مع ضبط علم FRAGMENT على كل الأجزاء عدا الأخير.

12.3.3. CRC الذيل¶

أربعة بايتات، CRC-32 على الحمولة. يلتقط التلف الذي لا يستطيع CRC الترويسة رؤيته، لا سيما في الحمولات الطويلة حيث قد يفلت خطأ بت واحد في منتصف الإطار لولا ذلك.

تقسيم فحص السلامة على CRC اثنين أمر متعمّد. يحمي CRC الترويسة حقول التأطير ذاتها -- لا سيما طول الحمولة. فبدون CRC منفصل للترويسة، يؤدي انقلاب بت واحد في بايت الطول إلى قراءة المستقبِل عددًا خاطئًا من البايتات للحمولة وفقدان المزامنة مع تدفق البايتات بالكامل؛ ومع وجوده، تُرفض الترويسة التالفة فورًا ويعيد المستقبِل المسح بحثًا عن كلمة المزامنة التالية. ثم يحمي CRC الحمولة جسم الرسالة كشأن منفصل، فيُبلَّغ عن انقلاب بت في البيانات كحمولة تالفة بدلًا من الخلط بينه وبين خطأ تأطير.

الصيغة صغيرة بما يكفي للمرور عليها بايتًا بايتًا، وكون كل حزمة لها التخطيط ذاته -- مزامنة، ثم ترويسة، ثم حمولة، ثم CRC -- يعني أن محلِّلًا مكتوبًا يدويًا يتسع في شاشة من الشيفرة. ولهذا فإن تنفيذًا صغيرًا للمضيف بلغة C أو Python أو Rust هو مشروع عطلة نهاية أسبوع؛ ومكتبة البروتوكول هي نسخة Python المصانة على كل جانب.