دليل دمج مجموعة تطوير PMSOpticDll V4.4.7 لعدسات التكبير المحرّكة

تكشف مجموعة تطوير PMSOptical عن 44 دالة C مُصدَّرة من ملف DLL واحد على Windows، وتغطي الاتصال التسلسلي والإيثرنت، والتحكّم بالموضع المطلق، وقراءة الحالة، ومزايا بطاقة التحكم المشفّرة، وعائلة واجهة كاملة متوازية لعدسات المحرك المزدوج. سير العمل الأساسي هو أربع استدعاءات: فتح → منزل → حركة → انتظار. ويُحصل على مقبض بـ PMSOptical_OpenComm("COM1", 9600) للتسلسلي، أو PMSOptical_OpenSocket("192.168.1.200", 4196) لـ TCP.

يُوثّق هذا الدليل عائلات الدوال، وتسلسل الاستدعاء الموصى به، والقيود الأربعة للدمج التي تسبب معظم مشاكل الدمج الأول، بما فيها ما يهمّ لسلامة الآلة: لا تحتوي مجموعة التطوير على توقف اضطراري برمجي قابل للاستخدام.

معلومات أساسية في لمحة

تخطيط الحزمة

PMSOptical-SDK/
├── Doc/
│   ├── POMEAS electric lens development documents V4.4.7.pdf   (English)
│   ├── encrypted / non-encrypted development documents V4.4.7  (control-card comparison)
│   └── dual-motor control card operation manual V1.5
├── SDK/
│   ├── include/PMSOpticalDll.h            44 exported functions
│   ├── x64/{Release,Debug}/PMSOpticalDll.dll + .lib
│   │   └── OP/*.txt                       per-model pulse tables
│   └── x86/{Release,Debug}/               same, 32-bit
└── demo/
    └── x64/PMSOpticalDemo.exe + .ini      MFC demo application

يجب أن يوجد ملف DLL بجانب الملف التنفيذي أو على متغير النظام PATH.

الاتصال

للاتصال الشبكي، يجب أن يكون حاسوب المضيف وبطاقة تحكم العدسة على نفس الشبكة الفرعية — يجب أن تتطابق الأجزاء الثلاثة الأولى من العنوان، مثل 192.168.1.xxx. ويُحصَل على قناع الشبكة الفرعية تلقائياً.

#include "PMSOpticalDll.h"

PMSHANDLE h = PMSOptical_OpenComm("COM2", 9600);            // serial
// PMSHANDLE h = PMSOptical_OpenSocket("192.168.1.200", 4196);  // Ethernet
if (!h) { /* connection failed */ }

الدوال الـ 44 حسب العائلة

العائلة 1 — إدارة الاتصال (1–4)

تمرّر الدالتان 3 و4 نتيجتهما ومقبضها بالمرجع. هذا متعمَّد: يلاحظ الترويسة أن التوقيعات صِيغت هكذا لتوافق P/Invoke في C#.

العائلة 2 — تحكّم أحادي المحرك (5–15)

تلفّ WaitForOpticalFinished منطق استطلاع الحالة داخلياً — تستطلع استعلام الحالة وتراقب مؤشر التوقف — بمهلة افتراضية قدرها 100000 مللي ثانية. وفي معظم التطبيقات ينبغي استدعاؤها بدل كتابة حلقة استطلاع خاصة بك.

العائلة 3 — بطاقة التحكم المشفّرة (16–24)

متاحة فقط عند تزويد العدسة ببطاقة التحكم المشفّرة (يُدل عليها encrypt في اسم ملف جدول النبضات).

ما الذي تصلح له البطاقة المشفّرة فعلاً: تخزّن عدّاد دورات التكبير وكتلة هوية العدسة بطول 64 بايت في Flash المتحكّم. وهذا يدعم تتبّع أصول المعدّات وإحصاءات الاستخدام والتعريف بالعدسة الأصلية — وهو مفيد مباشرةً للمندمجين والأساطيل المؤجَّرة وعمليات ما بعد البيع.

العائلة 4 — عدسات المحرك المزدوج (25–44)

كل دالة أعلاه لها نسخة متوازية بلاحقة 2 ومعامل إضافي unsigned char u8lensnum = 0 يختار المحرك 1 أو المحرك 2.

تزاوج عدسات المحرك المزدوج محرك تكبير بمحرك ضبط بؤري مستقل — مثل عدسة تكبير 12.5X بضبط بؤري مدعوم 12 مم، أو 12.5X بمحرك مزدوج بمحور ضبط 3 مم.

// Dual motor: motor 0 = zoom, motor 1 = focus trim
PMSOptical_GoHome2(h, 0);
PMSOptical_MoveTo2(h, 4600, 0);                        // zoom to 1X (see the model pulse table)
PMSOptical_WaitForOpticalFinished2(h, 100000, 0);

تسلسل الاستدعاء الموصى به

Open (serial or Ethernet)
   |
GoHome()  ->  WaitForOpticalFinished(timeout)
   |
GetMaxPos()  ->  validate total travel, and confirm the link is alive
   |
+-- MoveTo(pulse)
|     ->  WaitForOpticalFinished(timeout)   (or poll GetStatus until it returns 1)
|     ->  GetPos()  ->  compare with target (closed loop)
+-- repeat for the next magnification
   |
Close()

يحدّد مخطط التدفق المرجعي للصانع ثلاث قواعد لمسار الاستطلاع:

1. انتظر 50 مللي ثانية على الأقل قبل كل استعلام حالة.
2. اضبط مهلة شاملة — يقترح الدليل 10 ثوانٍ أو أكثر.
3. إذا انقضت المهلة الشاملة دون رد صالح، أعلن خطأ اتصال العدسة واخرج بنظافة.

أربعة قيود للدمج

1. تتوقف الاتصالات أثناء حركة المحرك

أثناء قيادة بطاقة التحكم للمحرك، تُعلّق الاتصالات. قد لا يُرجع استعلام الحالة أي شيء على الإطلاق. تعامل مع هذا بأسلوب المهلة وإعادة المحاولة، أو باستدعاء WaitForOpticalFinished. لا تعتبره عطلاً ولا تُعِد تشغيل الاتصال.

2. طلب حركة مساوٍ للموضع الحالي لا يفعل شيئاً

إذا تساوت النبضة المطلوبة مع النبضة الحالية، فلا تتحرك العدسة ولا تبلّغ عن نجاح. لا تستخدم أبداً «إرسال الأمر» كاختبار لحياة الرابط. استخدم GetMaxPos أو GetPos بدلاً من ذلك.

3. تستغرق التهيئة عند التشغيل 25–35 ثانية

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

4. لا يوجد توقف اضطراري برمجي

كل من Stop وStop2 موسومتان غير مُنفَّذة في الترويسة، إلى جانب IsHomed وJogStart وJogStop ونظيراتها ثنائية المحرك — ثمان دوال في المجموع. لا تبنِ وظيفة سلامة عليها. حدّد الاكتمال بـ GetStatus أو WaitForOpticalFinished، ونفّذ التوقف الاضطراري بدائرة عتاد — قطع الطاقة أو إشارة تداخل خارجية.

قواعد عتادية يعتمد عليها البرنامج

1. اربط كبل المحرك وكبل RS-232 وقفلهما قبل توصيل الطاقة. إن توصيلهما أثناء التشغيل قد يضرّ بدارة القيادة.
2. لا تصل أو تفصل كبل المحرك أبداً أثناء التشغيل. هذا أكثر الأفعال تخريباً في الميدان، ويمكن أن يلحق ضرراً دائماً بالمحرك.
3. إذا كان كبل المحرك يجب أن يتجاوز 5 م، فاطلب كبل المصنع الطويل. لا تلحم عدة كبلات قصيرة أو تصنع كابلك بنفسك.
4. اختر التسلسلي أو الإيثرنت، لا كلاهما. تدعم بطاقة التحكم أحدهما؛ يجب أن يتطابق وضع الاتصال البرمجي مع التوصيل العتادي.

بطاقة تحكم مشفّرة أم قياسية؟

الأسئلة الشائعة

هل يدعم برنامج SDK نظامي Linux أو macOS؟

يُوزَّع برنامج SDK الرسمي على ملفات DLL لـ Windows فقط (x64 وx86). على المنصات الأخرى، نفّذ البروتوكول التسلسلي مباشرة — هو خمسة أوامر ASCII عادية بلا اعتماد على منصة، فيعمل على أي مضيف بمنفذ تسلسلي أو مقبس TCP.

هل يمكنني استدعاء برنامج SDK من Python؟

نعم، عبر ctypes أو cffi، لأن الدوال المُصدَّرة تستخدم ربط C. لا يوجد ارتباط رسمي لـ Python، فتكتب الغلاف بنفسك. لاحظ أن PMSHANDLE مؤشّر void* ويجب تمرير معاملات bool& بـ ctypes.byref.

هل يمكنني خلط برنامج SDK والأوامر التسلسلية الخام؟

تقنياً نعم، لكن لا تفعل. كلاهما يتناول نفس سجلّات الأجهزة، والخلط بينهما — خصوصاً حول مرجع العودة إلى المنزل — يُنتج حالة غير متسقة. اختر منهجاً واحداً لكل مشروع.

ما المهلة التي أستخدمها لـ WaitForOpticalFinished؟

الافتراضي 100000 مللي ثانية. اضبطه على ضعف مدة أطول سفر تكبير على أجهزتك على الأقل. والرقم المرجعي في الدليل هو 10 ثوانٍ أو أكثر.

هل هذه واجهة رؤية بالذكاء الاصطناعي؟

لا، ولا ينبغي وصفها كذلك. توفّر مجموعة التطوير واجهة تحكّم بصري قابلة للبرمجة — الموضع والحالة والقراءة المرتدة. يمكن دمجها في بنية رؤية بالذكاء الاصطناعي، حيث تصدر البرمجيات الإشرافية أمر تكبير جديداً بناءً على نتيجة فحص، لكن مجموعة التطوير نفسها لا تحتوي قدرات ذكاء اصطناعي أو تحليل صور. والصياغة الدقيقة هي أن عدسات التكبير المحرّكة يمكن دمجها في سير عمل رؤية آلية يتحكّم به الذكاء الاصطناعي.

هل توجد مشاكل معروفة في ملف الترويسة؟

اثنتان تستحقان المعرفة. يُعرّف GetVer2 معامله بـ u8lennum — خطأ إملائي لا يؤثر على الاستدعاء، لكن يستحسن توحيده في غلافك. والدوال الثماني غير المُنفَّذة المذكورة أعلاه يجب ألا يُعتمد عليها.

مقالات ذات صلة

• مرجع أوامر RS-232 التسلسلية — طبقة البروتوكول تحت مجموعة التطوير
• ربط التكبير بالموضع بالنبضات — القيم الممرّرة إلى MoveTo
• دليل استكشاف أعطال عدسة التكبير المحرّكة
• البصريات القابلة للبرمجة في الرؤية الآلية

منتجات ذات صلة

• عدسة تكبير محرّكة 12.5X للفحص الآلي
• عدسة تكبير محورية محرّكة 12.5X للرؤية الآلية
• PMS-LZ-650104 — عدسة تكبير مستمر محرّكة 6.5X
• عدسة تكبير محرّكة بمحركين C-mount 12.5X