> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/arabic/alblwkat-alwzyfyh/blocks-reference/input-output/communication/mqtt-subscribe-tls-beta.md).

# MQTT Subscribe (TLS-Beta)

هذا الـ function block يتصل بـ MQTT broker ويستمع للرسائل على موضوع (Topic) محدد باستخدام اتصال TLS (آمن). يستقبل حمولة نصية (text payload) ويصدر إشارة عند وصول بيانات جديدة حتى تتمكن من معالجتها أو تمريرها داخل السيناريو الخاص بك.

## 📥 المدخلات

`Enable`\
مقبس إدخال منطقي (Boolean) يتحكم بفعالية الاشتراك. اضبطه على TRUE للسماح باستقبال الرسائل؛ FALSE يعطل المعالجة.

## 📤 المخرجات

`Data`\
النص (payload) الخاص بآخر رسالة تم استلامها.

`New Data`\
علامة منطقية تصبح TRUE لتقييم واحد عندما تصل رسالة جديدة.

## 🕹️ الضوابط

`Server / Broker`\
أدخل عنوان أو اسم المضيف الخاص بـ MQTT broker.

`Port`\
منفذ الاتصال بالـ broker (المنفذ الشائع لـ TLS هو 8883).

`Topic`\
حدد الموضوع (topic) للاشتراك. الرسائل الواردة على هذا الموضوع تظهر في مخرج `Data`.

`Client ID`\
معرف اختياري لهذا العميل على الـ broker.

`Username`\
اسم مستخدم اختياري لمصادقة الاتصال.

`Password`\
كلمة مرور اختياريّة لمصادقة الاتصال.

`Use TLS`\
تبديل لتمكين وضع الاتصال الآمن (TLS).

`CA Certificate`\
خيار لتوفير أو الإشارة إلى حزمة شهادات CA للتحقق من شهادات TLS (البلوك يدعم التحقق باستخدام CA النظامي).

`Connect`\
زر أو تحكم لبدء أو إعادة إنشاء الاتصال بالإعدادات الحالية.

`Auto Reconnect`\
تبديل لإعادة الاتصال تلقائيًا عند انقطاع الاتصال.

ملاحظة: إذا كان لدى البلوك واجهة مضغوطة، قد تُجمع بعض الخيارات المتقدمة أو تُوضع تحت قسم "Advanced".

## 🎯 الميزات

* اشتراك MQTT آمن بدعم TLS للاتصال المشفّر.
* وسم رسائل جديدة مباشر عبر مخرج `New Data` بحيث يمكنك تشغيل المعالجة التالية فقط عند الحاجة.
* مرونة اختيار الموضوع للاشتراك في أي MQTT topic صالح.
* إعدادات اتصال ومصادقة أساسية لتغطية معظم تكوينات الـ broker.
* معالجة إعادة الاتصال بسلاسة حتى لا تتطلب الانقطاعات المؤقتة تدخلاً يدويًا.

## 📝 تعليمات الاستخدام

1. اضبط تفاصيل الـ broker باستخدام ضوابط `Server / Broker` و`Port` وبيانات المصادقة إن لزم.
2. أدخل الموضوع الذي تريد الاستماع إليه في تحكم `Topic`.
3. فعّل البلوك بإرسال TRUE إلى المدخل `Enable` أو باستخدام زر الاتصال في واجهة البلوك.
4. اقرَأ الحمولة النصية الواردة من مخرج `Data`. استخدم مخرج `New Data` لتشغيل كتل لاحقة فقط عند وصول رسالة جديدة.
5. إذا غيّرت معايير الاتصال، استخدم تحكم `Connect` (أو قم بإيقاف/تشغيل `Enable`) لتطبيق التغييرات.

## 📊 التقييم

عند التفعيل، يحافظ هذا البلوك على اشتراك في الموضوع المُكوّن. عند كل تشغيل، يصدر آخر حمولة مستلمة عبر `Data` ويضع `New Data` على TRUE فقط عند وصول رسالة جديدة منذ التقييم السابق.

## 💡 نصائح وحيل

* استخدم `Parse Data Dictionary` أو `Data to JSON` بعد `MQTT Subscribe (TLS-Beta)` لتحويل نص JSON الوارد إلى قيم مُهيكلة للمعالجة.
* لتسجيل الرسائل الواردة، وصل `Data` إلى `CSV Export` أو `Data to JSON` ثم إلى بلوك تصدير.
* اجمع مع `Debug Input` لطباعة الرسائل أو فحصها أثناء الإعداد.
* استخدم `Logic Input` أو `Rising Edge` لتشغيل إجراءات فقط عندما يصبح `New Data` TRUE.
* لسيناريوهات موزعة، أمزج هذا البلوك مع `Data Write Global` / `Data Read Global` لمشاركة آخر رسالة عبر فروع مختلفة من السيناريو.
* إذا كانت الرسالة تحتوي مراجع أو بيانات صورة مشفرة، فكِّ الشفرة وأرسل الصورة إلى `Show Image` لمعاينتها.
* عند نشر ردود أو إشعارات، استخدم بلوك المقابل `MQTT Publish (TLS-Beta)` لإرسال الرسائل إلى الـ broker.

## 🛠️ تحرّي الخلل وإصلاحه

* فشل الاتصال: تحقق من `Server / Broker` و`Port` وإمكانية الوصول للشبكة. تأكد من أن منفذ TLS وقواعد الجدار الناري صحيحة.
* أخطاء المصادقة: أعد فحص `Username` و`Password` وتحقق من صلاحيات الوصول في الـ broker (ACLs).
* لا تظهر رسائل: تأكد من صحة سلسلة الـ `Topic` (الرموز البريّة wildcards والتدرج مهمّان) وأن عميلًا آخر ينشر إلى الموضوع. استخدم عميل اختبار بسيط للتأكد.
* تنسيق الرسائل غير متوقع: استخدم `Parse Data Dictionary` أو `String Operations` لفحص وتوحيد الحمولات.
* مشاكل TLS: إذا فشل التحقق من الشهادة، تأكد من توفر حزمة شهادات CA أو استخدم خيار CA النظامي. لأغراض التحليل فقط، جرّب اتصالًا غير TLS (إن سمح الـ broker) لعزل سبب المشكلة.