> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# إدارة الطابعات عن بعد مع Klipper وOctoPrint
- URL: https://arabroot.io/articles/ادارة-الطابعات-ثلاثية-الابعاد-عن-بعد-klipper-مع-octoprint/
- Published: 2026-11-20T04:36:00.000Z
- Updated: 2026-11-20T05:34:41.000Z
- Description: كيف تدير طابعتك من المتصفح بـ Klipper أو OctoPrint، مع مختبر يشغل طابعة وهمية ويطبع عليها قطعة كاملة ويقرأ سجلاتها.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, الإلكترونيات والطائرات المسيرة والطباعة ثلاثية الأبعاد, Klipper

إذا كانت لديك طابعة ثلاثية الأبعاد 3D Printer في غرفة أخرى أو في زاوية الورشة، فأنت تعرف هذا اليوم جيداً: تقطع الملف في برنامج التقطيع Slicer على جهازك، ثم تنسخه إلى بطاقة SD، وتمشي بها إلى الطابعة، وتختار الملف من شاشة صغيرة بزر دوار، ثم تقف بجانبها حتى تنتهي الطبقة الأولى لأنك لا تثق بها، وبعد ساعتين تعود لترى هل انتهت أم تحولت القطعة إلى كومة من الخيوط. ومع طابعة واحدة يمكن احتمال هذا، ولكن عندما تصبح الطباعة جزءاً من عملك، فتطبع علب الأجهزة التي صممتها وقطع التثبيت لعملائك، أو تصبح لديك ثلاث طابعات في مختبر صغير، فإن هذا الأسلوب يأكل وقتك ويخفي عنك الأعطال حتى تصبح خسارة كاملة.

والحل الذي يستخدمه أغلب من يطبع بجدية هو أن يضع بجانب الطابعة حاسوباً صغيراً مثل Raspberry Pi، ويشغل عليه برنامجاً يدير الطابعة من المتصفح Browser: ترفع الملف من جهازك، وتبدأ الطباعة، وترى الحرارة والتقدم والكاميرا من أي مكان في الشبكة، وتوقفها أو تلغيها بزر. وهناك طريقتان مشهورتان لهذا: OctoPrint الذي يرسل الملف إلى البرنامج الثابت Firmware الموجود في الطابعة سطراً سطراً، وKlipper الذي يغير طريقة عمل الطابعة نفسها وينقل الحساب كله إلى الحاسوب، ومعه Moonraker وواجهة Mainsail أو Fluidd.

وفي هذا المقال من مرحلة الطباعة ثلاثية الأبعاد سوف نفهم الطريقتين من الداخل، ثم نبني طابعة وهمية حقيقية التشغيل داخل Docker: Klipper بإصداره v0.13.0 مع متحكم يعمل كبرنامج على Linux، وMoonraker وMainsail، ونطبع عليها ملف G-code كاملاً قطعناه بـ PrusaSlicer، ثم نطبع الملف نفسه على الطابعة الافتراضية في OctoPrint 2.0.1\. ولن تكون التجربة نظيفة من أول مرة، فقد واجهنا ست مشكلات حقيقية قبل أول طبقة، وكل واحدة منها تشرح شيئاً عن كيفية عمل Klipper أهم من أي فقرة نظرية.

وسوف نناقش في هذا المقال ما يلي:

- لماذا تدير الطابعة عن بعد Remote Management، وما الذي تكسبه وما الذي تخاطر به.
- البرنامج الثابت Firmware داخل الطابعة: كيف يعمل Marlin، ولماذا قسم Klipper العمل بين حاسوب ومتحكم دقيق Microcontroller.
- الطبقات الأربع في Klipper: المتحكم، والمضيف klippy، وMoonraker، والواجهة Mainsail أو Fluidd.
- OctoPrint والإرسال سطراً سطراً Serial Streaming، وأرقام الأسطر ومجموع التحقق Checksum.
- تجربة عملية كاملة: طابعة وهمية في Docker، وست مشكلات حقيقية وحلولها، وطباعة ملف كامل مع إيقاف واستئناف، ثم ماذا يحدث إذا ضعف السخان.
- تشكيل الإدخال Input Shaper وضغط الخيط Pressure Advance كما تشرحهما وثائق Klipper.
- الأمان وإدارة عدة طابعات، وجدول يساعدك على الاختيار بين Klipper وOctoPrint.

## لماذا تدير الطابعة عن بعد Remote Management؟

الطباعة بطريقة الترسيب المنصهر FDM عملية بطيئة بطبيعتها، فعلبة جهاز صغيرة تأخذ ساعتين أو ثلاث، وقطعة كبيرة قد تأخذ يوماً كاملاً، وخلال هذا الوقت تحدث أشياء كثيرة: تنفصل القطعة عن السرير Bed، أو ينقطع الخيط Filament، أو تنسد الفوهة Nozzle، أو تتغير حرارة الغرفة. وعندما تكون الطابعة مربوطة ببطاقة SD وشاشة صغيرة فقط، فإنك لا تعرف بأي من هذا إلا عندما تقف أمامها. أما عندما يديرها حاسوب متصل بالشبكة، فإنك تحصل على عدة أشياء دفعة واحدة:

- **رفع الملف مباشرة من برنامج التقطيع:** PrusaSlicer وOrcaSlicer وCura تستطيع إرسال الملف إلى OctoPrint أو Moonraker بزر واحد، فلا توجد بطاقة SD ولا مشي إلى الغرفة الأخرى.
- **المراقبة Monitoring:** الحرارة الحالية والمطلوبة، ونسبة التقدم، والوقت المتبقي، وصورة الكاميرا Webcam، وكل هذا في المتصفح أو على الجوال.
- **التحكم أثناء الطباعة:** الإيقاف المؤقت Pause، والاستئناف Resume، والإلغاء Cancel، وتغيير السرعة والحرارة دون أن تلمس الطابعة.
- **السجل History:** كل طباعة بوقتها الحقيقي وكمية الخيط التي استهلكتها، وهذا مهم عندما تحسب تكلفة قطعة لعميل.
- **الإضافات والتكامل Integration:** تنبيه على الجوال عند الانتهاء، أو ربط الطابعة بـ Home Assistant، أو قراءة حالتها من برنامجك عبر واجهة برمجة API.

وفي المقابل هناك ما تخاطر به، وأوله أن الطابعة جهاز فيه سخان يصل إلى 250 درجة وأكثر، وأن «عن بعد» تعني في الغالب أنك لست في الغرفة. لذلك لا تعتبر الإدارة عن بعد بديلاً عن الحماية الحرارية في البرنامج الثابت، ولا عن جهاز كشف الدخان، ولا عن عدم ترك الطابعة تعمل في بيت فارغ في أول أسابيع استخدامها. وسوف نرى في التجربة كيف يوقف Klipper الطابعة كلها عندما لا يسخن السخان بالمعدل المتوقع، وهذه الحماية بالذات هي التي تجعل الإدارة عن بعد مقبولة أصلاً.

## البرنامج الثابت Firmware داخل الطابعة: Marlin وKlipper

كما ذكرنا في [مقارنة Raspberry Pi مع المتحكم الدقيق](https://arabroot.io/articles/%D9%85%D9%82%D8%A7%D8%B1%D9%86%D8%A9-raspberry-pi-%D9%85%D8%B9-%D8%A7%D9%84%D9%85%D8%AA%D8%AD%D9%83%D9%85-%D8%A7%D9%84%D8%AF%D9%82%D9%8A%D9%82-microcontroller/)، فإن المتحكم الدقيق Microcontroller شريحة صغيرة رخيصة تجيد شيئاً واحداً: أن تفعل الشيء نفسه في الوقت نفسه بالضبط في كل مرة، ولكن ذاكرتها وقدرتها على الحساب محدودة. وفي قلب كل طابعة FDM لوحة تحكم Mainboard عليها متحكم من هذا النوع، يحرك أربعة محركات خطوية Stepper Motors على الأقل (المحاور X وY وZ والطارد Extruder)، ويقرأ حساسين للحرارة Thermistors، ويشغل سخانين ومروحة، ويقرأ مفاتيح النهاية Endstops.

![طابعة ثلاثية الأبعاد بإطار أسود من الألومنيوم وقطع برتقالية مطبوعة، رأس الطباعة في المنتصف معلق على قضيب أفقي بأحزمة مسننة، وسرير أسود في الأسفل، ومحركات في الزوايا السفلية](https://arabroot.io/content/images/2026/11/klipper-octoprint-01-voron-photo.webp)

طابعة Voron أثناء التجميع: رأس الطباعة على قضيب أفقي تحركه أحزمة من محركين في الخلف، ومشروع Voron يستخدم Klipper برنامجاً ثابتاً لطابعاته. الصورة: disinterpreter، رخصة CC BY-SA 2.0، [ويكيميديا كومنز](https://commons.wikimedia.org/wiki/File:Voron%5F3D%5Fprinter.jpg?ref=arabroot.io)

والبرنامج الثابت الأشهر لهذه اللوحات هو Marlin، وطريقته أن كل شيء يحدث داخل المتحكم: يصله سطر G-code مثل `G1 X114.57 Y102.003 E4.5076` من بطاقة SD أو من كابل USB، فيفسره، ويحسب مسار الحركة وتسارعها في مخطط الحركة Planner، ثم يحول هذا إلى نبضات خطوة Step Pulses لكل محرك في أوقات دقيقة. ونجح هذا الأسلوب لسنوات طويلة، ولكن له حدود واضحة: المتحكم الذي يعمل بتردد 16 ميجاهرتز في اللوحات القديمة لا يستطيع حساب منحنيات تسارع معقدة لعدة محركات بسرعات عالية، وأي تعديل في الإعدادات يعني أن تعدل ملفات المصدر وتعيد بناء البرنامج الثابت Compile ثم تحرقه Flash على اللوحة.

وجاء [Klipper](https://www.klipper3d.org/Overview.html?ref=arabroot.io) بفكرة مختلفة: إذا كان بجانب الطابعة حاسوب Linux قوي مثل Raspberry Pi، فلماذا يحسب المتحكم الصغير كل شيء؟ فقسم العمل إلى قسمين: برنامج على الحاسوب اسمه klippy مكتوب بلغة Python مع أجزاء بلغة C، يقرأ ملف الإعدادات `printer.cfg` ويفسر G-code ويحسب الحركة كاملة، ثم يرسل إلى المتحكم أوامر جاهزة من نوع «حرك هذا المحرك بهذه الخطوات بدءاً من الساعة رقم كذا وبفاصل كذا». والمتحكم لا يعرف شيئاً عن G-code إطلاقاً، وكل ما يفعله أن ينفذ هذه الأوامر في وقتها بالضبط، ويرسل قراءات الحرارة والمفاتيح إلى الحاسوب. ولهذا التقسيم نتائج عملية تراها مباشرة:

- **الإعدادات ملف نصي:** تغير قيمة في `printer.cfg` ثم تكتب `RESTART`، دون بناء برنامج ثابت جديد.
- **حساب أدق وأسرع:** لأن الحاسوب يحسب، فيمكن تطبيق خوارزميات مثل تشكيل الإدخال Input Shaper الذي يقلل اهتزاز الإطار، وضغط الخيط Pressure Advance.
- **الماكرو Macros:** أوامر G-code تكتبها بنفسك بلغة القوالب Jinja، مثل `START_PRINT` و`PAUSE`، وسوف نكتبها في التجربة.
- **عدة متحكمات في طابعة واحدة:** لوحة رئيسية، ولوحة على رأس الطباعة، والحاسوب نفسه كمتحكم ثالث لأرجله GPIO، وكلها متزامنة بساعة واحدة.

ولكن هذا التقسيم له ثمن أيضاً، فالطابعة لم تعد تعمل وحدها، وإذا تعطل الحاسوب أو انقطع كابل USB أثناء الطباعة توقفت فوراً، والحاسوب نفسه يجب أن يكون سريع الاستجابة بما يكفي لأن الأوامر مؤقتة بالساعة. وسوف نرى هذا الثمن بالأرقام في التجربة، عندما رفض المتحكم أن يتأخر أكثر من 1 ملي ثانية.

## الطبقات الأربع في Klipper Architecture

عندما تقرأ عن Klipper ستجد أسماء كثيرة، ولكن الصورة الكاملة أربع طبقات، كل واحدة برنامج مستقل يتكلم مع التي بعدها:

![رسم من أربعة صناديق متصلة بأسهم: المتصفح مع Mainsail أو Fluidd، ثم Moonraker على المنفذ 7125، ثم klippy على الحاسوب يحسب الحركة، ثم المتحكم MCU ينفذ الخطوات، وتحته المشغلات من محركات وسخانات، وفي الأسفل صندوق يقارن بـ Marlin حيث كل شيء داخل اللوحة](https://arabroot.io/content/images/2026/11/klipper-octoprint-02-architecture.webp)

من المتصفح إلى المحرك: الواجهة لا تعرف شيئاً عن المحركات، والمتحكم لا يعرف شيئاً عن G-code

1. **المتحكم MCU:** اللوحة الرئيسية للطابعة وعليها برنامج Klipper الثابت، تبنيه مرة واحدة بالأمر `make menuconfig` ثم `make`، ولا تعود إليه إلا عند التحديث.
2. **المضيف klippy Host:** برنامج Python على الحاسوب، يقرأ `printer.cfg`، ويفتح منفذ المتحكم، ويحسب الحركة، ويكتب كل ما يحدث في `klippy.log`. ويفتح مقبس يونكس Unix Socket اسمه `klippy.sock` لمن يريد أن يكلمه.
3. **Moonraker:** خادم واجهة برمجة API Server مكتوب بـ Python أيضاً، يتصل بـ klippy عبر ذلك المقبس، ويقدم للعالم واجهة HTTP وWebSocket على المنفذ 7125: رفع الملفات، وبدء الطباعة، وقراءة الحالة، وحفظ السجل في قاعدة بيانات صغيرة، وإدارة التحديثات.
4. **الواجهة Frontend:** Mainsail أو Fluidd، وكل منهما ملفات HTML وJavaScript ثابتة يقدمها nginx، وتعمل في متصفحك وتتكلم مع Moonraker. ولا توجد في الواجهة أي منطق للطابعة، ولهذا تستطيع أن تبدل Mainsail بـ Fluidd في دقيقة، أو تستخدم الاثنين معاً على الطابعة نفسها.

وكل هذه البرامج تشترك في مجلد واحد اسمه `printer_data` في بيت المستخدم، فيه `config` للإعدادات، و`gcodes` للملفات المرفوعة، و`logs` للسجلات، و`comms` للمقابس، و`database` لقاعدة بيانات Moonraker. وعندما تعرف هذا المجلد تعرف أين تبحث عند أي مشكلة، وماذا تنسخ في النسخة الاحتياطية Backup.

## OctoPrint والإرسال سطراً سطراً Serial Streaming

OctoPrint أقدم من Klipper، وفكرته أبسط: لا يغير شيئاً في الطابعة، وإنما يأخذ مكان بطاقة SD. فهو خادم ويب Web Server بلغة Python يعمل على الحاسوب، ويتصل بالطابعة عبر كابل USB كمنفذ تسلسلي Serial Port، ويقرأ ملف G-code من قرصه ويرسله إلى Marlin سطراً سطراً، وينتظر بعد كل سطر كلمة `ok` من الطابعة قبل أن يرسل التالي. ولأن الكابل قد يفسد بايتاً هنا أو هناك، فإن كل سطر يرسل برقم سطر ومجموع تحقق Checksum في آخره، مثل `N100 G1 X114.57 Y102.003 E4.5076*101`، فإذا وصل السطر تالفاً طلبت الطابعة إعادته بالرسالة `Resend:100`. وسوف نرى هذا الحوار حرفياً في التجربة، لأن الطابعة الافتراضية في OctoPrint تفتعل هذه الأخطاء عمداً.

![مقارنة بين طريقتين: OctoPrint مع Marlin يرسل سطراً ثم ينتظر ok ويحمل كل سطر رقماً ومجموع تحقق، وMoonraker مع Klipper حيث يضع الملف في مجلد gcodes ويقرأه klippy بنفسه كبطاقة SD افتراضية ويرسل خطوات مؤقتة للمتحكم](https://arabroot.io/content/images/2026/11/klipper-octoprint-14-streaming.webp)

من يقرأ الملف؟ في OctoPrint يقرأه OctoPrint ويرسله سطراً سطراً، وفي Klipper يقرأه klippy نفسه من البطاقة الافتراضية

وقوة OctoPrint في مكتبة الإضافات Plugins الكبيرة حوله، وفي أنه يعمل مع أي طابعة تقريباً دون أن تلمس برنامجها الثابت، ولهذا كان لسنوات الخيار الأول لمن يشتري طابعة جاهزة ويريد إدارتها من المتصفح، وتوزيعة [OctoPi](https://octoprint.org/download/?ref=arabroot.io) تجهز لك Raspberry Pi به في دقائق. وضعفه في الطريقة نفسها: كل حركة قصيرة سطر، وكل سطر ذهاب وعودة على الكابل، وفي المنحنيات المكونة من مئات الأسطر القصيرة قد لا يلحق الإرسال بالطابعة فتتوقف لحظة Stutter وتترك أثراً على السطح. ويستطيع OctoPrint أيضاً أن يعمل واجهة لـ Klipper، إذ يفتح klippy منفذاً تسلسلياً وهمياً اسمه `klippy.serial` يتصل به OctoPrint كما يتصل بطابعة، وهذا مشروح في [صفحة OctoPrint في وثائق Klipper](https://www.klipper3d.org/OctoPrint.html?ref=arabroot.io)، ولكن أغلب مستخدمي Klipper اليوم يستخدمون Moonraker مع Mainsail أو Fluidd، لأنهما بنيا لـ Klipper من البداية.

## ماذا تحتاج بجانب الطابعة؟ Hardware

في الحالتين تحتاج حاسوباً صغيراً يعمل طوال الوقت بجانب الطابعة، والخيار الشائع Raspberry Pi، وقد شرحنا تجهيزه كسيرفر في [تجهيز Raspberry Pi كسيرفر](https://arabroot.io/articles/%D8%AA%D8%AC%D9%87%D9%8A%D8%B2-raspberry-pi-%D9%83%D8%B3%D9%8A%D8%B1%D9%81%D8%B1-ssd-%D9%88%D8%A7%D9%84%D8%AA%D8%A8%D8%B1%D9%8A%D8%AF-%D9%88%D8%A7%D9%84%D8%B7%D8%A7%D9%82%D8%A9/). وأي حاسوب Linux يكفي في الحقيقة: لابتوب قديم، أو حاسوب صغير Mini PC، أو حتى بعض الطابعات الحديثة التي تأتي بحاسوب داخلي وKlipper مثبت.

![لوحة Raspberry Pi 4 خضراء من الجانب، تظهر فيها منافذ USB الزرقاء والسوداء ومنفذ الشبكة الفضي وصف أرجل GPIO على الحافة العلوية](https://arabroot.io/content/images/2026/11/klipper-octoprint-03-pi-photo.webp)

Raspberry Pi 4 Model B: منافذ USB لكابل الطابعة والكاميرا، ومنفذ الشبكة، وأرجل GPIO التي يستطيع Klipper استخدامها كمتحكم إضافي. الصورة: Laserlicht، رخصة CC BY-SA 4.0، [ويكيميديا كومنز](https://commons.wikimedia.org/wiki/File:Raspberry%5FPi%5F4%5FModel%5FB%5F-%5FSide.jpg?ref=arabroot.io)

| البند    | ما يكفي                                            | لماذا                                                                        |
| -------- | -------------------------------------------------- | ---------------------------------------------------------------------------- |
| الحاسوب  | Raspberry Pi 3B+ أو أحدث، أو أي Linux بمعالج 64 بت | klippy يحسب الحركة في الوقت الحقيقي، والكاميرا والواجهة تحتاجان ذاكرة إضافية |
| التخزين  | بطاقة microSD جيدة، أو SSD عبر USB أفضل            | السجلات وقاعدة البيانات تكتب باستمرار، والبطاقات الرخيصة تتعطل               |
| الطاقة   | مزود الطاقة الرسمي للوحة                           | انخفاض الجهد يعيد تشغيل الحاسوب، وفي Klipper هذا يعني توقف الطباعة           |
| الكابل   | USB قصير جيد، أو UART أو CAN حسب اللوحة            | كل خطوة تمر عليه، والكابل الرديء يظهر كرسائل إعادة إرسال Retransmit في السجل |
| الكاميرا | كاميرا USB أو كاميرا Pi                            | هي التي تجعل «عن بعد» مفيدة فعلاً                                            |

وطريقة التثبيت المعتادة على Pi حقيقي هي سكربت [KIAUH](https://github.com/dw-0/kiauh?ref=arabroot.io) الذي يثبت Klipper وMoonraker والواجهة ويجهز خدمات systemd لها، أو توزيعة [MainsailOS](https://docs-os.mainsail.xyz/?ref=arabroot.io) الجاهزة، وكلاهما مذكوران في [صفحة التثبيت في وثائق Klipper](https://www.klipper3d.org/Installation.html?ref=arabroot.io). وفي هذا المقال لن نستخدم أياً منهما، وإنما سوف نبني كل جزء بيدنا داخل Docker، حتى نرى ماذا يفعل كل جزء، وأين يتعطل.

## التجربة العملية Lab: طابعة وهمية في Docker

ليس لدينا طابعة في هذه التجربة، ولكننا نريد أن يعمل Klipper حقيقياً: يقرأ إعدادات حقيقية، ويحسب حركة حقيقية لملف G-code حقيقي، ويرسل خطوات إلى متحكم حقيقي يعدها، وتراه الواجهة كما تراه في طابعة. والخطة حاويتان Containers: الأولى فيها Klipper وMoonraker وMainsail، والثانية فيها OctoPrint بطابعته الافتراضية، والملف نفسه يرفع إلى الاثنين. وكل ملفات التجربة في مجلد `lab` المرفق مع المقال.

![خريطة المختبر: حاوية elp-klipper فيها nginx مع Mainsail على المنفذ 9621، وMoonraker على 7125، وklippy، وklipper_mcu مع fakegpio.so، وحاوية elp-octoprint فيها OctoPrint 2.0.1 على المنفذ 9631 مع الطابعة الافتراضية، وجهازك يقطع الملف بـ PrusaSlicer ويرفعه إلى الاثنين](https://arabroot.io/content/images/2026/11/klipper-octoprint-04-lab-map.webp)

خريطة المختبر: حاويتان وملف G-code واحد

وقبل أن ندخل في الخطوات، هذه المشكلات الست التي واجهناها بالترتيب، وكل خطوة بعدها تشرح واحدة منها:

![جدول من ست مشكلات: فشل بناء cffi وgreenlet على Python 3.13، وبطء simulavr مع Timeout on connect، ورفض sched_setscheduler داخل Docker، وتوقف المتحكم لعدم وجود ADC، وStepper too far in past بسبب تأخير الآلة الافتراضية، وNo trigger on x لعدم وجود مفاتيح نهاية، ومع كل مشكلة ما فعلناه](https://arabroot.io/content/images/2026/11/klipper-octoprint-05-problems.webp)

ست مشكلات حقيقية قبل أول طبقة، بالرسالة التي ظهرت في السجل وما فعلناه

### الخطوة الأولى: الصورة Image والمشكلة الأولى مع Python 3.13

بدأنا من صورة `debian:trixie-slim`، ونسخنا Klipper عند الوسم v0.13.0 وMoonraker عند v0.11.0، ثم أنشأنا بيئة Python افتراضية Virtual Environment لكل منهما كما تقول وثائق التثبيت، أي `pip install -r scripts/klippy-requirements.txt`. والملف الكامل في `lab/Dockerfile.klipper`، وهذا الجزء المهم منه:

```dockerfile
RUN git clone --depth 1 --branch v0.13.0 https://github.com/Klipper3d/klipper.git \
 && git clone --depth 1 --branch v0.11.0 https://github.com/Arksine/moonraker.git
RUN python3 -m venv klippy-env && klippy-env/bin/pip install --no-cache-dir -r klipper/scripts/klippy-requirements.txt
```

والمخرج سوف يكون كما يلي:

```text
c/_cffi_backend.c:6100:9: error: implicit declaration of function ‘_PyErr_WriteUnraisableMsg’; did you mean ‘PyErr_WriteUnraisable’? [-Wimplicit-function-declaration]
ERROR: Failed building wheel for cffi
ERROR: Failed building wheel for greenlet
Failed to build cffi greenlet
```

في المخرج أعلاه لاحظ التالي:

- ملف [klippy-requirements.txt في الوسم v0.13.0](https://github.com/Klipper3d/klipper/blob/v0.13.0/scripts/klippy-requirements.txt?ref=arabroot.io) يثبت النسخة `cffi==1.14.6` و`greenlet==3.0.3`، ولا توجد لهما حزم جاهزة Wheels لـ Python 3.13، فيحاول pip بناءهما من المصدر.
- Debian 13 يأتي بـ Python 3.13.5، والدالة `_PyErr_WriteUnraisableMsg` لم تعد موجودة في هذا الإصدار، فيفشل البناء في ملف C داخل cffi نفسه، وليس في Klipper.
- والفرع الرئيسي Master في Klipper عالج هذا لاحقاً برفع النسخ لمن يستخدم Python 3.12 وما بعده، ولكن الوسم v0.13.0 صدر في أبريل 2025 قبل هذا التعديل.

والحل أن تثبت نسخاً أحدث من المكتبتين تدعم Python 3.13، ووضعناها في `lab/req-py313.txt` بدل ملف المشروع:

```text
cffi==1.17.1
pyserial==3.4
greenlet==3.1.1
Jinja2==2.11.3
python-can==3.3.4
markupsafe==1.1.1
setuptools==75.6.0
```

وهذا الخطأ تراه أيضاً على Raspberry Pi إذا ثبت Klipper بإصدار قديم على نظام حديث، والقاعدة هنا: إذا فشل pip في بناء مكتبة C فاقرأ أول سطر `error:` في المخرج، لا آخر سطر، لأن الأول يقول لك السبب والأخير يقول لك فقط أن البناء فشل.

### المحاولة الأولى: محاكاة معالج AVR مع simulavr

تشرح [صفحة التصحيح Debugging في وثائق Klipper](https://www.klipper3d.org/Debugging.html?ref=arabroot.io) طريقة لتشغيل Klipper دون طابعة: تبني البرنامج الثابت لمعالج ATmega644p مع خيار المحاكاة، ثم تشغله داخل المحاكي simulavr الذي يحاكي المعالج تعليمة تعليمة، ويفتح منفذاً تسلسلياً وهمياً `/tmp/pseudoserial` يتصل به klippy. وبنينا simulavr من مصدره (واحتاج حزمة `python3-setuptools` لأن Python 3.13 حذف `distutils`)، وبنينا البرنامج الثابت بهذا الملف `lab/simulavr.config`:

```ini
CONFIG_LOW_LEVEL_OPTIONS=y
CONFIG_MACH_AVR=y
CONFIG_MACH_atmega644p=y
CONFIG_CLOCK_FREQ=16000000
CONFIG_SIMULAVR=y
```

وخرج البرنامج الثابت بحجم 41,014 بايت من الكود، ثم شغلنا المحاكي وklippy، فامتلأ `klippy.log` بهذه الأسطر مرة بعد مرة:

```text
mcu 'mcu': Starting serial connect
mcu 'mcu': Timeout on connect
mcu 'mcu': Wait for identify_response
serialhdl.error: mcu 'mcu': Serial connection closed
```

والمحاكي يعمل بنسبة 100% من نواة المعالج، فلماذا لا يرد؟ كتبنا برنامجاً صغيراً يشغل المحاكي ثانية واحدة من وقت المعالج المحاكى ويقيس كم أخذت من الوقت الحقيقي، فكانت النتيجة:

```text
simulated 1.000 s of AVR time in 18.17 s of real time
```

أي أن المعالج المحاكى أبطأ من الحقيقي بثماني عشرة مرة على هذا الجهاز، وklippy ينتظر رد التعريف Identify خلال ثوان معدودة بالوقت الحقيقي، فيستسلم ثم يعيد المحاولة، وهكذا إلى الأبد. وهذا ما تقصده الوثائق عندما تقول إن simulavr يحتاج «معالج حاسوب مكتبي» وجهداً كبيراً من المعالج. والدرس هنا مهم لفهم Klipper: كل أمر يرسله klippy إلى المتحكم مربوط بوقت حقيقي على ساعة المتحكم، وklippy يزامن ساعته مع ساعة المتحكم باستمرار، فإذا كانت ساعة المتحكم تمشي ببطء فلا يوجد شيء يمكن إصلاحه في الإعدادات. فتركنا simulavr وانتقلنا إلى خيار ثان تذكره الوثائق.

### المتحكم كبرنامج Linux Process MCU

يستطيع Klipper أن يبني برنامجه الثابت لا لمتحكم، وإنما كبرنامج Linux عادي اسمه `klipper_mcu`، وهذا مشروح في [صفحة استخدام Raspberry Pi كمتحكم](https://www.klipper3d.org/RPi%5Fmicrocontroller.html?ref=arabroot.io)، والغرض الأصلي منه أن تستخدم أرجل GPIO في الـ Pi نفسه كمتحكم ثان بجانب لوحة الطابعة، لمروحة أو حساس أو زر. وهذا البرنامج يعمل بسرعة الحاسوب الحقيقية، ويتكلم مع klippy عبر منفذ وهمي `/tmp/klipper_host_mcu` بالبروتوكول نفسه. وفي `make menuconfig` تختار «Linux process»، وفي التجربة نسخنا ملف الإعدادات الجاهز من مجلد اختبارات Klipper، والسكربت `lab/setup.sh` يفعل ذلك:

```bash
cd ~/klipper
cp test/configs/linuxprocess.config .config      # CONFIG_MACH_LINUX=y
make olddefconfig
make
```

وعلى Raspberry Pi حقيقي تشغله خدمة systemd اسمها `klipper-mcu.service` بهذا الأمر من ملفها في المستودع:

```ini
ExecStart=/usr/local/bin/klipper_mcu -r -I ${KLIPPER_HOST_MCU_SERIAL}
```

والخيار `-r` يطلب جدولة الوقت الحقيقي Real-time Scheduling من نوع `SCHED_FIFO`، أي أن يتقدم هذا البرنامج على كل البرامج الأخرى في المعالج. فشغلناه بالخيار نفسه داخل الحاوية، فخرج فوراً بهذه الرسالة:

```text
Got error -1 in sched_setscheduler: (1)Operation not permitted
```

وجربنا إضافة الصلاحية `--cap-add SYS_NICE` ورفع الحد `--ulimit rtprio=99`، وجربنا التشغيل بالمستخدم root، والنتيجة نفسها، ثم جربنا الخيار `--cpu-rt-runtime` فرفض Docker إنشاء الحاوية أصلاً:

```text
failed to write "400000": write /sys/fs/cgroup/cpu/docker/96391af98d8c.../cpu.rt_runtime_us: invalid argument
```

والسبب أن Docker Desktop يعطي مجموعة التحكم Cgroup الخاصة بالحاويات حصة صفر من وقت المعالج للبرامج الفورية، ولا تستطيع حاوية أن تأخذ أكثر من مجموعة أبيها. وهذا شيء لا تحتاجه على Pi حقيقي لأن الخدمة تعمل بالمستخدم root مباشرة على النظام، أما هنا فشغلنا `klipper_mcu` دون `-r` وبأعلى أولوية عادية `nice -n -20`، والسكربت `lab/start-mcu.sh` يفعل ذلك. وسوف نرى بعد قليل أن هذا القرار له ثمن.

### لا توجد أرجل ولا محول تماثلي: مكتبة fakegpio

بعد أن عمل `klipper_mcu`، شغلنا klippy بملف إعدادات فيه محاور ومحركات وسخانات، فاتصل بالمتحكم هذه المرة وعرف نفسه بنجاح، ثم توقف كل شيء:

```text
Loaded MCU 'mcu' 127 commands (v0.13.0-0-g61c0c8d / gcc: (Debian 14.2.0-19) 14.2.0 binutils: (GNU Binutils for Debian) 2.44)
MCU 'mcu' config: ADC_MAX=4095 CLOCK_FREQ=50000000 MCU=linux PCA9685_MAX=4096 PWM_MAX=32768 STATS_SUMSQ_BASE=256 STEPPER_STEP_BOTH_EDGE=1
Sending MCU 'mcu' printer configuration...
MCU 'mcu' shutdown: Unable to open adc device
Once the underlying issue is corrected, use the
"FIRMWARE_RESTART" command to reset the firmware, reload the
config, and restart the host software.
Printer is shutdown
```

في المخرج أعلاه لاحظ التالي:

- السطر الثاني هو ما يعرفه klippy عن المتحكم: ساعته 50 ميجاهرتز، ومحوله التماثلي الرقمي ADC بدقة 12 بت أي أكبر قيمة 4095، وهو متحكم من نوع `linux`.
- klippy يرسل الإعدادات Configuration إلى المتحكم مرة واحدة عند البداية: هذا المحرك على الرجل كذا، وهذا الحساس على القناة كذا. والمتحكم يجهز كل رجل، وأول ما فشل كان قناة الحساس.
- وفي سجل `klipper_mcu` نفسه السبب الدقيق: `Got error -1 in analog open: (2)No such file or directory`، لأن البرنامج يقرأ الحرارة من الملف `/sys/bus/iio/devices/iio:device0/in_voltage0_raw` ولا يوجد ADC في الحاوية، ولو لم يتوقف هنا لتوقف عند `/dev/gpiochip0` لأن نواة WSL2 مبنية دون دعم GPIO أصلاً.
- عبارة «Printer is shutdown» هي حالة التوقف الطارئ في Klipper: لا حركة ولا تسخين حتى تصلح السبب وتعيد التشغيل بـ `FIRMWARE_RESTART`.

والحل الذي اخترناه أن نتظاهر بوجود الشريحة، فكتبنا مكتبة صغيرة بلغة C اسمها `fakegpio.so` تحمل قبل البرنامج بالمتغير `LD_PRELOAD`، وتعترض ثلاث دوال من مكتبة النظام: `open` و`ioctl` و`pread`. فعندما يفتح `klipper_mcu` الملف `/dev/gpiochip0` تعطيه المكتبة واصفاً Descriptor يشير إلى `/dev/null`، وعندما يكتب قيمة على رجل تعدها، وعندما يقرأ الحرارة تحسبها من نموذج حراري بسيط: كلما كان السخان يعمل نسبة أكبر من الوقت ارتفعت الحرارة، وكلما ارتفعت فقدت أكثر إلى الغرفة. ثم تحول الحرارة إلى القيمة التي يعطيها حساس NTC بمقاومة 100 كيلو أوم مع مقاومة رفع Pull-up بقيمة 4.7 كيلو أوم، وهي الدائرة نفسها التي شرحناها في [مقال GPIO وPWM وADC](https://arabroot.io/articles/%D8%A7%D9%84%D8%A7%D8%B1%D8%AC%D9%84-%D8%A7%D9%84%D8%B1%D9%82%D9%85%D9%8A%D8%A9-%D9%88%D8%A7%D9%84%D8%AA%D9%85%D8%A7%D8%AB%D9%84%D9%8A%D8%A9-%D9%81%D9%87%D9%85-gpio-%D8%AB%D9%85-pwm-%D9%85%D8%B9-%D9%85%D8%AD%D9%88%D9%84-adc/). وهذا الجزء الذي يقرأ الحرارة من المكتبة:

```c
// NTC 100k, beta 4092 at 25 C, 4.7k pull-up, 12-bit ADC (Klipper's Linux MCU assumes ADC_MAX 4095)
static int adc_from_temp(double t) {
    double r = 100000.0 * exp(4092.0 * (1.0 / (t + 273.15) - 1.0 / 298.15));
    return (int)(4095.0 * r / (r + 4700.0));
}
```

وفي الملف الكامل `lab/fakegpio.c` بقية التفاصيل، وأهم ما فيه أن Klipper نفسه لم يتغير: الكود الذي يحسب الحركة ويرسل الخطوات ويقرأ الحرارة ويشغل حلقة التحكم PID هو كود Klipper كما هو، والمكتبة تجلس فقط في المكان الذي كانت ستجلس فيه الأسلاك. وبعد إعادة التشغيل مع المكتبة كان السجل كما يلي:

```text
Configured MCU 'mcu' (789 moves)
Starting heater checks for heater_bed
Starting heater checks for extruder
Stats 73787.2: gcodein=0  mcu: mcu_awake=0.000 ... heater_bed: target=0 temp=25.0 pwm=0.000 ... extruder: target=0 temp=25.0 pwm=0.000
```

والرقم 789 هو عدد الحركات التي حجزها المتحكم في ذاكرته لطابور الخطوات، والحرارة 25.0 درجة هي قراءة النموذج للغرفة، وسطر `Stats` يكتبه klippy كل ثانية، وسوف نعود إليه لأنه أهم سطر في السجل عند تحليل أي مشكلة.

⚠️

مكتبة fakegpio للتجربة فقط، ولا مكان لها على طابعة حقيقية، فهي تعيد للحساس حرارة محسوبة لا مقاسة، ولو حملت على جهاز متصل بسخان حقيقي لعطلت كل حماية حرارية في Klipper.

### مشكلة حقيقية: Stepper too far in past

بعد أن أصبحت الطابعة الوهمية «جاهزة»، أرسلنا أول أمر حركة عبر Moonraker، وهو تحريك المحور X إلى نقطة الصفر `G28 X`، فتحرك المحرك أكثر من تسعة آلاف خطوة ثم توقفت الطابعة:

```text
MCU 'mcu' shutdown: Stepper too far in past
This generally occurs when the micro-controller has been
requested to step at a rate higher than it is capable of
obtaining.
Dumping stepper 'stepper_x' (mcu) 5 queue_step:
queue_step 0: t=1322600111 p=-8962 i=12500 c=-200 a=0
```

والرسالة تقول إن المتحكم طلب منه أن يخطو أسرع مما يستطيع، ولكن 4,000 خطوة في الثانية (السرعة 50 مم في الثانية مع 80 خطوة لكل مليمتر) لا شيء بالنسبة لمعالج حاسوب. فقرأنا الكود في `src/stepper.c`، فوجدنا أن الشرط الحقيقي هو أن المؤقت Timer استيقظ متأخراً عن موعد الخطوة بأكثر من 1 ملي ثانية. والسؤال إذن: كم يتأخر برنامج عادي في الاستيقاظ داخل هذه الحاوية؟ فكتبنا برنامجاً صغيراً `lab/lat.c` ينام 1 ملي ثانية بالضبط بالدالة `clock_nanosleep` ثم يقيس كم تأخر، ويكرر ذلك آلاف المرات:

```text
wakeups=5000 avg_late=0.174 ms worst=17.064 ms over_1ms=79 over_5ms=23
wakeups=5000 avg_late=0.233 ms worst=15.877 ms over_1ms=151 over_5ms=51
wakeups=20000 avg_late=0.206 ms worst=32.888 ms over_1ms=327 over_5ms=123
```

![رسم أعمدة لثلاث تجارب: 5,000 استيقاظ بأسوأ تأخير 17.064 ملي ثانية، و5,000 مع nice -20 بأسوأ 15.877، و20,000 بأسوأ 32.888، والمتوسط حوالي 0.2 ملي ثانية، وخط أحمر عند 1 ملي ثانية هو حد Klipper](https://arabroot.io/content/images/2026/11/klipper-octoprint-07-latency.webp)

المتوسط ممتاز، ولكن Klipper لا يهمه المتوسط: يكفي استيقاظ واحد متأخر أكثر من 1 ms ليتوقف كل شيء

والمتوسط 0.2 ملي ثانية ممتاز، ولكن في عشرين ألف استيقاظ تأخر البرنامج أكثر من 1 ملي ثانية 327 مرة، وأسوأ مرة 33 ملي ثانية، وأولوية `nice -20` لم تحسن شيئاً لأن التأخير يأتي من الآلة الافتراضية Virtual Machine التي يعمل فيها Docker Desktop نفسه، عندما يعطي نظام Windows المعالج لبرامج أخرى. وهذا بالضبط سبب وجود الخيار `-r` في الخدمة، وسبب نصيحة الوثائق بألا تشغل على حاسوب الطابعة برامج ثقيلة أخرى، وهو أيضاً الفرق بين نظام تشغيل عادي ونظام تشغيل فوري RTOS الذي شرحناه في [مقال أنظمة التشغيل الفورية](https://arabroot.io/articles/%D8%A7%D9%86%D8%B8%D9%85%D8%A9-%D8%A7%D9%84%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D8%A7%D9%84%D9%81%D9%88%D8%B1%D9%8A%D8%A9-rtos-%D9%85%D8%B9-freertos-%D8%AB%D9%85-zephyr/): العبرة بأسوأ حالة، لا بالمتوسط.

ولأن تجربتنا محاكاة لا تحرك محركاً حقيقياً، غيرنا رقماً واحداً في نسخة المختبر: الحد في `src/stepper.c` من 1 ملي ثانية إلى 100 ملي ثانية، والسكربت `lab/setup.sh` يفعل ذلك بسطر واحد قبل البناء:

```bash
sed -i 's/timer_from_us(1000))/timer_from_us(100000))/' src/stepper.c
```

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

💡

وقعنا هنا أيضاً في خطأ من صنعنا يستحق الذكر: النسخة الأولى من fakegpio كانت تكتب ملف إحصائيات في كل قراءة حرارة، وقراءة الحرارة في `klipper_mcu` تحدث داخل مؤقت، فكانت عملية الكتابة على القرص توقف المؤقتات حتى ظهر خطأ آخر هو `Rescheduled timer in the past`. وعندما جعلنا الكتابة كل خمس ثوان فقط اختفى. والقاعدة نفسها في أي برنامج مدمج: لا تقم بعمليات إدخال وإخراج بطيئة داخل المؤقت أو المقاطعة Interrupt.

### ملف الإعدادات printer.cfg

بنينا ملف الإعدادات على المثال `config/generic-simulavr.cfg` الموجود في مستودع Klipper، وغيرنا الأرجل إلى أرجل الشريحة الوهمية، والفوهة إلى 0.4 مم والخيط إلى 1.75 مم. وهذا أول جزء منه، والملف الكامل في `lab/printer.cfg`:

```ini
[mcu]
serial: /tmp/klipper_host_mcu

[printer]
kinematics: cartesian
max_velocity: 300
max_accel: 3000
max_z_velocity: 15
max_z_accel: 100

[stepper_x]
step_pin: gpiochip0/gpio2
dir_pin: gpiochip0/gpio3
enable_pin: !gpiochip0/gpio10
microsteps: 16
rotation_distance: 40
endstop_pin: gpiochip0/gpio11
position_min: -0.25
position_endstop: 0
position_max: 200
homing_speed: 50
```

في الإعداد أعلاه لاحظ التالي:

- `kinematics: cartesian` تعني طابعة ديكارتية يتحرك فيها كل محور بمحرك مستقل، وفي طابعة CoreXY مثل Voron تكتب `corexy` وklippy يحسب كيف يتحرك المحركان معاً لكل حركة.
- `rotation_distance: 40` هي المسافة التي يقطعها المحور في دورة كاملة للمحرك، وهي 40 مم لحزام GT2 على بكرة بعشرين سناً، ومع 200 خطوة كاملة في الدورة و16 خطوة جزئية Microsteps لكل خطوة تصبح 80 خطوة لكل مليمتر.
- علامة التعجب في `!gpiochip0/gpio10` تعني أن الرجل معكوسة Inverted، أي أن المحركات تعمل عندما تكون الرجل منخفضة، وهذا شائع في مشغلات المحركات Stepper Drivers.
- `position_max: 200` هي حدود الحركة الآمنة، وklippy يرفض أي أمر يخرج عنها برسالة `Move out of range` قبل أن يصل إلى المحرك.

وفي آخر الملف الأقسام التي تحتاجها Mainsail وMoonraker من Klipper، وأهمها البطاقة الافتراضية:

```ini
[virtual_sdcard]
path: ~/printer_data/gcodes
on_error_gcode: CANCEL_PRINT

[pause_resume]
[display_status]
[exclude_object]
```

و[القسم virtual\_sdcard](https://www.klipper3d.org/Config%5FReference.html?ref=arabroot.io#virtual%5Fsdcard) هو الذي يجعل klippy يقرأ ملفات G-code من القرص بنفسه بدل أن يرسلها أحد إليه سطراً سطراً، و`pause_resume` يضيف أوامر الإيقاف والاستئناف، و`display_status` يعطي الواجهة نسبة التقدم، و`exclude_object` يسمح بإلغاء قطعة واحدة من عدة قطع على السرير إذا فشلت، بشرط أن يكتب برنامج التقطيع أسماء القطع في الملف.

### مشكلة حقيقية: No trigger on x after full movement

أعدنا تحريك المحور إلى الصفر بعد التعديل، فعمل المحرك هذه المرة حتى النهاية، ثم ظهرت رسالة أخرى:

```text
{"error":{"code":400,"message":"No trigger on x after full movement", ...}}
```

وهذه رسالة ستراها على طابعة حقيقية عندما يكون مفتاح النهاية Endstop غير موصول أو سلكه مقطوعاً: Klipper يحرك المحور مسافة تساوي طول المحور ونصف، أي 300 مم هنا، فإذا لم يضغط المفتاح خلالها توقف وأبلغك، بدل أن يستمر المحرك في الدفع على إطار الطابعة. والشريحة الوهمية تقرأ كل المفاتيح صفراً دائماً، ولهذا أضفنا للمحاكاة فقط قسماً يستبدل أمر `G28` بتعريف الموضع مباشرة، وهو مشروح في [قسم homing\_override في مرجع الإعدادات](https://www.klipper3d.org/Config%5FReference.html?ref=arabroot.io#homing%5Foverride):

```ini
[respond]

# Simulation only: the pretend endstops never trigger, so G28 would fail with
# "No trigger on x after full movement". A real printer does not have this section.
[force_move]
enable_force_move: True     # SET_KINEMATIC_POSITION is only available with this

[homing_override]
gcode:
    SET_KINEMATIC_POSITION X=0 Y=0 Z=0.5
    RESPOND MSG="simulated homing: position set to X0 Y0 Z0.5"
```

وفي أول نسخة نسينا قسم `force_move`، فقبل Klipper الأمر `G28` دون خطأ، ولكن الواجهة أظهرت في الطرفية Console السطر `Unknown command:"SET_KINEMATIC_POSITION"` والمحاور بقيت غير معرفة، وهذا ما تراه في لقطة Mainsail التالية. والدرس هنا أن الماكرو في Klipper لا يتوقف عند أول أمر خاطئ داخله دائماً، فاقرأ الطرفية بعد كل تعديل على الماكرو، ولا تكتف بأن الأمر «انتهى».

![لقطة من واجهة Mainsail الداكنة: لوحة رأس الطباعة بموضع صفر، ولوحة الحرارة تظهر الفوهة عند 215 درجة والسرير عند 59.4، ورسماً للحرارة، وفي الطرفية أسطر No trigger on y after full movement ثم G28 ثم Unknown command SET_KINEMATIC_POSITION ثم رسالة المحاكاة](https://arabroot.io/content/images/2026/11/klipper-octoprint-06-mainsail-homing.webp)

Mainsail v2.19.0 على الطابعة الوهمية: الطرفية تكشف أن SET\_KINEMATIC\_POSITION لم يعمل قبل إضافة قسم force\_move

### Moonraker وMainsail أمام klippy: الواجهة Frontend

ملف إعدادات Moonraker في التجربة قصير، لأن أغلب القيم الافتراضية مناسبة، والملف الكامل في `lab/moonraker.conf`:

```ini
[server]
host: 0.0.0.0
port: 7125
klippy_uds_address: ~/printer_data/comms/klippy.sock

[authorization]
trusted_clients:
    127.0.0.0/8
    172.16.0.0/12
cors_domains:
    *

[machine]
provider: none
validate_service: False
```

في الإعداد أعلاه لاحظ التالي:

- `klippy_uds_address` هو مقبس klippy الذي ذكرناه، وهو الرابط الوحيد بين Moonraker وKlipper.
- `trusted_clients` يحدد الشبكات التي تدخل دون كلمة مرور، وهنا شبكة الحاوية فقط، و[وثائق إعدادات Moonraker](https://moonraker.readthedocs.io/en/latest/configuration/?ref=arabroot.io) تشرح المصادقة بالمستخدمين ومفاتيح API عندما تحتاج أكثر من ذلك.
- `provider: none` لأن الحاوية لا تعمل بـ systemd، وعلى Pi حقيقي يستخدم Moonraker نظام systemd ليعيد تشغيل الخدمات ويطفئ الجهاز من الواجهة.

أما Mainsail فملفات ثابتة نزلناها من صفحة الإصدار v2.19.0، وقدمها nginx على المنفذ 80 داخل الحاوية، مع تمرير مسارات `/websocket` و`/printer` و`/server` و`/machine` و`/access` إلى Moonraker، كما في [وثائق Mainsail](https://docs.mainsail.xyz/?ref=arabroot.io)، والملف في `lab/nginx-mainsail.conf`. ولماذا لا تفتح المتصفح على Moonraker مباشرة؟ لأن الواجهة تفترض أن الملفات والـ API على العنوان نفسه، ولأن nginx هو المكان الطبيعي لاحقاً لإضافة TLS وكلمة مرور، كما شرحنا في [مقال الـ Reverse Proxy](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%88-reverse-proxy-%D9%88%D9%84%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D8%AD%D8%AA%D8%A7%D8%AC%D9%87/).

### ملف G-code لـ Klipper: مشكلة الحرارة المزدوجة

قطعنا قطعة صغيرة لتثبيت الأسلاك بحجم 40 × 12 × 8 مم صممناها في OpenSCAD (الملف `lab/clip.scad`)، بـ PrusaSlicer 2.9.7 من سطر الأوامر، وكتبنا في كود البداية Start G-code سطراً واحداً يستدعي ماكرو `START_PRINT`، كما تنصح [صفحة برامج التقطيع في وثائق Klipper](https://www.klipper3d.org/Slicers.html?ref=arabroot.io). فكان أول الملف هكذا:

```gcode
M190 S60 ; set bed temperature and wait for it to be reached
M104 S215 ; set temperature
;TYPE:Custom
START_PRINT BED_TEMP=60 EXTRUDER_TEMP=215
M109 S215 ; set temperature and wait for it to be reached
G21 ; set units to millimeters
```

ولاحظ أن PrusaSlicer أضاف بنفسه أوامر التسخين قبل الماكرو وبعده، لأنه لم يجد `M190` و`M109` في كود البداية الذي كتبناه، فظن أننا نسيناهما. والنتيجة على طابعة حقيقية أن السرير يسخن والفوهة تبدأ بالتسخين قبل أن يحرك الماكرو المحاور إلى الصفر، ثم ينتظر الماكرو مرة ثانية، وأحياناً تسيل قطرة من الفوهة الساخنة على السرير أثناء الحركة. والحل في PrusaSlicer خيار يوقف هذا السلوك، وهو في سطر الأوامر `--no-autoemit-temperature-commands`، والأمر الكامل في `lab/slice.sh`:

```bash
prusa-slicer-console --export-gcode $COMMON --gcode-flavor klipper --no-autoemit-temperature-commands \
  --start-gcode "START_PRINT BED_TEMP=[first_layer_bed_temperature] EXTRUDER_TEMP=[first_layer_temperature]" \
  --end-gcode "END_PRINT" --output clip.gcode clip.stl
```

فأصبح أول الملف سطر الماكرو وحده، وخرج الملف بحجم 330,919 بايت و39 طبقة، والوقت المقدر Estimated Time حسب PrusaSlicer 14 دقيقة وثانية واحدة، و786.45 مم من الخيط. والقيم بين الأقواس المربعة مثل `[first_layer_bed_temperature]` متغيرات يملؤها PrusaSlicer من إعدادات الخامة، فتصل حرارة كل خامة إلى الماكرو دون أن تكتبها في مكانين. وقد شرحنا برامج التقطيع وإعداداتها بالتفصيل في مقال برامج التقطيع في هذه المرحلة.

### الماكرو Macro: START\_PRINT وPAUSE

الماكرو في Klipper قسم في ملف الإعدادات اسمه `gcode_macro`، وجسمه أوامر G-code عادية مع قوالب Jinja بين الأقواس المعقوفة، كما في [صفحة قوالب الأوامر](https://www.klipper3d.org/Command%5FTemplates.html?ref=arabroot.io). وهذا الماكرو الذي يبدأ الطباعة في التجربة، من `lab/macros.cfg`:

```ini
[gcode_macro START_PRINT]
description: Heat, home and prime before a print
gcode:
    {% set BED_TEMP = params.BED_TEMP|default(60)|float %}
    {% set EXTRUDER_TEMP = params.EXTRUDER_TEMP|default(200)|float %}
    M140 S{BED_TEMP}
    G90
    SET_GCODE_OFFSET Z=0.0
    G28
    G1 Z5 F3000
    M190 S{BED_TEMP}
    M109 S{EXTRUDER_TEMP}
    G1 Z0.3 F300
    RESPOND MSG="START_PRINT done: bed {BED_TEMP}, nozzle {EXTRUDER_TEMP}"
```

في الإعداد أعلاه لاحظ التالي:

- `params.BED_TEMP` هو المعامل الذي أرسله الملف، و`default(60)` قيمة احتياطية إذا استدعيت الماكرو يدوياً دون معاملات.
- الترتيب مقصود: نبدأ تسخين السرير بـ `M140` دون انتظار، ثم نحرك المحاور إلى الصفر أثناء التسخين، ثم ننتظر السرير، ثم الفوهة، فلا تسيل الفوهة أثناء الحركة.
- هذا الماكرو يعيش في الطابعة لا في برنامج التقطيع، فإذا غيرت شيئاً في بداية الطباعة غيرته في مكان واحد لكل الملفات التي قطعتها، القديمة والجديدة.

وأما الإيقاف المؤقت فنعيد تعريف الأمر `PAUSE` الموجود في Klipper، ونحتفظ بالأصلي باسم `BASE_PAUSE` عبر الخاصية `rename_existing`:

```ini
[gcode_macro PAUSE]
description: Pause the print and park the head
rename_existing: BASE_PAUSE
gcode:
    SAVE_GCODE_STATE NAME=PAUSE_state
    BASE_PAUSE
    G91
    G1 E-2 F2100
    G1 Z10 F900
    G90
    G1 X10 Y190 F6000
```

فيحفظ الماكرو حالة G-code كلها (الموضع ونوع الإحداثيات والسرعة)، ثم يوقف قراءة الملف، ثم يسحب الخيط 2 مم حتى لا يسيل، ويرفع الرأس 10 مم ويبعده إلى الزاوية. والماكرو `RESUME` يعكس هذا ويعيد الحالة بـ `RESTORE_GCODE_STATE MOVE=1`، وسوف نرى أرقامه الحقيقية بعد قليل.

### الطباعة: رفع الملف وبدؤها عبر Moonraker

رفعنا الملف إلى Moonraker بنفس الطلب الذي يرسله برنامج التقطيع عندما تضغط زر الإرسال، ثم بدأنا الطباعة، كما في [وثائق واجهة Moonraker](https://moonraker.readthedocs.io/en/latest/external%5Fapi/introduction/?ref=arabroot.io):

```bash
curl -s -F "file=@clip.gcode" -F "root=gcodes" http://127.0.0.1:9621/server/files/upload
curl -s "http://127.0.0.1:9621/server/files/metadata?filename=clip.gcode"
curl -s -X POST "http://127.0.0.1:9621/printer/print/start?filename=clip.gcode"
```

والمخرج سوف يكون كما يلي (اختصرنا من وسط البيانات الوصفية Metadata):

```json
{"action":"create_file","item":{"modified":1795149542.8662431,"size":330919,"permissions":"rw","path":"clip.gcode","root":"gcodes"},"print_started":false,"print_queued":false}
{"result":{"size":330919,"slicer":"PrusaSlicer","slicer_version":"2.9.7","object_height":7.95,"estimated_time":841,
 "nozzle_diameter":0.4,"layer_height":0.2,"first_layer_height":0.35,"first_layer_extr_temp":215.0,"first_layer_bed_temp":60.0,
 "filament_type":"PLA","filament_total":786.45, ... ,"filename":"clip.gcode"}}
{"result":"ok"}
```

فـ Moonraker قرأ تعليقات PrusaSlicer في آخر الملف واستخرج منها الوقت المقدر 841 ثانية، وارتفاع القطعة 7.95 مم، ونوع الخيط وطوله، وهذه هي الأرقام التي تعرضها الواجهة قبل أن تبدأ. ثم بدأ الماكرو بتسخين السرير والفوهة، والنموذج الحراري في fakegpio مع حلقة PID الحقيقية في Klipper أعطيا هذا المنحنى، والأرقام من أسطر `Stats` في `klippy.log`:

![رسم بياني للحرارة مع الزمن: السرير بالأزرق يرتفع من 25 إلى 60 درجة خلال 44 ثانية بعد M190 ثم يتذبذب حول 60، والفوهة بالبرتقالي ترتفع بعد M109 من 25 إلى 214 درجة عند الثانية 175 ثم تستقر عند 215](https://arabroot.io/content/images/2026/11/klipper-octoprint-08-heating.webp)

التسخين كما سجله klippy.log: السرير بتحكم Watermark يتذبذب بين 57.9 و62.1، والفوهة بتحكم PID تستقر بين 214.2 و215.6

ولاحظ الفرق بين المنحنيين، فالسرير يستخدم تحكم Watermark، أي تشغيل كامل حتى يتجاوز الهدف ثم إطفاء كامل، فيتذبذب بين 57.9 و62.1 درجة، وهذا مقبول لسرير ثقيل بطيء. أما الفوهة فتستخدم PID، فتخفض قدرة السخان تدريجياً كلما اقتربت من الهدف، فتراها في السجل تنزل من `pwm=1.000` إلى `0.900` ثم `0.854` ثم `0.761`، وتستقر بين 214.2 و215.6 درجة. وبدأت الطباعة، وهذا ما عرضته Mainsail في الطبقة الثانية:

![لقطة Mainsail أثناء الطباعة: 6% Printing، السرعة 20 مم في الثانية، والتدفق 1.6 مم مكعب في الثانية، والطبقة 2 من 39، والتقدير 11 دقيقة، والرأس عند X 90.55 وY 105.06 وZ 0.55، والطرفية تظهر START_PRINT done ثم File opened clip.gcode](https://arabroot.io/content/images/2026/11/klipper-octoprint-09-mainsail-printing.webp)

الطابعة الوهمية تطبع: الطبقة 2 من 39، والتقدير حسب PrusaSlicer 13 دقيقة، والطرفية تؤكد أن الماكرو انتهى

وفي صفحة عارض G-code Viewer ترسم Mainsail الملف كله ثلاثي الأبعاد في المتصفح، وتستطيع أن تتبع موضع الرأس أثناء الطباعة، وهذا مفيد قبل الطباعة أيضاً لتتأكد أن القطعة في وسط السرير وأن الحافة Skirt حولها:

![عارض G-code في Mainsail: شبكة السرير ثلاثية الأبعاد بمحاورها الملونة، وفي وسطها قطعة التثبيت البرتقالية بثقبيها وتجويفها الدائري، وحولها خط الحافة، وأيقونة الفوهة عند نقطة الأصل](https://arabroot.io/content/images/2026/11/klipper-octoprint-10-gcode-viewer.webp)

عارض G-code في Mainsail يرسم clip.gcode كاملاً في المتصفح

### الإيقاف والاستئناف أثناء الطباعة

عند 16% من الملف أرسلنا طلب الإيقاف عبر Moonraker، واستعلمنا عن موضع الرأس وحالة الطباعة قبله وبعده:

```bash
Q='http://127.0.0.1:9621/printer/objects/query?print_stats=state,print_duration,filament_used&toolhead=position&pause_resume&virtual_sdcard=progress'
curl -s $Q
curl -s -X POST http://127.0.0.1:9621/printer/print/pause
curl -s $Q
curl -s -X POST http://127.0.0.1:9621/printer/print/resume
```

والمخرج سوف يكون كما يلي:

```json
{"result":{"eventtime":74971.262886,"status":{"print_stats":{"state":"printing","print_duration":180.62484229999245,"filament_used":192.73754000000005},"toolhead":{"position":[115.396,102.296,1.35,192.73754000000005]},"pause_resume":{"is_paused":false},"virtual_sdcard":{"progress":0.16196410601990216}}}}
{"result":"ok"}
{"result":{"eventtime":74976.2802606,"status":{"print_stats":{"state":"paused","print_duration":181.14755519999017,"filament_used":192.86795000000006},"toolhead":{"position":[10.0,190.0,11.35,190.86795000000006]},"pause_resume":{"is_paused":true},"virtual_sdcard":{"progress":0.16311846705689306}}}}
```

![خمس خطوات من اليمين إلى اليسار: قبل PAUSE عند X 115.40 وY 102.30 وZ 1.35 والطارد 192.87، ثم حفظ الحالة والإيقاف، ثم سحب الخيط ورفع الرأس، ثم بعد PAUSE عند X 10 وY 190 وZ 11.35 والطارد 190.87، ثم RESUME يعود إلى Z 1.35](https://arabroot.io/content/images/2026/11/klipper-octoprint-11-pause.webp)

ماذا فعل ماكرو PAUSE بالأرقام الحقيقية من Moonraker

والأرقام تحكي ما كتبناه في الماكرو حرفياً: الرأس انتقل من (115.40، 102.30) إلى الزاوية (10، 190)، وارتفع من 1.35 إلى 11.35 مم، والطارد رجع من 192.87 إلى 190.87 مم، أي سحب 2 مم بالضبط. وبعد الاستئناف عاد إلى Z 1.35 وأكمل. وفي `klippy.log` تجد الإيقاف بلغة البطاقة الافتراضية:

```text
Starting SD card print (position 0)
Exiting SD card print (position 53979)
Starting SD card print (position 53979)
Finished SD card print
```

فالإيقاف عند Klipper هو أن يتوقف عن قراءة الملف عند البايت 53,979، والاستئناف أن يكمل من البايت نفسه، وهذا هو سبب أن إغلاق المتصفح أو انقطاع الشبكة لا يؤثر في الطباعة إطلاقاً: الملف على قرص الـ Pi وklippy هو من يقرؤه.

![لقطة Mainsail في حالة 16% Paused: السرعة صفر، والطبقة 39 من 39، والرأس عند X 10 وY 190 وZ 11.35، والفوهة ما زالت عند 214.9 درجة والسرير 59.1](https://arabroot.io/content/images/2026/11/klipper-octoprint-12-mainsail-paused.webp)

أثناء الإيقاف: السخانات تبقى على حرارتها، والرأس في الزاوية، والواجهة تقول «الطبقة 39 من 39» لأنها تحسب الطبقة من ارتفاع الرأس

ولاحظ في اللقطة تفصيلاً صغيراً: Mainsail تقول إن الطابعة في الطبقة 39 من 39، والسبب أن ملفنا لا يرسل رقم الطبقة صراحة، فتحسبه الواجهة من ارتفاع الرأس، والرأس المرفوع 10 مم يخدعها. وإذا أردت رقم الطبقة دقيقاً فأضف في برنامج التقطيع عند تغيير الطبقة الأمر `SET_PRINT_STATS_INFO CURRENT_LAYER=[layer_num]`، وهو من أوامر Klipper المذكورة في [صفحة أوامر G-code](https://www.klipper3d.org/G-Codes.html?ref=arabroot.io).

### النتيجة Result: هل طبع Klipper الملف فعلاً؟

انتهت الطباعة، وهذا ما سجله Moonraker في صفحة السجل History:

![صفحة السجل في Mainsail: إجمالي وقت الطباعة 13 دقيقة و49 ثانية، والخيط المستخدم 0.8 متر، ومهمة واحدة مكتملة باسم clip.gcode، والتقدير 14 دقيقة وثانية، ووقت الطباعة 13 دقيقة و49 ثانية، والخيط 781.45 مم، وبرنامج التقطيع PrusaSlicer 2.9.7](https://arabroot.io/content/images/2026/11/klipper-octoprint-16-history.webp)

السجل: التقدير 14m 1s والحقيقي 13m 49s، دون وقت التسخين والإيقاف

ولكن كيف نعرف أن الحركة حدثت فعلاً، وليست أرقاماً في واجهة؟ الشريحة الوهمية تعد كل حافة صاعدة Rising Edge على كل رجل، وهذه أرقامها في نهاية الطباعة:

```text
gpio2 rising_edges=1393329
gpio4 rising_edges=1040418
gpio6 rising_edges=18740
gpio8 rising_edges=201688
gpio20 rising_edges=10575
gpio22 rising_edges=69746
```

ولنأخذ المحور Z لأنه الأسهل في الحساب: في إعداداتنا 400 خطوة لكل مليمتر (8 مم للدورة مع 3,200 خطوة جزئية)، والمحور تحرك من 0.5 إلى 5 مم في الماكرو (4.5 مم)، ثم نزل إلى 0.3 (4.7 مم)، ثم إلى الطبقة الأولى 0.35، ثم صعد طبقة طبقة إلى 7.95 (7.6 مم)، ثم 10 مم صعوداً و10 نزولاً في الإيقاف، ثم 10 مم في `END_PRINT`. والمجموع 46.85 مم، وضرب 46.85 في 400 يعطي 18,740 خطوة، وهو بالضبط الرقم الذي عدته الشريحة على الرجل `gpio6`. أما الرجل `gpio20` فهي سخان الفوهة وحوافها 10,575 مرة تشغيل، والرجل `gpio22` المروحة التي تعمل بتعديل عرض النبضة PWM برمجياً.

وفي آخر سطر `Stats` رقمان آخران يستحقان النظر:

```text
bytes_write=905519 bytes_read=188197 bytes_retransmit=0 bytes_invalid=0 send_seq=15934 receive_seq=15934
```

فklippy أرسل إلى المتحكم 905,519 بايت ليطبع ملفاً حجمه 330,919 بايت، أي ثلاثة أضعاف تقريباً، لأن ما يمر على الكابل ليس G-code وإنما أوامر خطوات مضغوطة لكل محرك ولكل سخان، وفيها كل ما حسبه الحاسوب. و`bytes_retransmit=0` يعني أن لا شيء أعيد إرساله، وعلى طابعة حقيقية هذا أول رقم تنظر إليه إذا شككت في الكابل أو في التشويش الكهربائي: إذا كان يزيد أثناء الطباعة فالمشكلة في الاتصال لا في Klipper.

### ماذا يحدث إذا ضعف السخان؟ verify\_heater

هذه الحالة تحدث على طابعة حقيقية عندما ينفصل الحساس الحراري من مكانه في كتلة التسخين Heater Block، أو يضعف السخان، أو ينقطع سلكه: البرنامج يشغل السخان بكامل قدرته، والحرارة لا ترتفع. وهو أخطر عطل في الطباعة ثلاثية الأبعاد، لأن الحساس إذا خرج من الكتلة يقرأ حرارة الهواء، فيستمر البرنامج في التسخين والكتلة نفسها تتجاوز حدها بكثير، وهذا ما يسمى الهروب الحراري Thermal Runaway. وجربناه بتغيير رقم واحد في النموذج: قدرة سخان الفوهة من 3.0 إلى 0.08 درجة في الثانية، ثم أرسلنا `M109 S215`:

```text
Heater extruder approaching new target of 215.000
Heater extruder no longer approaching target 215.000
Heater extruder not heating at expected rate
Transition to shutdown state: Heater extruder not heating at expected rate
See the 'verify_heater' section in docs/Config_Reference.md
for the parameters that control this check.
```

وبعد 22 ثانية من الأمر، والحرارة 26.5 درجة فقط والسخان على `pwm=1.000`، أوقف Klipper الطابعة كلها، وهذا ما عرضته Mainsail:

![لقطة Mainsail بلوحة برتقالية عنوانها Klipper reports SHUTDOWN ونصها Heater extruder not heating at expected rate مع إشارة إلى قسم verify_heater، وأزرار RESTART وFIRMWARE RESTART وتنزيل سجلات Klipper وMoonraker](https://arabroot.io/content/images/2026/11/klipper-octoprint-15-heater-shutdown.webp)

الحماية الحرارية تعمل: السخان لم يرفع الحرارة درجتين خلال 20 ثانية، فتوقفت الطابعة

والقاعدة كما في [قسم verify\_heater في مرجع الإعدادات](https://www.klipper3d.org/Config%5FReference.html?ref=arabroot.io#verify%5Fheater): إذا لم ترتفع حرارة الفوهة درجتين خلال 20 ثانية (60 ثانية للسرير) والسخان يعمل بكامل قدرته، أو ابتعدت الحرارة عن الهدف بأكثر من الحد المسموح لفترة، فإن Klipper يتوقف. وهذه الحماية تعمل دون أن تكتب شيئاً في `printer.cfg`، ولا تقم بإطفائها أو رفع قيمها كثيراً لأن طابعتك «تسخن ببطء»، والسبب أنها الشيء الوحيد بين حساس خرج من مكانه وبين حريق. وإذا كان السخان بطيئاً فعلاً فأعد معايرة PID بالأمر `PID_CALIBRATE HEATER=extruder TARGET=215`، أو افحص السخان نفسه.

### الملف نفسه على OctoPrint 2.0.1 والطابعة الافتراضية Virtual Printer

الحاوية الثانية أبسط بكثير: صورة `python:3.13-slim` فيها OctoPrint 2.0.1 مثبت بـ pip، وملف إعدادات يتخطى معالج البداية Setup Wizard ويفعل الطابعة الافتراضية Virtual Printer المرفقة مع OctoPrint، والملف في `lab/octoprint-config.yaml`:

```yaml
server:
  firstRun: false
  onlineCheck:
    enabled: false
  pluginBlacklist:
    enabled: false
plugins:
  tracking:
    enabled: false
  virtual_printer:
    enabled: true
serial:
  port: VIRTUAL
  baudrate: 0
  autoconnect: true
```

ثم أنشأنا مستخدماً مديراً بكلمة مرور عشوائية من `openssl rand -hex 12`، وشغلنا الخادم:

```bash
octoprint user add admin --password "$PW" --admin
octoprint serve --host 0.0.0.0 --port 5000
```

واتصل OctoPrint بالطابعة الافتراضية وحدها، وهذا من سجله:

```text
octoprint.plugins.serial_connector.serial_comm - INFO - Changing monitoring state from "Detecting serial connection" to "Operational"
octoprint.plugins.serial_connector.serial_comm - INFO - Printer reports firmware name "Virtual Marlin 1.0"
octoprint.plugins.serial_connector.serial_comm - INFO - Firmware states that it supports temperature autoreporting
```

والطابعة الافتراضية برنامج داخل OctoPrint يتصرف كأنه Marlin على كابل تسلسلي: يرد `ok` ويرسل الحرارة ويسخن ببطء، كما في [صفحة الطابعة الافتراضية في وثائق OctoPrint](https://docs.octoprint.org/en/2.0.1/development/virtual%5Fprinter.html?ref=arabroot.io). ورفعنا إليها أولاً ملف Klipper نفسه `clip.gcode` عبر [واجهة الملفات](https://docs.octoprint.org/en/2.0.1/api/files.html?ref=arabroot.io)، وهذا خطأ مقصود، فماذا يحدث لسطر `START_PRINT` على طابعة Marlin؟ هذا ما سجلته الطابعة الافتراضية:

```text
05:04:16,373 >>> ok
05:04:16,378 <<< START_PRINT BED_TEMP=60 EXTRUDER_TEMP=215
05:04:16,378 <<< N1 G21*27
05:04:16,379 >>> ok
05:04:16,379 >>> ok
```

الطابعة قبلت السطر بـ `ok` صامتة، دون خطأ، وأكمل OctoPrint الملف كله في 49.476 ثانية، والسخانان على صفر طوال الوقت. وعلى طابعة Marlin حقيقية تحميها إعدادات منع البثق البارد Cold Extrusion Prevention سوف ترى رأساً يتحرك فوق السرير دون خيط، وعلى طابعة بإعدادات أضعف تحاول المحركات دفع خيط صلب في فوهة باردة. والقاعدة: ملف G-code مقطوع لطابعة بعينها وبرنامجها الثابت، فلا تنقله بين Klipper وMarlin دون أن تقطعه من جديد، لأن الطابعة لن تقول لك دائماً إنها لا تفهم.

ثم قطعنا الملف من جديد بنكهة Marlin في خيار G-code Flavor، أي `--gcode-flavor marlin2` مع أوامر التسخين في الملف نفسه، ورفعناه وطبعناه، وفي سجل الطابعة الافتراضية ترى `M190` ينتظر السرير:

```text
05:06:30,175 <<< N1 M190 S60*95
05:06:30,177 >>> B:21.38
05:06:31,177 >>> B:31.39
05:06:32,177 >>> B:41.39
05:06:33,176 >>> B:51.39
05:06:34,177 >>> B:60.00
05:06:35,177 >>> ok
```

فالطابعة لا ترد بـ `ok` على `M190` حتى يصل السرير إلى الحرارة، وترسل الحرارة كل ثانية أثناء الانتظار، ولهذا ينتظر OctoPrint ولا يرسل السطر التالي، وهذا هو معنى «انتظر» في [وثائق M109 في Marlin](https://marlinfw.org/docs/gcode/M109.html?ref=arabroot.io). ولاحظ أيضاً أن كل سطر يحمل رقمه ومجموع تحققه، مثل `N1 M190 S60*95`، وأن الطابعة الافتراضية تفتعل أخطاء في الأسطر 100 و105 و110 و115 لتختبر OctoPrint، وهذا ما حدث عند السطر 100:

```text
<<< N100 G1 X114.57 Y102.003 E4.5076*101
>>> Error: Missing checksum
>>> Resend:100
>>> ok
<<< N100 G1 X114.57 Y102.003 E4.5076*101
>>> ok
```

فطلبت الطابعة إعادة السطر 100، فأعاده OctoPrint بالرقم نفسه، وأكمل. وهذه الآلية التي يبدأها الأمر [M110](https://marlinfw.org/docs/gcode/M110.html?ref=arabroot.io) بتصفير رقم السطر هي التي تحمي الطباعة من بايت تالف على كابل USB طويل بجانب محركات تحدث تشويشاً كهربائياً. وفي واجهة OctoPrint ظهر هذا كله في خانة «Error ratio» بأربعة أخطاء من 11,700 سطر تقريباً:

![واجهة OctoPrint 2.0.1: لوحة الحالة تقول Printing ونسبة الأخطاء 4 من 11.7K، والملف clip-marlin.gcode، ورسم الحرارة يظهر الفوهة عند 181.7 درجة تصعد نحو 215 والسرير عند 60، وقائمة الملفات فيها clip-marlin.gcode وclip.gcode](https://arabroot.io/content/images/2026/11/klipper-octoprint-18-octoprint-printing.webp)

OctoPrint 2.0.1 يطبع على الطابعة الافتراضية: نسبة الأخطاء 4 من 11.7K سطر، كلها أخطاء مفتعلة أعيد إرسالها

وانتهت هذه الطباعة في 87.053 ثانية بحسب سجل OctoPrint، والملف نفسه أخذ على Klipper 13 دقيقة و49 ثانية من الطباعة. والسبب أن الطابعة الافتراضية في OctoPrint لا تحاكي زمن الحركة، وإنما ترد على كل سطر بعد تأخير صغير ثابت، فهي أداة لاختبار الاتصال والإضافات والواجهة، لا لتقدير الوقت. أما Klipper في تجربتنا فحسب كل حركة بتسارعها الحقيقي ونفذها المتحكم في وقتها، ولهذا جاء وقته قريباً من تقدير PrusaSlicer.

### تنظيف المختبر Cleanup

```bash
docker rm -f elp-klipper elp-octoprint
docker rmi elp-klipper:1 elp-octoprint:1
```

ولا توجد Volumes في هذه التجربة، فكل الملفات داخل الحاويتين، وملفات الإعداد مربوطة من مجلد `lab` للقراءة فقط.

## تشكيل الإدخال Input Shaper وضغط الخيط Pressure Advance

هاتان الميزتان من أهم أسباب انتقال الناس إلى Klipper، ولا يمكن تجربتهما على طابعة وهمية لأنهما تعالجان أشياء فيزيائية: اهتزاز الإطار، وضغط البلاستيك المنصهر في الفوهة. لذلك تركنا قسميهما في `printer.cfg` معلقين، ونشرحهما هنا من الوثائق.

![مقارنة بين موجة اهتزاز كبيرة تتلاشى ببطء بدون Input Shaper وموجة صغيرة جداً معه، وتحتهما أربع خطوات: قياس التردد بمقياس تسارع ADXL345 أو نموذج الرنين، واختيار الشكل mzv أو ei، والكتابة في printer.cfg، ثم ضبط pressure_advance](https://arabroot.io/content/images/2026/11/klipper-octoprint-13-input-shaper.webp)

الفكرة وخطوات الضبط كما في صفحتي Resonance Compensation وPressure Advance

عندما يغير الرأس اتجاهه بسرعة في زاوية، يهتز إطار الطابعة بتردد الرنين Resonance Frequency الخاص به، فتظهر على الجدار بعد الزاوية تموجات صغيرة متكررة تسمى Ringing أو Ghosting. وتشكيل الإدخال، كما في [صفحة Resonance Compensation](https://www.klipper3d.org/Resonance%5FCompensation.html?ref=arabroot.io)، يقسم كل تسارع إلى نبضات متتالية مصممة بحيث تلغي النبضة الثانية اهتزاز الأولى عند ذلك التردد بالذات. وتحتاج لهذا أن تعرف التردد، وهناك طريقتان: أن تطبع نموذج الرنين من مستودع Klipper وتقيس المسافة بين التموجات بالمسماك Caliper، فتحسب التردد من السرعة V وعدد التموجات N والمسافة D بالمعادلة V·N/D، أو أن تركب مقياس تسارع Accelerometer مثل ADXL345 على الرأس وتشغل الأمر `TEST_RESONANCES` كما في [صفحة Measuring Resonances](https://www.klipper3d.org/Measuring%5FResonances.html?ref=arabroot.io)، والأداة تقترح الشكل والتردد. وفي الحالتين تكتب النتيجة هكذا، والقيمة 49.4 هي مثال الوثائق نفسها:

```ini
[input_shaper]
shaper_freq_x: 49.4
shaper_freq_y: 49.4
shaper_type: mzv
```

أما ضغط الخيط، كما في [صفحة Pressure Advance](https://www.klipper3d.org/Pressure%5FAdvance.html?ref=arabroot.io)، فيعالج أن البلاستيك في الفوهة يتصرف كنابض: عندما يتسارع الرأس يتأخر خروج الخيط، وعندما يبطئ عند الزاوية يستمر الضغط فتخرج كتلة زائدة. فيدفع Klipper الطارد أكثر قليلاً عند التسارع وأقل عند التباطؤ بنسبة تحددها أنت. والضبط بطباعة مربع مجوف مع الأمر `TUNING_TOWER` الذي يرفع القيمة مع كل طبقة، ثم تقيس الارتفاع الذي تبدو فيه الزوايا أفضل:

```text
SET_VELOCITY_LIMIT SQUARE_CORNER_VELOCITY=1 ACCEL=500
TUNING_TOWER COMMAND=SET_PRESSURE_ADVANCE PARAMETER=ADVANCE START=0 FACTOR=.005
```

والقيمة النهائية بحسب الوثائق تساوي البداية زائد الارتفاع المقاس مضروباً في المعامل، مثل 0 + 12.90 × 0.020 = 0.258 في مثالها لطارد Bowden، والقيم المعتادة بين 0.050 و1.000\. وتكتبها في قسم `[extruder]` باسم `pressure_advance`، وهي تختلف بين خامة وأخرى، ولهذا يضعها كثيرون في كود بداية الخامة في برنامج التقطيع بالأمر `SET_PRESSURE_ADVANCE`. وابدأ دائماً بتشكيل الإدخال ثم ضغط الخيط، لأن الأول يغير شكل الحركة الذي يبني عليه الثاني.

## الأمان Security: لا تعرض الطابعة على الإنترنت

الطابعة المتصلة بالشبكة جهاز إنترنت أشياء IoT فيه سخان ومحركات، وكل ما ذكرناه في [مقال أمن إنترنت الأشياء](https://arabroot.io/articles/%D8%A7%D9%85%D9%86-%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D8%A7%D9%84%D8%A7%D8%AC%D9%87%D8%B2%D8%A9-%D8%A7%D9%84%D8%AA%D9%8A-%D9%8A%D9%86%D8%B3%D8%A7%D9%87%D8%A7-%D8%A7%D9%84%D8%AC%D9%85%D9%8A%D8%B9/) ينطبق عليها، مع فرق مهم: من يتحكم بها يستطيع أن يسخنها ويحركها، لا أن يقرأ بياناتها فقط. وفيما يلي ما يجب أن تفعله:

- **لا تفتح المنفذ في الراوتر Port Forwarding:** لا لـ Moonraker على 7125، ولا لـ OctoPrint على 5000 أو 80\. وإذا أردت الوصول من خارج البيت أو الورشة فاستخدم شبكة خاصة VPN، كما في [VPN إلى بيتك على Raspberry Pi مع WireGuard](https://arabroot.io/articles/vpn-%D8%A7%D9%84%D9%89-%D8%A8%D9%8A%D8%AA%D9%83-%D8%B9%D9%84%D9%89-raspberry-pi-%D9%85%D8%B9-wireguard/).
- **ضيق trusted\_clients في Moonraker:** القيمة التي يضعها الناس كثيراً هي الشبكة المحلية كلها، وهذا مقبول في البيت، أما في مكتب مشترك فاستخدم المستخدمين وكلمات المرور في قسم `[authorization]`.
- **OctoPrint بمستخدم وكلمة مرور قوية:** OctoPrint يطلب إنشاء مدير عند أول تشغيل، فلا تتخطاه، ولا تشارك مفتاح API مع إضافات لا تعرف مصدرها.
- **حدث البرامج:** Moonraker وOctoPrint يعرضان التحديثات في الواجهة، فطبقها، ولكن ليس أثناء طباعة طويلة، ولا قبل أن تقرأ ملاحظات الإصدار.
- **الكاميرا تكشف المكان:** رابط الكاميرا Stream يعمل غالباً دون مصادقة، فإذا كانت الواجهة خلف كلمة مرور فتأكد أن الكاميرا كذلك.

## عدة طابعات Printer Farm

عندما تصبح لديك طابعتان أو ثلاث، فالنموذج الأبسط والأكثر شيوعاً أن يكون لكل طابعة حاسوبها وتثبيتها الكامل، أي Pi لكل طابعة، لأن عطل أحدها لا يوقف البقية، ولأن klippy يحتاج الاستجابة السريعة التي رأينا ثمنها. ثم تجمعها في واجهة واحدة: Mainsail وFluidd تسمحان بإضافة عدة طابعات من إعداداتهما، فتنتقل بينها من قائمة في أعلى الصفحة، وكل واحدة تبقى مستقلة بملفاتها وسجلها. ويمكن أيضاً تشغيل عدة نسخ من Klipper وMoonraker على حاسوب واحد قوي بمنافذ ومجلدات `printer_data` مختلفة، وKIAUH يدعم هذا، ولكن ضعه في حسابك فقط عندما يكون الحاسوب أقوى بكثير من حاجة الطابعات.

وفي ورشة صغيرة تطبع لعملاء، فإن ما يهم بعد ذلك هو التنظيم أكثر من البرامج:

- **اسم ثابت لكل طابعة:** في اسم الحاسوب Hostname وفي الواجهة وعلى ملصق على الطابعة نفسها، حتى لا ترفع ملف خامة PETG إلى طابعة فيها PLA.
- **إعدادات في Git:** مجلد `config` لكل طابعة في مستودع، فتعرف من غير ماذا ومتى، وتستعيد الإعدادات بعد تعطل بطاقة SD.
- **طابور المهام Job Queue:** Moonraker فيه طابور يبدأ الملف التالي عندما ينتهي الحالي، وهو مفيد عندما تكون إزالة القطعة آلية أو عندما يكون أحد بجانب الطابعة.
- **السجل والتكلفة:** وقت الطباعة الحقيقي وطول الخيط من سجل Moonraker أو OctoPrint هما أساس تسعير القطعة، وقد رأينا الفرق بين 14m 1s المقدرة و13m 49s الحقيقية.
- **تنبيهات:** إشعار عند الانتهاء أو عند توقف الطابعة، عبر Moonraker أو إضافة في OctoPrint، أو عبر MQTT كما في [مقال MQTT مع Mosquitto](https://arabroot.io/articles/%D8%A8%D8%B1%D9%88%D8%AA%D9%88%D9%83%D9%88%D9%84-mqtt-%D9%85%D8%B9-mosquitto-%D9%83%D9%8A%D9%81-%D8%AA%D8%AA%D9%83%D9%84%D9%85-%D8%A7%D9%84%D8%A7%D8%AC%D9%87%D8%B2%D8%A9/).

## Klipper أم OctoPrint؟ Decision Table

لا يوجد جواب واحد، وهذا الجدول يلخص متى يناسب كل منهما:

| حالتك                                                         | الأنسب                              | لماذا                                                                 |
| ------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------- |
| طابعة جاهزة تعمل جيداً بـ Marlin ولا تريد لمس برنامجها الثابت | OctoPrint                           | يعمل مع البرنامج الموجود، والرجوع عنه بنزع كابل USB                   |
| تريد سرعة أعلى وجودة أفضل في الزوايا                          | Klipper                             | Input Shaper وPressure Advance والحساب على الحاسوب                    |
| تبني طابعتك بنفسك أو تعدل فيها كثيراً                         | Klipper                             | الإعدادات ملف نصي، والماكرو يغني عن إعادة بناء البرنامج الثابت        |
| تحتاج إضافة معينة موجودة لـ OctoPrint فقط                     | OctoPrint، أو OctoPrint فوق Klipper | مكتبة إضافات أكبر وأقدم                                               |
| الحاسوب بجانب الطابعة ضعيف أو مشغول بأشياء أخرى               | OctoPrint مع Marlin                 | تأخر الحاسوب يبطئ الإرسال فقط، أما في Klipper فيوقف الطباعة كما رأينا |
| عدة طابعات في ورشة                                            | Klipper مع Mainsail أو Fluidd       | عدة طابعات في واجهة واحدة، وإعدادات نصية في Git                       |

## أخطاء شائعة Common Mistakes

- **تشغيل برامج ثقيلة على حاسوب Klipper:** رأينا أن تأخيراً واحداً أكثر من 1 ملي ثانية يكفي ليتوقف المتحكم برسالة `Stepper too far in past` أو `Timer too close`، فلا تضع على الـ Pi نفسه خادم ملفات وقاعدة بيانات ونظام مراقبة ثقيلاً.
- **نقل ملف G-code بين Klipper وMarlin:** الطابعة قد تقبل `START_PRINT` صامتة وتطبع باردة، فاقطع الملف لكل طابعة.
- **ترك برنامج التقطيع يضيف أوامر الحرارة:** مع ماكرو `START_PRINT` أوقف الإضافة التلقائية في PrusaSlicer، أو اكتب الحرارة داخل كود البداية بنفسك.
- **إطفاء الحماية الحرارية أو رفع قيمها:** رسالة `not heating at expected rate` عطل حقيقي، فافحص الحساس والسخان، وأعد معايرة PID.
- **كابل USB رديء أو طويل بجانب أسلاك المحركات:** يظهر كأرقام في `bytes_retransmit` أو كأخطاء في نسبة الأخطاء في OctoPrint، ثم كتوقف مفاجئ.
- **تحديث Klipper دون تحديث البرنامج الثابت للمتحكم:** klippy يرفض العمل إذا اختلف الإصداران كثيراً، فخطط للتحديث في يوم لا تحتاج فيه الطابعة.
- **تثبيت إصدار قديم على نظام حديث:** كما رأينا مع cffi وgreenlet على Python 3.13، فاقرأ أول خطأ في مخرج pip.
- **فتح الواجهة على الإنترنت:** لا يوجد سبب لذلك مع وجود VPN.

## قبل أن تترك الطابعة تطبع وحدها Checklist

| البند                 | كيف تتحقق                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| الحماية الحرارية      | لا يوجد قسم verify\_heater بقيم مرتفعة، وجربت أن الطابعة تتوقف إذا فصلت السخان وهي باردة             |
| الحاسوب مستقر         | مزود طاقة رسمي، ولا رسائل Timer too close في klippy.log خلال أسبوع                                   |
| الاتصال نظيف          | bytes\_retransmit ثابت أثناء الطباعة، أو نسبة الأخطاء صفر في OctoPrint                               |
| الملف للطابعة الصحيحة | نكهة G-code واسم الطابعة في برنامج التقطيع، وأول الملف فيه START\_PRINT أو أوامر التسخين، لا الاثنين |
| الإيقاف والإلغاء      | جربت PAUSE وRESUME وCANCEL\_PRINT مرة على قطعة صغيرة وأنت بجانب الطابعة                              |
| المراقبة              | الكاميرا تعمل، والتنبيه عند الانتهاء أو التوقف يصلك على الجوال                                       |
| الأمان                | لا منافذ مفتوحة في الراوتر، والوصول من الخارج عبر VPN فقط                                            |
| النسخة الاحتياطية     | مجلد printer\_data/config في Git أو منسوخ خارج الجهاز                                                |
| المكان                | كاشف دخان في الغرفة، ولا مواد قابلة للاشتعال حول الطابعة                                             |

## تدريب عملي Practice

1. غير قيمة `max_accel` في `lab/printer.cfg` من 3000 إلى 1000، وأعد طباعة `clip.gcode` على الطابعة الوهمية، وقارن وقت الطباعة الحقيقي في السجل بالتقدير 14m 1s، ثم فكر: لماذا يتغير الوقت مع أن الملف لم يتغير؟
2. اكتب ماكرو `END_PRINT` يرسل رسالة بطول الخيط المستخدم من `printer.print_stats.filament_used` عبر `RESPOND`، وجربه في نهاية الطباعة.

## الخلاصة Summary

- الإدارة عن بعد ترفع الملف من برنامج التقطيع وتعطيك المراقبة والتحكم والسجل، ولكنها لا تغني عن الحماية الحرارية وكاشف الدخان.
- OctoPrint يأخذ مكان بطاقة SD ويرسل الملف سطراً سطراً برقم ومجموع تحقق، ويعمل مع Marlin كما هو.
- Klipper يقسم العمل: klippy على الحاسوب يقرأ الملف ويحسب الحركة، والمتحكم ينفذ خطوات مؤقتة بالساعة، وMoonraker يقدم الـ API، وMainsail أو Fluidd واجهة في المتصفح.
- هذا التقسيم يجعل الحاسوب جزءاً من الطابعة: تأخره أكثر من 1 ملي ثانية أوقف الطابعة الوهمية، وفي Docker Desktop قسنا تأخيراً حتى 33 ملي ثانية.
- طبع Klipper الوهمي ملفاً كاملاً من 39 طبقة في 13 دقيقة و49 ثانية مقابل تقدير 14 دقيقة وثانية، وعدد خطوات المحور Z طابق الحساب بالضبط: 18,740 خطوة.
- الإيقاف في Klipper يحفظ موضع القراءة في الملف، وماكرو `PAUSE` يسحب الخيط ويرفع الرأس، وكل ذلك ظهر بالأرقام في Moonraker.
- الملف المقطوع لـ Klipper طبع دون تسخين ودون أي خطأ على طابعة Marlin الافتراضية، فاقطع لكل برنامج ثابت ملفه.
- Input Shaper ثم Pressure Advance يحتاجان طابعة حقيقية وقياساً، والوثائق تشرح الطريقتين بالمسماك أو بمقياس التسارع.

[![](https://arabroot.io/content/images/2026/11/3d-printing-basics-cover-cover-2.webp)دليلالطباعة ثلاثية الأبعاد 3D Printing: FDM والراتنج Resinكيف تبني الطابعة القطعة طبقة فوق طبقة، والفرق بين طابعات الخيط FDM والراتنج، وأيهما يناسب مشاريع الإلكترونيات.](https://arabroot.io/articles/%D8%A7%D9%84%D8%B7%D8%A8%D8%A7%D8%B9%D8%A9-%D8%AB%D9%84%D8%A7%D8%AB%D9%8A%D8%A9-%D8%A7%D9%84%D8%A7%D8%A8%D8%B9%D8%A7%D8%AF-3d-printing-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86-fdm-%D9%88%D8%A7%D9%84%D8%B1%D8%A7%D8%AA%D9%86%D8%AC-resin/)[![](https://arabroot.io/content/images/2026/11/3d-slicers-cover-cover-2.webp)دليلبرامج التقطيع Slicers: Cura وPrusaSlicer وOrcaSlicerماذا يفعل برنامج التقطيع بقطعتك قبل الطابعة، مع قطعة واحدة قطعناها في ثلاثة برامج من سطر الأوامر وقرأنا ملف G-code سطراً سطراً.](https://arabroot.io/articles/%D8%A8%D8%B1%D8%A7%D9%85%D8%AC-%D8%A7%D9%84%D8%AA%D9%82%D8%B7%D9%8A%D8%B9-slicers-%D9%85%D8%B9-prusaslicer-%D9%88-orcaslicer-%D9%88-cura/)[![](https://arabroot.io/content/images/2026/11/enclosures-3d-printing-cover-cover-2.webp)دليلالغلاف Enclosure بالطباعة ثلاثية الأبعادكيف تصمم غلافاً مطبوعاً للوحة ESP32 يفصل الحساس عن حرارتها ويترك للهوائي مسافته، وتفحصه بالكود قبل أن تطبعه.](https://arabroot.io/articles/%D8%BA%D9%84%D8%A7%D9%81-enclosure-%D9%84%D8%AF%D8%A7%D8%B1%D8%AA%D9%83-%D8%A8%D8%A7%D9%84%D8%B7%D8%A8%D8%A7%D8%B9%D8%A9-%D8%AB%D9%84%D8%A7%D8%AB%D9%8A%D8%A9-%D8%A7%D9%84%D8%A7%D8%A8%D8%B9%D8%A7%D8%AF/)[![](https://arabroot.io/content/images/2026/11/raspberry-pi-vs-mcu-cover-cover-2.webp)دليلRaspberry Pi أم متحكم دقيق؟ الفرق ومتى تختارالفرق بين حاسوب Linux صغير ومتحكم دقيق بالأرقام: مهمة تتكرر كل ملي ثانية تأخرت على Linux حتى 20 ملي ثانية، وعلى المتحكم 5 ميكروثانية فقط، ومتى تختار كلاً منهما.](https://arabroot.io/articles/%D9%85%D9%82%D8%A7%D8%B1%D9%86%D8%A9-raspberry-pi-%D9%85%D8%B9-%D8%A7%D9%84%D9%85%D8%AA%D8%AD%D9%83%D9%85-%D8%A7%D9%84%D8%AF%D9%82%D9%8A%D9%82-microcontroller/)[![](https://arabroot.io/content/images/2026/11/rtos-freertos-zephyr-cover-cover-1.webp)دليلأنظمة التشغيل الفورية RTOS مع FreeRTOS ثم Zephyrنشرح المهام والمجدول والطوابير والأقفال في الأنظمة الفورية، ثم نعيد مشكلة انعكاس الأولوية التي أوقفت Mars Pathfinder على FreeRTOS ثم Zephyr في QEMU، ونقيسها قبل الإصلاح وبعده.](https://arabroot.io/articles/%D8%A7%D9%86%D8%B8%D9%85%D8%A9-%D8%A7%D9%84%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D8%A7%D9%84%D9%81%D9%88%D8%B1%D9%8A%D8%A9-rtos-%D9%85%D8%B9-freertos-%D8%AB%D9%85-zephyr/)[![](https://arabroot.io/content/images/2026/11/iot-security-cover-cover-1.webp)دليلأمن إنترنت الأشياء IoT: الأجهزة التي ينساها الجميعنهاجم وسيط MQTT في مختبر غرفة التبريد كما يفعل من يدخل الشبكة، فنطفئ الضاغط ونسرق كلمة المرور، ثم نغلقه بالتشفير والصلاحيات وتقسيم الشبكة ونعيد الهجوم.](https://arabroot.io/articles/%D8%A7%D9%85%D9%86-%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D8%A7%D9%84%D8%A7%D8%AC%D9%87%D8%B2%D8%A9-%D8%A7%D9%84%D8%AA%D9%8A-%D9%8A%D9%86%D8%B3%D8%A7%D9%87%D8%A7-%D8%A7%D9%84%D8%AC%D9%85%D9%8A%D8%B9/)

## سجل التحديثات Changelog

- نوفمبر 2026: كتابة المقال، والتجربة على Klipper v0.13.0 بمتحكم Linux process مع مكتبة fakegpio، وMoonraker v0.11.0، وMainsail v2.19.0، وOctoPrint 2.0.1 بطابعته الافتراضية، وملف مقطوع بـ PrusaSlicer 2.9.7، داخل Docker Desktop، بتاريخ 20 نوفمبر 2026.