البرمجيات الأساسية HALO Smart Sensor API

إلى الأمام

يصف هذا المستند مجموعة مرافق مستشعر Halo Smart المعروف مجتمعة باسم BASIC API ، أو واجهة برمجة التطبيقات. هذه المناقشة مخصصة للاستخدام من قبل المبرمجين أو الدمجين المهتمين بدمج واحد أو أكثر من مستشعرات HALO الذكية (HALO) مع مكونات أو أنظمة برامج الطرف الثالث (غير IPVideo). بشكل عام ، تهدف HALO API إلى نقل المعلومات بكفاءة من HALO عبر شبكة إيثرنت تقليدية إلى البرنامج الخارجي. لتحقيق هذا الهدف ، يتم تقسيم واجهة برمجة التطبيقات إلى ثلاثة أقسام: اتصال مأخذ بواسطة الحدث ، اتصال مقبس نبضات القلب ، وبيانات الأحداث URL. واجهة BACnet موجودة أيضًا ومغطاة في مستند منفصل.

تصميم واجهة برمجة التطبيقات

تم تصميم API باستخدام التنسيقات القياسية الصناعية مثل TCP / IP. HTTP و HTTPS و JSON. لا يتطلب التصميم أي تقنيات أو مكتبات خاصة أو خاصة لاستخدامها في تطوير البرنامج أو التطبيق الخارجي. تتميز واجهة برمجة التطبيقات بالمرونة ويمكن تهيئتها وبرمجتها لتقديم البيانات المطلوبة بالضبط وبأكثر الطرق كفاءة. يتم تناول تفاصيل تشغيل كل قسم من الأقسام المذكورة أعلاه في الأقسام التالية من هذا الدليل.

الرسائل الخارجية

تُستخدم هذه الميزة لتسليم التنبيهات أو الإنذارات وبيانات الأحداث إلى برنامج خارجي ، أو نظام VMS ، أو خادم ، وما إلى ذلك عند تشغيل حدث (يتم تعيينه). يمكن أيضًا تمكين الرسائل الاختيارية للإشارة عند مسح حدث (إعادة تعيينه). يمكن أن يتم هذا التسليم لمقبس TCP / IP أو خادم HTTP / S في الوقت الفعلي. هناك مجموعة من البروتوكولات القابلة للتكوين بمحتويات قابلة للتخصيص. المصادقة والتشفير متاحان.

نبض القلب

يتم إرسال رسائل Heartbeat بفاصل زمني قابل للتكوين (بدلاً من وقت تشغيل الأحداث) لتقديم دليل على البث المباشر / التوفر. لديهم مجموعة مماثلة من القدرات مثل المراسلة الخارجية ولكن يتم تكوينها عادةً لاحتواء معلومات الحالة العامة بدلاً من تفاصيل حول حدث معين.

بيانات الحدث URL

هذا المرفق متاح فقط بموجب اتفاقية عدم الإفشاء ويجب استخدامه فقط عندما يتطلب البرنامج الخارجي الوصول إلى أي وجميع قيم الأحداث والحدود وعلامات الحالة. يتم استرداد هذه البيانات بشكل عام عند الطلب بواسطة البرنامج الخارجي ولكن ليس بتردد عالٍ جدًا. تتحمل هذه الطريقة عمومًا بعض وقت الاستجابة عند استخدام معدل اقتراع متواضع. تتراوح معدلات الاستقصاء النموذجية من مرة واحدة في الدقيقة إلى مرة واحدة لكل 5 ثوانٍ بحد أقصى مطلق لمرة واحدة في الثانية. يمكن استخدام هذه الطريقة أيضًا لاسترداد بيانات داعمة إضافية عند تلقي حدث (تنبيه).

تفاصيل المراسلة الخارجية

قسم من HALO web توفر النافذة المنبثقة لتكامل الواجهة تكوين اتصال طرف ثالث واحد حيث يمكن إرسال قيم مختلفة إلى مقبس TCP بعيد أو خادم HTTP / HTTPS. تُستخدم حوامل المكان (الرموز المميزة) لإدراج القيم الحية في النص المرسل. على الرغم من تسميتها "المراسلة الخارجية" ، يمكن استخدام هذه القناة لأي غرض تقريبًا يتطلب مشغلات الأحداث في الوقت الفعلي ، والتي يتم تقديمها بنشاط بواسطة HALO. هذا الترتيب مرن للغاية لأن التحديدات على "الإجراءات" تحدد أحداث HALO التي ترسل عبر هذه القناة.

في وضع HTTP ، تكون سلاسل Set و Reset هي ملفات URLالتي يجب إدخالها وتنسيقها على النحو المطلوب من قبل الخادم الوجهة المطلوب. يمكن استخدام حقل المستخدم وكلمة المرور للمصادقة. انظر وضع HTTP أدناه.

في وضع TCP ، تكون سلاسل Set و Reset هي فقط بيانات رسالة واحدة يتم إرسالها إلى مأخذ توصيل TCP المستلم. يمكن تنسيقها حسب الحاجة بواسطة الوجهة. يتم تحديد الوجهة في حقلي العنوان والمنفذ. انظر وضع TCP أدناه.

بالنسبة لأي من الوضعين ، يتم عرض الحالة من أحدث رسالة والتي يمكن أن تساعد في إصلاح الاتصال أو مشكلات أخرى. يمكنك استخدام أزرار Event TEST في قائمة الإجراءات المنبثقة لفرض رسالة:

يجب أن يكون التشغيل / الإيقاف الشامل للتعيين أو إعادة التعيين في وضع التشغيل لتمكين تلك الأنواع من الرسائل. غالبًا ما لا يتم استخدام إعادة التعيين لأن بداية الحدث فقط هي التي تهم ، ولكن يمكن أن يختلف ذلك. يمكن لكل حدث تحديد ما إذا كان سيستخدم إما رسالة المجموعة أو إعادة التعيين في قائمة الإجراءات المنبثقة. ستعرض أزرار مقلة العين تمثيلًا تقريبيًا لما يتم إرساله بعد استبدال الكلمات الرئيسية وتنسيقها. يمكن استخدام التوقف المتكرر لخنق الرسائل المتكررة عن طريق التأخير قبل إرسال رسالة أخرى. يتم ذلك بشكل مستقل لكل حدث. HALO لديه وقت تعليق مدمج للأحداث يبلغ 15 ثانية لمنع إعادة التشغيل السريع للأحداث. إذا كنت تريد التأكد من عدم إرسال أكثر من حدث واحد من النوع في الدقيقة ، فيمكنك تعيين Repeat Holdoff على 1 (ثانية).

تفاصيل نبضات القلب

تعمل إرسالات Heartbeat بطريقة مشابهة لما ورد أعلاه باستثناء عدم وجود تفاعل مع صفحة الإجراءات. بدلاً من ذلك ، يحدث إرسال Heartbeat على أساس منتظم كما تم تكوينه باستخدام حقل الفاصل الزمني ، في وضع HTTP ، تكون سلاسل الضبط وإعادة التعيين هي URLالتي يجب إدخالها وتنسيقها على النحو المطلوب من قبل الخادم الوجهة المطلوب. يمكن استخدام حقل المستخدم وكلمة المرور للمصادقة. انظر وضع HTTP أدناه.

في حين أن الغرض الأساسي من Heartbeat هو توفير دليل على حياة مستشعر HALO الذكي إلى تطبيق بعيد ، يمكن أيضًا استخدام هذه الرسالة لنقل أجهزة الاستشعار المحددة أو معلومات حالة الحدث الحالية. السابقampيرسل le أعلاه معلمة سلسلة طويلة مع URL التي تتضمن اسم Halo ، ومعظم قيم أجهزة الاستشعار ، وأخيرًا تم التشغيل =٪ ACTIVE٪ والتي يمكن أن تكون فارغة أو قائمة بالأحداث التي تم تشغيلها حاليًا.

وضع HTTP (و HTTPS)

يمكن أن تكون سلاسل الرسائل الخارجية ونبضات القلب http: أو https: URLق حسب الحاجة. يمكن إدخال المسار والمعلمات حسب الحاجة بواسطة الخادم الوجهة. يمكن إدراج كلمات رئيسية مثل٪ NAME٪ (اسم جهاز HALO) أو٪ EID٪ (معرّف الحدث) حسب الحاجة وسيتم استبدالها بالبيانات ذات الصلة عند إرسال الرسالة. يتم عرض قائمة بالكلمات الرئيسية شائعة الاستخدام للرجوع إليها بسرعة.
ال URL يمكن أن يحتوي المسار على كلمات رئيسية بالإضافة إلى معلمات ملف URL. قد تكون المعلمات NAME = VALUE أزواج أو كائن JSON ، أو تنسيقًا مخصصًا اعتمادًا على الخادم الوجهة. السابقampقد تتضمن les للمراسلة الخارجية٪ EID٪ للإشارة إلى الحدث الذي تم تشغيله:

• https://server.com/event/%NAME%/%EID%
• https://server.com/event?location=%NAME%&event=%EID%
• https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}

Exampقد تضيف les for Heartbeat٪ ACTIVE٪ (الأحداث التي يتم تشغيلها حاليًا) أو قيمة المستشعر:

• https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
• https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
  المستشعر٪:… تستخدم قيم٪ الأسماء الموجودة في عناوين أعمدة المستشعر الأيمن في سجل evtYYYMMDD.csv fileس. هم عادة:

إذا كان الخادم الوجهة يفضل HTTP PUT أو POST بدلاً من طلبات GET ، فيمكنك بادئة URL مع PUT: أو POST :. بشكل مستقل ، يمكنك إضافة حمولة JSON الشائعة لدى العديد من الخوادم عن طريق إضافة الكلمة الأساسية [JSONBODY] متبوعة بكائن بتنسيق JSON. السابقampعلى:
PUT: https: //server.com/event [JSONBODY] {"الموقع": "٪ NAME٪"، "الحدث": "٪ EID٪"}
ال URL يدعم عنوان IP النموذجي (و IPv6) وخيارات المنفذ وكلمة مرور المستخدم ، أو يمكنك استخدام حقلي المستخدم وكلمة المرور إذا لزم الأمر ليكون الخادم الوجهة لأساليب المصادقة مثل Basic أو Digest:
https://username:password@123.321.123.321:9876/event…

وضع TCP

تعتبر سلاسل الرسائل الخارجية و Heartbeat مخصصة للبيانات فقط لأن حقلي "العنوان" و "المنفذ" يحددان الوجهة. يدعم العنوان الأسماء ، IPv4 و IPv6.
يمكن تنسيق السلسلة مثل أجزاء البيانات لرسائل HTTP الموضحة أعلاه ، أو كما هو مطلوب من قبل الخادم الوجهة.
Exampقد تتضمن les للمراسلة الخارجية٪ EID٪ للإشارة إلى الحدث الذي تم تشغيله:
الموقع =٪ NAME٪ ، الحدث =٪ EID٪
{“location”: ”:٪ NAME٪”، ”event”: ”٪ EID٪”}
Exampقد تضيف les for Heartbeat٪ ACTIVE٪ (الأحداث التي يتم تشغيلها حاليًا) أو قيمة المستشعر:
الموقع =٪ NAME٪ & المشغل =٪ ACTIVE٪
{“location”: ”:٪ NAME٪”، “NH3”:٪ SENSOR: NH3٪}

تحدد مربعات الاختيار الموجودة في عمودي "مجموعة التكامل" و "إعادة تعيين التكامل" الأحداث التي تؤدي إلى الإرسال. يتوفر المزيد حول إعداد الأحداث والإجراءات في دليل مسؤول HALO.

تسليم رسائل حدث JSON
يفضل بعض المطورين تلقي بيانات الأحداث بتنسيق JSON القياسي في الصناعة بدلاً من نص ASCII العادي لأن الأول أكثر موثوقية وأكثر سهولة في التحليل. على HALO web صفحة "المراسلة" ، يمكنك توفير رسائل JSON في إعدادات "المراسلة الخارجية" "تعيين السلسلة" و "إعادة تعيين السلسلة" وفي "رسالة" نبض القلب.

Exampليه:
سلسلة إعدادات "المراسلة الخارجية":

{"الجهاز": "٪ NAME٪"، "الحدث": "٪ EID٪"، "المنبه": "نعم"}
سيؤدي هذا إلى إرسال رسالة TCP أو UDP JSON واحدة إلى الخادم المحدد للإبلاغ عن اسم الجهاز المألوف واسم الحدث وأنه بدأ للتو.

إعدادات "المراسلة الخارجية" إعادة تعيين السلسلة:
{"الجهاز": "٪ NAME٪"، "الحدث": "٪ EID٪"، "المنبه": "لا"}
سيؤدي هذا إلى إرسال رسالة TCP أو UDP JSON واحدة إلى الخادم المحدد للإبلاغ عن اسم الجهاز المألوف واسم الحدث وأن الحالة قد توقفت الآن.

رسالة "نبضات القلب":
{"الجهاز": "٪ NAME٪" ، "على قيد الحياة": "٪ DATE٪٪ TIME٪"}
سيؤدي هذا بشكل دوري إلى إرسال رسالة TCP أو UDP JSON إلى الخادم المحدد للإبلاغ عن أن HALO ما زال على قيد الحياة في الوقت المحدد.

المستندات / الموارد

البرمجيات الأساسية HALO Smart Sensor API [بي دي اف] دليل المستخدم برنامج HALO Smart Sensor API الأساسي

مراجع

• دليل المستخدم