> 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.md).

# MQTT Subscribe

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

## 📥 المدخلات <a href="#inputs" id="inputs"></a>

* `Enable` مدخل — تمكين أو تعطيل الاشتراك. عندما يكون نشطًا، يتصل البلوك بالوسيط (broker) ويستمع للرسائل.

## 📤 المخرجات <a href="#outputs" id="outputs"></a>

* `Data` مخرج — أحدث حمولة رسالة مستلمة (نص) من الموضوع المشترك به.
* `New Data` مخرج — مخرج بولياني يصبح true لمرّة واحدة في التشغيل عندما تصل رسالة جديدة.

## 🕹️ عناصر التحكم <a href="#controls" id="controls"></a>

* `Broker Address` اسم المضيف أو عنوان IP لوسيط MQTT للاتصال به.
* `Port` منفذ TCP للوسيط (غالبًا 1883 أو 8883 عند استخدام TLS).
* `Topic` سلسلة الموضوع للاشتراك بها (يدعم المطابقة الدقيقة للموضوع).
* `Client ID` معرف اختياري لعميل MQTT.
* `Username` اسم مستخدم اختياري لمصادقة الوسيط.
* `Password` كلمة مرور اختيارية لمصادقة الوسيط.
* `Keep Alive` الفاصل الزمني للحفاظ على اتصال الوسيط.
* `Use TLS` تبديل لتمكين اتصال آمن TLS (إذا دعمه الوسيط).
* `Reconnect / Connect` زر أو منطق تلقائي في واجهة المستخدم لإعادة إنشاء الاتصال عند تغيير الإعدادات.

(قد يختلف شكل ظهور هذه الضوابط في واجهة المستخدم؛ قدّم معطيات اتصال صحيحة وقم بتمكين البلوك لبدء استقبال الرسائل)

## 🎯 الميزات <a href="#features" id="features"></a>

* اشتراك مستمر طالما أن `Enable` مفعل — تُستقبل الرسائل في الوقت الحقيقي.
* يوفر كلًا من `Data` الخام وعَلَم `New Data` لمرة تشغيل واحدة حتى تتمكن البلوكات التالية من الاستجابة فقط للرسائل الجديدة.
* يعيد الاتصال تلقائيًا إذا تغيّرت إعدادات الاتصال.
* تظهر حالة الاتصال ورسائل معلوماتية أساسية في واجهة البلوك لمساعدتك في تشخيص أحداث الاتصال.

## ⚙️ آلية التشغيل <a href="#running-mechanism" id="running-mechanism"></a>

* عندما يكون `Enable` مفعلًا، يستخدم البلوك إعدادات الاتصال المُكوّنة للاتصال بوسيط MQTT والاشتراك في `Topic` المحدد.
* تُخزن الرسائل الواردة داخليًا وتُعرض على مخرج `Data`.
* يضع البلوك `New Data` على true فقط للتشغيل الذي يلي وصول رسالة جديدة مباشرة؛ في التشغيلات التالية يُعاد تعيينه إلى false حتى تستلم رسالة جديدة.
* يؤدي تغيير إعدادات الاتصال إلى إعادة اتصال البلوك حتى تصبح المعاملات الجديدة نافذة المفعول.

## 📝 تعليمات الاستخدام <a href="#usage" id="usage"></a>

1. املأ معطيات الاتصال: `Broker Address`, `Port`, و`Topic` (أضف بيانات الاعتماد إن تطلب الوسيط ذلك).
2. فعّل البلوك عبر مدخل `Enable`.
3. استخدم مخرج `Data` لتمرير الحمولة المستلمة إلى بلوكات أخرى. استخدم مخرج `New Data` لتشغيل المعالجة التالية فقط عند وصول رسالة جديدة.
4. إذا غيرت إعدادات الاتصال، انتظر لحظة قصيرة ليعيد البلوك الاتصال قبل توقع استقبال الرسائل.

## 💡 نصائح وحيل <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* لإعادة توجيه الرسائل المستلمة إلى خادم أو خدمة، اربط `Data` بـ `REST API - Post`.
* لإعادة نشر أو صدى الرسائل، اجمع هذا البلوك مع `MQTT Publish` أو `MQTT Publish (TLS-Beta)`.
* استخدم `Data to JSON` لترتيب حقول متعددة من النص الوارد قبل تسجيلها أو تصديرها.
* احفظ الرسائل الواردة للمراجعة لاحقًا بربط `Data` بـ `CSV Export` أو إلى `SQL-DB Operations` (عبر `Data to JSON` أو التنسيق المناسب).
* أضف `Debug Input` لتفحص محتوى الرسائل بسرعة في نافذة السجل أثناء التطوير.
* عند التعامل مع صيغ متغيرة، استخدم `Replace None` أو `Is None` للتعامل مع الرسائل المفقودة أو التالفة بشكل سلس.

(تلميحات أعلاه تستخدم فقط البلوكات المتاحة في النظام)

## 🛠️ استكشاف الأخطاء وإصلاحها <a href="#troubleshooting" id="troubleshooting"></a>

* لا توجد رسائل مستلمة: تحقق من صحة `Broker Address`, `Port` و`Topic` وأن الوسيط قابل للوصول من الجهاز الذي يشغل السيناريو.
* أخطاء المصادقة: تحقق من `Username` و`Password` وما إذا كان الوسيط يتطلب TLS.
* انقطاع الاتصال بشكل متقطع: تحقق من إعدادات الشبكة/الجدار الناري وجرب تمكين TLS أو تعديل `Keep Alive`.
* تصل الرسائل ولكن لا يتم تمريرها: تأكد من تفعيل البلوكات اللاحقة واستخدم عَلَم `New Data` إذا كان عليها العمل فقط على الحمولات الجديدة.
* إذا عدّلت المعاملات، انتظر قليلاً بعد إعادة التمكين حتى يعيد البلوك الاتصال قبل توقع الرسائل.