5Tech Edge Bridge (ESP32) — MVP للمرحلة الأولى — دليل المستخدم والتشغيل

الإعداد والتحميل الوميضي وتهيئة Wi-Fi / MQTT وأوامر Bluetooth LE وتدفّق العرض التوضيحي لجهاز ESP32 Edge Bridge.

esp32-edge-bridge · مسودة مراجعة (مبدئية) · 2026-07-08 · الحالة: مبدئية

مبدئي. يصف هذا الدليل MVP للمرحلة الأولى على لوحة تطوير ESP32 جاهزة للاستخدام. وهو نموذج أولي للمراقبة والأتمتة، وليس منتجًا مكتملًا أو معتمدًا. الإجراءات والقيم المميّزة بـ [TBD] بانتظار التأكيد. وثائق الهندسة المعتمَدة موجودة في modules/5tech-edge-iot-bridge/؛ اتّبع دائمًا الوثائق المرفقة بالبرنامج الثابت الذي حمّلته.

الشكل FIG-001 — 5Tech Edge Bridge، وهو MVP للمرحلة الأولى الذي يربط مدخلًا بتدفّق أتمتة عبر Wi-Fi وBluetooth LE وMQTT.

---

1. السلامة

اقرأ هذا الفصل قبل إعداد الـ Edge Bridge أو تشغيله أو تعديله.

الشكل FIG-002 — الكلمات التنبيهية (خطر · تحذير · تنبيه · إشعار) والرموز التصويرية المستخدمة في هذا الدليل.

1.1 الكلمات التنبيهية

1.2 هذا ليس جهاز سلامة

إشعار — ليس جهاز سلامة. إن 5Tech Edge Bridge نموذج أولي للمراقبة والأتمتة على لوحة تطوير. وهو لا يحمل أي اعتماد سلامة من أي نوع ويجب ألّا يُستخدم لحماية الأشخاص أو المعدات، ولا لإيقاف الآلات، ولا لإنشاء منطقة حماية، ولا كجزء من أي وظيفة سلامة وظيفية. حالات الخطر لديه (WARNING / DANGER) هي إشارات عرض توضيحي في خط بيانات، وليست مخرجات سلامة. لا تعتمد عليه أبدًا حيث قد يسبّب الفشل إصابة أو خسارة. (هذا تنويه بشأن النطاق حول ما ليس عليه الجهاز — إشعار وفق §1.1، وليس تحذيرًا من خطر بشأن الجهاز نفسه.)

1.3 الاستخدام المقصود والجمهور

يُقصد بالـ Edge Bridge الاستخدام من قِبل المطورين والفنيين والمُدمِجين على منضدة اختبار موثوقة للتحقق من خط المعالجة من المستشعر إلى الأتمتة ولعرضه على العملاء وأصحاب المصلحة. يُعدّ أي استخدام آخر — وعلى وجه الخصوص النشر الميداني أو استخدام السلامة أو الاتصال بشبكة غير موثوقة — إساءة استخدام لهذا الـ MVP للمرحلة الأولى.

1.4 الأفراد المؤهَّلون والكفاءة المطلوبة

إعداد الـ Edge Bridge وتشغيله وتوصيله وتعديله للأفراد المؤهَّلين فقط. وبالنسبة لهذا الـ MVP للمرحلة الأولى، يعني ذلك شخصًا:

• يكون مطوّرًا أو فنيًا أو مُدمِجًا كفؤًا في إلكترونيات الجهد المنخفض والمناولة الآمنة من التفريغ الكهروستاتيكي (ESD) للوحة PCB مجرّدة؛
• يستطيع تحميل البرنامج الثابت وميضيًا وقراءة وحدة تحكّم تسلسلية، ويفهم منطق 3.3 V وأن أطراف GPIO لا تتحمّل 5 V (§1.5)؛
• يفهم MQTT / Bluetooth LE على شبكة LAN موثوقة والطبيعة النصية الصريحة وغير المُوثَّقة لهذا النموذج الأولي (§1.7)؛
• وقبل توصيل أي شيء بمخرج Con1 أو مدخلَي Det1 / Det2، يستطيع تأكيد جهد الدارة الخارجية وتيارها وعزلها مقابل ورقة البيانات.

يجب ألّا يقوم شخص يفتقر إلى هذه الكفاءة بإعداد الجهاز أو توصيله أو تعديله دون إشراف.

1.5 السلامة الكهربائية

تُغذّى اللوحة من مصدر USB 5 V وتعمل بجهد منخفض (منطق 3.3 V). خطر الصعقة الكهربائية من اللوحة نفسها ضئيل، لكن:

إشعار — تلف المعدات. أطراف GPIO هي منطق 3.3 V وغير متحمّلة لـ 5 V. قد يؤدي تطبيق أكثر من 3.3 V على مدخل GPIO أو تقصير الأطراف أو عكس وصلة إلى إتلاف اللوحة. غذِّ اللوحة من مصدر واحد في كل مرة (USB أو قضيب خارجي 3.3 V/5 V، وليس كليهما). راعِ احتياطات التفريغ الكهروستاتيكي (ESD) عند مناولة اللوحة العارية.

• استخدم كبل USB يدعم البيانات ومنفذ أو مصدر USB معروف الجودة.
• إذا وصّلت مستشعرًا خارجيًا أو حِملًا بمخرج Con1، فأكّد أن جهده وتياره ضمن القيمة الاسمية للطرف ([TBD]) قبل التوصيل. لا تُبدّل التيار الكهربائي الرئيسي أو حِملًا حثّيًا مباشرةً من طرف GPIO.

1.6 ملاحظة حول الترددات الراديوية (RF)

تبثّ اللوحة عبر Wi-Fi (2.4 GHz) وBluetooth LE من خلال الهوائي المدمج في الوحدة. قدرة الإرسال منخفضة ونموذجية لوحدة ESP32 استهلاكية. اعتمادات الراديو الإقليمية لـالنموذج الأولي المُجمَّع هي [TBD] — هذا جهاز تطوير، فشغّله فقط حيثما يُسمح بهذا الاستخدام وأبقِه على شبكة منضدة موثوقة.

1.7 المخاطر المتبقية

حتى عند الاستخدام على النحو المقصود، تبقى الأمور التالية: قد يُثبّت الجهاز حالة خطر ويستمر في الإبلاغ بـ DANGER بعد تعافي المستشعر (هذا متعمَّد — انظر §3.3)؛ وعلى شبكة بنص عادي يمكن لأي شخص يصل إلى الوسيط (broker) أن يتحكّم في الجهاز؛ ويتشارك Bluetooth LE وWi-Fi هوائيًا واحدًا، لذا تتفاوت استجابة BLE مع حِمل Wi-Fi. لا شيء من هذه تخفيفٌ للسلامة.

---

2. حول هذا الدليل

النطاق. يغطي هذا الدليل إعداد الـ Edge Bridge MVP للمرحلة الأولى على لوحة تطوير ESP32 وتحميله الوميضي وتهيئته وتشغيله واستكشاف أعطاله. وهو لا يحلّ محل وثائق الهندسة التفصيلية في مستودع البرنامج الثابت.

الجمهور. المطورون والفنيون والمُدمِجون كما هو موصوف في §1.3.

الاصطلاحات.

• تستخدم إشعارات السلامة الكلمات التنبيهية في §1.1 وتظهر قبل الخطوة التي تنطبق عليها.
• الإجراءات مرقَّمة، إجراء واحد لكل خطوة.
• يُشير [TBD] إلى قيمة بانتظار التأكيد. لا تستبدل أبدًا قيمة مُخمَّنة بـ [TBD].
• يدلّ الخط أحادي المسافة على الأوامر وأسماء الملفات وأسماء الأطراف والمواضيع (topics) ونص الواجهة/وحدة التحكم.

الوثائق ذات الصلة.

---

3. نظرة عامة على المنتج ومبدأ التشغيل

الشكل FIG-003 — الـ Edge Bridge ووصلاته: USB والمداخل الاختيارية وراديوا 2.4 GHz.

3.1 ما الذي يفعله

يقرأ الـ Edge Bridge مدخلًا، ويقرّر ما إذا كان ذلك المدخل يمثّل حالة WARNING أو DANGER، ويعيد نشر القرار كـ JSON منظَّم عبر Bluetooth LE وMQTT بحيث يمكن لتدفّق أتمتة أن يتصرّف بناءً عليه. وهو يعمل على لوحة تطوير ESP32 قياسية ولا يحتاج إلى عتاد مستشعر للعرض التوضيحي.

3.2 موقعه — Sense → Connect → Decide

• Sense — مستشعر GPIO (Det1 / Det2) أو الزر المدمج أو مستشعر مُحاكى أو أمر بعيد يشير إلى حالة.
• Connect — يحلّ ESP32 حالته وينشر عبر Wi-Fi إلى وسيط MQTT؛ وتمنح قناة Bluetooth LE تحكمًا محليًا حتى بلا شبكة.
• Decide — يشترك تدفّق أتمتة (n8n / Node-RED / مخصَّص) ويقود لوحات المعلومات والتنبيهات والسجلات.

3.3 مبدأ التشغيل

1. هوية الجهاز. عند الإقلاع يشتق الجهاز هويته من عنوان MAC للوحدة: معرّف MQTT 5tech-bridge-a1b2c3 واسم BLE 5Tech-IoT-Bridge-a1b2c3 (آخر ست خانات ست عشرية من MAC).
2. آلة الحالات. تسع حالات — BOOTING وWIFI_CONNECTING وMQTT_CONNECTING وREADY وWARNING وDANGER وOFFLINE وCONFIG_MODE وERROR. بمجرد التشغيل، تُحلّ الحالة بأولوية صارمة: error > danger > warning > config_mode > !wifi > READY. ولكل حالة نمط وميض خاص بها لمؤشر LED المدمج.
3. تثبيت الأخطار. تُرتَّب مستويات الخطر NORMAL < WARNING < DANGER. الرفع إلى مستوى أعلى يفوز وينشر حدثًا؛ والرفع إلى مستوى مساوٍ أو أدنى عملية بلا تأثير. يُثبَّت الخطر — والمستشعر المتعافي لا يمسحه تلقائيًا. فقط أمر clear صريح (أو مهلة مهيَّأة، معطَّلة افتراضيًا) يُعيد إلى NORMAL.
4. النشر. تُنشر القياسات عن بُعد كل 5 s، ويُنشر حدث فورًا عند أي تغيير، وتُحتفَظ الحالة على الوسيط مع Last Will بحيث يرى المشترك المتأخر دائمًا الحالة الحقيقية. الخطر يفوق الاتصال: جهاز في DANGER يستمر في الإبلاغ بـ DANGER حتى لو سقط Wi-Fi.
5. الأوامر. تعمل قواعد الأوامر نفسها على التسلسلي وBluetooth LE وMQTT. تُوضع الأوامر في طابور وتُنفَّذ على الحلقة الرئيسية، وليس على مهمة استدعاء راديو أبدًا.

---

4. عناصر التحكم والمؤشرات

الشكل FIG-004 — الأطراف والزر المدمج ومؤشر LED للحالة وموصِّل USB، مع مفتاح إيضاحي مرقَّم.

أرقام الأطراف الدقيقة هي الإعدادات الافتراضية للمرحلة الأولى؛ أكّدها مقابل ورقة البيانات والطباعة الحريرية (silkscreen) على لوحتك.

إشعار. في معظم لوحات تطوير ESP32 يكون GPIO2 هو مؤشر LED المدمج. تستخدمه المرحلة الأولى لحالة الجهاز، لذا نُقِل Con1 إلى GPIO23. لاستعادة التوصيل الأصلي، اضبط CON1_GPIO = 2 وENABLE_STATUS_LED = 0 (حارس وقت الترجمة يفرض ألّا يتشاركا طرفًا أبدًا).

---

5. التشغيل

5.1 قبل أن تبدأ

تحتاج إلى: لوحة تطوير ESP32-WROOM-32، وكبل USB يدعم البيانات، وحاسوب مضيف بسلسلة الأدوات، و(لمسار Wi-Fi/MQTT) وسيط MQTT مثل mosquitto على شبكة LAN الموثوقة نفسها. لا يلزم عتاد مستشعر.

يتوفّر طرازان من البرنامج الثابت وهما قابلان للتبادل على السلك:

الإعداد الكامل لسلسلة الأدوات موجود في modules/5tech-edge-iot-bridge/docs/setup.md.

5.2 تهيئة secrets والتحميل الوميضي

إشعار. secrets.h مُدرَج في gitignore ويجب ألّا يُودَع (commit) أبدًا. يُتتبَّع فقط secrets.example.h.

طراز ESP-IDF:

1. انسخ القالب: cp firmware/esp-idf/main/config/secrets.example.h firmware/esp-idf/main/config/secrets.h
2. حرّر secrets.h — اضبط WIFI_SSID وWIFI_PASSWORD وMQTT_HOST.
3. ابنِ وحمّل وميضيًا: cd firmware/esp-idf && idf.py set-target esp32 && idf.py build
4. idf.py -p /dev/ttyUSB0 flash monitor

طراز Arduino / PlatformIO:

1. cp firmware/platformio/src/config/secrets.example.h firmware/platformio/src/config/secrets.h
2. حرّر secrets.h كما ورد أعلاه.
3. cd firmware/platformio && pio run && pio run -t upload
4. pio device monitor

5.3 أول تشغيل والتحقق من الحالة

1. وصّل اللوحة عبر USB وافتح المراقب التسلسلي عند 115 200 باود.
2. أكّد أن الجهاز يطبع هويته (5tech-bridge-…) ويبدأ تسلسل الإقلاع.
3. راقبه وهو يقترن بـ Wi-Fi، ويتصل بالوسيط، ويبدأ البثّ الإعلاني لـ Bluetooth LE.
4. أكّد استقرار مؤشر LED للحالة على نمط READY.
5. إذا لم يتصل Wi-Fi خلال ~15 ثانية، يستمر الجهاز غير متصل: يظل BLE والتسلسلي يعملان وتُقرأ الحالة OFFLINE. هذا متوقَّع وليس عطلًا.

5.4 وضع المنضدة (بلا Wi-Fi)

ترك WIFI_SSID على عنصره النائب هو وضع منضدة مدعوم: يتخطّى الجهاز Wi-Fi، ويُقلِع إلى CONFIG_MODE، ويبقى قابلًا للاستخدام تمامًا عبر Bluetooth LE ووحدة التحكم التسلسلية. تعمل كل الأوامر؛ نشر MQTT وحده غير متاح.

5.5 تدفّق العرض التوضيحي

1. على حاسوب محمول على شبكة LAN نفسها، اشترك في الوسيط: mosquitto_sub -h <broker> -t "5tech/iotbridge/+/#" -v
2. أطلِق تحذيرًا — من وحدة التحكم التسلسلية، أو من هاتف عبر Bluetooth LE (اكتب test_warning إلى الخاصية Cmd)، أو بالنشر إلى موضوع الأوامر. الثلاثة متكافئة.
3. راقب [STATE] READY -> WARNING، وتغيّر إيقاع LED، ووصول الحدث إلى الوسيط.
4. أطلِق test_danger. يسرع LED ويُثبَّت الخطر (danger).
5. أرسِل clear. يعود الجهاز إلى READY.
6. اشرح النقطة: المُشغِّل وحده مُحاكى — استبدله بمستشعر حقيقي ولن يتغيّر شيء في اتجاه المصبّ.

5.6 الإيقاف المنظم

ببساطة افصل USB. عند الفصل غير المنظم، ينشر الوسيط Last Will المُحتفَظ به، فتنقلب حالة الجهاز إلى OFFLINE لأي مشترك. وفي الإقلاع التالي يستبدلها الجهاز بحالة حيّة.

---

6. التهيئة

6.1 طرق التهيئة

6.2 أوامر وقت التشغيل

تُقبل كنص مجرد أو JSON، على أي ناقل.

أمثلة:

test_danger
{"command":"set_threshold","danger_threshold":40,"warning_threshold":90}

6.3 العتبات

تُنمذَج قيمة المستشعر كـمسافة بالسنتيمتر — الأصغر يعني الأقرب يعني الأسوأ. قراءة أدنى من warning_threshold (الافتراضي 100) ترفع WARNING؛ وأدنى من danger_threshold (الافتراضي 50) ترفع DANGER. يرفض set_threshold أي زوج لا يكون فيه warning أعلى بصرامة من danger أو يخرج عن النطاق الصالح [0, 200]. لا تُحفظ العتبات — تُعيد إعادة التشغيل القيمَ الافتراضية المُترجَمة.

6.4 أوامر Bluetooth LE

1. امسح بحثًا عن 5Tech-IoT-Bridge-…، أو رشّح على UUID الخدمة 4fafc201-1fb5-459e-8fcc-c5c9c331914b (أكثر موثوقية — الاسم في استجابة المسح).
2. اتصل ووسّع الخدمة المخصَّصة.
3. فعّل الإشعارات على الخاصية Resp قبل الكتابة إلى Cmd. الردود على Resp غير مشترَك فيه تُسقَط — وهذا أشيع سبب لـ "لا استجابة".
4. اكتب أمرًا كنص UTF-8 (مثل test_danger) إلى Cmd. تصل الردود كإشعارات على Resp، بالشكل OK <cmd>: <message> أو ERR <cmd>: <message>.
5. اكتب 0x01 (بايت خام، وليس النص "1") إلى Con1 لرفع GPIO23 إلى المرتفع؛ و0x00 يخفضه.

6.5 تحديث البرنامج الثابت

حمّل وميضيًا عبر USB (§5.2). لا يوجد OTA ولا تحديث عبر BLE في المرحلة الأولى.

---

7. الصيانة

الـ Edge Bridge برنامج ثابت على لوحة تطوير؛ ولا توجد مهام صيانة فيزيائية مجدوَلة. تعني "الصيانة" هنا الحفاظ على سلامة البرنامج الثابت وتهيئته.

الشكل FIG-005 — نقاط الاهتمام الروتيني: وصلة USB وملف secrets ومجموعات الاختبارات المؤتمَتة.

---

8. استكشاف الأعطال وإصلاحها

إذا استمر عطل، التقِط السجل التسلسلي وخرج status / config ورسائل الوسيط، ثم راجِع وثائق الهندسة في modules/5tech-edge-iot-bridge/.

---

9. المواصفات

هذا الدليل لا يكرّر قيم المواصفات. جميع مواصفات لوحة التطوير والواجهات والكهرباء والبيئة تُحفظ في ورقة البيانات:

• ورقة البيانات: datasheets/esp32-edge-bridge-datasheet/document.md

---

10. الضمان والدعم

الضمان. هذا MVP للمرحلة الأولى / نموذج أولي للتطوير، مُقدَّم كما هو للتقييم والعرض التوضيحي. لا يحمل أي ضمان منتج تجاري ولا اعتماد. شروط ضمان الإنتاج هي [TBD] وتخصّ المرحلة الثانية.

الدعم.

• 5Tech — فانكوفر، بريتيش كولومبيا، كندا
• البريد الإلكتروني: info@5tech.ca
• الويب: https://5tech.ca

عند التواصل مع الدعم، جهّز: طراز البرنامج الثابت وإصداره، ومعرّف الجهاز (5tech-bridge-…)، والسجل التسلسلي، ورسائل الوسيط حول المشكلة.

إشعار — ليس جهاز سلامة. لا تنشر هذا النموذج الأولي في أي دور قد يؤذي فيه الفشلُ الأشخاصَ أو المعدات. إنه MVP للمراقبة والأتمتة، لا أكثر. (تنويه بشأن النطاق — إشعار وفق §1.1، وليس تحذيرًا من خطر بشأن الجهاز نفسه.)

---

الأشكال

---

هذا الدليل أولي وقابل للتغيير. انظر revision.md للتحكم في التغيير، وreferences.md للمصادر، وimage_prompts.md لفهرس الأشكال/المطالبات.