📡 تثبيت ESPHome — أداة بناء فيرموير لـ ESP32 وESP8266

انشر ESPHome على Ubuntu — لوحة تحكم ويب تحوّل ملفات YAML البسيطة إلى فيرموير مخصص لأجهزة ESP32 وESP8266، وتُحدّثها لاسلكياً وتدمجها مع Home Assistant.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — أمر واحد ينشر لوحة تحكم ESPHome على المنفذ 6052 مع وحدة تخزين إعدادات دائمة.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/esphome/esphome-ubuntu.sh
chmod +x esphome-ubuntu.sh
sudo bash esphome-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/iot/esphome/esphome-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x esphome-ubuntu.sh

3 تشغيل المثبّت

يثبّت السكريبت Docker إن لزم الأمر، يسحب صورة ghcr.io/esphome/esphome، ويشغّل لوحة التحكم على المنفذ 6052 مع وحدة تخزين دائمة ./config تحتفظ بملفات YAML لأجهزتك.

sudo bash esphome-ubuntu.sh

4 فتح لوحة التحكم

افتح المتصفح وانتقل إلى لوحة تحكم ESPHome، ثم أنشئ إعدادات جهازك الأول:

http://<your-server-ip>:6052

المنافذ المستخدمة

المنفذالغرض
6052ESPHome dashboard (edit, compile, OTA flash)

نظرة عامة

يحوّل ESPHome لوحات ESP32 وESP8266 الدقيقة إلى أجهزة منزل ذكي دون كتابة C++ يدوياً. تصف الجهاز — حساساته ومفاتيحه وشاشاته وسلوكه — في ملف YAML قصير وسهل القراءة، وتقوم لوحة تحكم ESPHome بتجميع ذلك إلى صورة فيرموير مخصصة كاملة، تُثبّتها على اللوحة، ثم يظهر الجهاز تلقائياً في Home Assistant مع كل كياناته جاهزة للاستخدام. إنه يسدّ الفجوة بين تطوير فيرموير خام للمتحكمات الدقيقة ومنصة منزل ذكي بالنقر والاختيار.

لماذا تستخدمه

يُلغي ESPHome الحاجة لكتابة وصيانة فيرموير C++ مخصص لكل مشروع ESP32 أو ESP8266 تبنيه. بضعة أسطر YAML تصف حساساً أو مرحّلاً تُنتج صورة فيرموير كاملة وفعالة، والتحديثات بعد أول تثبيت تحدث لاسلكياً. لمن يبني عتاد منزل ذكي مخصص — حساسات، مفاتيح، شاشات، وحدات تحكم ري — بدلاً من شراء أجهزة IoT تجارية تتصل بسحابة المُصنّع، يمنحك ESPHome تحكماً محلياً كاملاً مع تكامل أصلي مع Home Assistant يُكتشف تلقائياً.

متى تحتاجه

  • تبني حساسات أو مُشغّلات منزل ذكي مخصصة من لوحات ESP32/ESP8266 رخيصة بدلاً من شراء أجهزة IoT تجارية
  • تريد أجهزة تندمج أصلياً مع Home Assistant دون سحابة أو تطبيق أو حساب من مُصنّع
  • تحتاج تثبيت وإدارة فيرموير للعديد من أجهزة المتحكمات الدقيقة دون صيانة C++ منفصلة لكل واحد
  • تريد تحديثات فيرموير لاسلكية حتى لا تحتاج الوصول الفعلي لكل جهاز بعد أول تثبيت
  • تُجرّب أو تُصلح مشاريع إلكترونيات مصنوعة يدوياً (ري، مراقبة بيئية، مفاتيح مخصصة) وتريد طريقاً سريعاً من الفكرة إلى فيرموير يعمل

من يحتاجه

  • مستخدمو Home Assistant الذين يريدون عتاداً مخصصاً يندمج أصلياً دون اعتماد على سحابة
  • بناة الإلكترونيات الهواة الذين يعملون بلوحات ESP32/ESP8266 والحساسات والمرحّلات والشاشات
  • عشاق المنزل الذكي المصنوع يدوياً الذين يستبدلون أجهزة IoT التجارية بعتاد مخصص أرخص ومحلي بالكامل
  • الصنّاع الذين يريدون تجنب كتابة وتصحيح فيرموير Arduino/C++ خام لكل مشروع صغير
  • من يُحدّث أجهزة أو مفاتيح حائط قديمة بتحكم ذكي مخصص عبر لوحات مرحّلات
  • بناة الأتمتة صغيرة النطاق (بيوت زجاجية، ري، ورش) الذين يحتاجون حساسات ومفاتيح موثوقة ومتحكم بها محلياً

حالات الاستخدام الشائعة

  • بناء حساس حرارة ورطوبة مخصص من لوحة ESP8266 رخيصة وحساس DHT22
  • تثبيت فيرموير على وحدة مرحّل للتحكم بأبواب الجراج أو صمامات الري أو تركيبات إضاءة موجودة
  • إنشاء شاشة e-ink أو OLED مخصصة تُظهر بيانات حساسات Home Assistant أو لوحات معلومات
  • تحديث جهاز أو مفتاح حائط موجود بأتمتة ذكية يُتحكم بها محلياً
  • بناء عقدة حساس حضور أو حركة تُغذّي أتمتة Home Assistant مباشرة
  • نشر شبكة حساسات بيئية حول المنزل أو البيت الزجاجي دون أي اعتماد على السحابة

الميزات الرئيسية

  • إعداد أجهزة قائم على YAML — صِف الحساسات والمفاتيح والسلوك بشكل تصريحي بدلاً من كتابة C++
  • تكامل أصلي مع واجهة برمجة Home Assistant مع اكتشاف تلقائي للأجهزة والكيانات، دون الحاجة لوسيط MQTT
  • تحديثات فيرموير لاسلكية (OTA) بعد أول تثبيت عبر USB، فلا تحتاج الوصول الفعلي للأجهزة مرة أخرى
  • لوحة تحكم ويب لإنشاء وتحرير وتجميع وتثبيت إعدادات الأجهزة من المتصفح
  • دعم عتاد واسع يشمل ESP32 وESP8266 وRP2040 وعائلات متحكمات دقيقة شائعة أخرى
  • مكتبة مكوّنات مدمجة كبيرة تغطي الحساسات والشاشات والمرحّلات والملحقات الشائعة جاهزة
  • دعم MQTT اختياري للتكامل مع وسطاء ومنصات أخرى غير Home Assistant
  • اتصال واجهة برمجة أصلي مشفّر بين الأجهزة وHome Assistant لتحكم محلي آمن

كيفية الاستخدام بعد التثبيت

  • افتح لوحة تحكم ESPHome وأنشئ إعدادات جهاز جديد، محدداً نوع لوحتك (ESP32 وESP8266 وغيرها)
  • أضف الحساسات أو المفاتيح أو الملحقات التي تحتاجها إلى YAML باستخدام مكتبة مكوّنات ESPHome المدمجة
  • وصّل اللوحة عبر USB للتثبيت الأول — التحديثات اللاسلكية تعمل فقط بعد تثبيت الفيرموير الأولي
  • جمّع وثبّت الفيرموير من لوحة التحكم، ثم تحقق من إقلاع الجهاز واتصاله بشبكة Wi-Fi
  • أضف مفتاح تشفير واجهة برمجة الجهاز إلى Home Assistant حتى يُكتشف تلقائياً مع كل كياناته
  • ادفع تغييرات الإعدادات المستقبلية لاسلكياً باستخدام تحديثات OTA مباشرة من لوحة التحكم
  • نظّم ملفات YAML لأجهزة متعددة باستخدام packages/includes مشتركة لتجنب تكرار الإعدادات الشائعة
  • اضبط عناوين IP ثابتة أو حل mDNS موثوق للأجهزة التي تعتمد عليها في تحديثات OTA والأتمتة

أفضل ممارسات الأمان

  • لا تكشف المنفذ 6052 للإنترنت أبداً — أي شخص يصل للوحة التحكم يمكنه تجميع وتثبيت فيرموير على أجهزتك
  • قيّد لوحة التحكم على شبكتك المحلية عبر ufw أو جدار الحماية، أو ضعها خلف VPN للوصول عن بُعد
  • فعّل مفاتيح تشفير واجهة البرمجة لكل جهاز حتى يكون اتصال Home Assistant مشفراً بدلاً من نص عادي
  • استخدم بيانات اعتماد Wi-Fi قوية وفريدة في إعدادات الأجهزة وتجنب رفعها إلى مستودعات مشتركة أو عامة
  • احفظ ملفات YAML للأجهزة وملف secrets.yaml بعناية — غالباً تحتوي كلمات مرور Wi-Fi ومفاتيح واجهة البرمجة
  • أبقِ ESPHome وفيرموير الأجهزة محدّثاً للحصول على إصلاحات أمنية في مكدس الشبكات وOTA
  • افصل أجهزة IoT على VLAN منفصلة إذا كان جهاز التوجيه يدعم ذلك، لتقييد وصولها لبقية شبكتك

المنافذ وإعدادات جدار الحماية

تستمع لوحة تحكم ESPHome على المنفذ 6052 لواجهة الويب حيث تُنشئ وتُجمّع وتُثبّت إعدادات الأجهزة. يجب ألا يُكشف هذا المنفذ للإنترنت العام أبداً — أي شخص يصل إليه يستطيع دفع فيرموير عشوائي لأجهزتك المتصلة، لذا أبقه مقيداً على شبكتك المحلية عبر ufw أو جدار الحماية السحابي، واستخدم VPN إذا احتجت وصولاً عن بُعد. لكي تعمل التحديثات اللاسلكية واكتشاف الأجهزة، يحتاج ESPHome عادة شبكة المضيف (--net=host على Linux) حتى تصل بثات mDNS لأجهزة ESP32/ESP8266 على الشبكة المحلية؛ بدونها، قد تحتاج للإشارة للأجهزة بعنوان IP ثابت بدلاً من اسمها .local. تعرض أجهزة ESPHome الفردية أيضاً منفذ واجهة برمجة أصلي خاص بها (افتراضياً 6053) للتواصل مع Home Assistant، ويجب أن يبقى هو الآخر على شبكتك المحلية الموثوقة.

النسخ الاحتياطي والصيانة

  • انسخ دليل ./config احتياطياً، الذي يحتفظ بملف إعدادات YAML لكل جهاز — إنه مصدر الحقيقة الكامل لأسطولك
  • انسخ ملف secrets.yaml احتياطياً بشكل منفصل وآمن لأنه يحتوي كلمات مرور Wi-Fi ومفاتيح تشفير واجهة البرمجة
  • احتفظ بملفات YAML للأجهزة في نظام تحكم بالإصدارات مثل Git لتتبع التغييرات والتراجع عن الإعدادات الخاطئة بسهولة
  • وثّق أي جهاز فعلي يتوافق مع أي ملف YAML وعنوان MAC، خاصة كلما زاد عدد أجهزتك
  • دوّن كلمة مرور OTA ومفتاح تشفير واجهة البرمجة لكل جهاز خارج لوحة التحكم في حال فُقدت وحدة تخزين الإعدادات
  • اختبر الاستعادة بإعادة إنشاء حاوية ESPHome بنسخة من دليل ./config والتأكد من ظهور كل الأجهزة مجدداً

الأخطاء الشائعة

  • كشف المنفذ 6052 للإنترنت — أي شخص يصل إليه يستطيع تثبيت فيرموير عشوائي على كل جهاز متصل
  • فقدان مفتاح تشفير واجهة البرمجة أو كلمة مرور OTA لجهاز، مما يتطلب إعادة تثبيت كاملة عبر USB لاستعادة الوصول اللاسلكي
  • تخطي شبكة المضيف على حاوية لوحة التحكم، ثم التساؤل لماذا لا تعمل تحديثات OTA واكتشاف mDNS
  • كتابة بيانات اعتماد Wi-Fi مباشرة في YAML الجهاز بدلاً من استخدام secrets.yaml، مما يُعقّد مشاركة الإعدادات والنسخ الاحتياطي
  • عدم نسخ دليل ./config احتياطياً، وفقدان ساعات من عمل إعدادات YAML إذا أُعيد بناء المضيف أو الحاوية
  • افتراض أن كل تغيير إعدادات يمكن دفعه عبر OTA — بعض التغييرات منخفضة المستوى لا تزال تتطلب إعادة تثبيت فعلي عبر USB
  • تجاهل عنوان IP ثابت أو حجز DHCP للأجهزة، مما يسبب اتصالاً متقطعاً بـ Home Assistant عند تغيّر عناوين IP

استكشاف الأخطاء وإصلاحها

  • لوحة التحكم لا تجد الأجهزة للتحديث اللاسلكي — عادة مشكلة mDNS؛ شغّل الحاوية بشبكة المضيف أو اضبط عنوان IP ثابتاً في إعدادات الجهاز
  • الجهاز لا يتصل بـ Wi-Fi بعد التثبيت — تحقق مرة أخرى من SSID وكلمة المرور في YAML وتأكد أن اللوحة تدعم نطاق Wi-Fi المُعدّ
  • Home Assistant لا يكتشف الجهاز تلقائياً — تأكد أن تكامل ESPHome مثبّت في Home Assistant وأن مفتاح تشفير واجهة البرمجة متطابق
  • التجميع يفشل في لوحة التحكم — تحقق من صيغة YAML وأسماء المكوّنات مقابل توثيق ESPHome للإصدار المثبّت
  • تثبيت OTA يفشل في المنتصف — تأكد أن الجهاز لديه اتصال Wi-Fi مستقر ولا يفقد الطاقة أثناء التثبيت
  • قراءات الحساسات مفقودة أو خاطئة — تحقق من التوصيلات وتعيينات دبابيس GPIO في YAML واستخدام مكوّن الحساس الصحيح
  • التثبيت الأول عبر USB غير مكتشف — تحقق أن كابل USB يدعم نقل البيانات (وليس الطاقة فقط) وأن المنفذ التسلسلي الصحيح مُحدد

البدائل

Tasmota هو الفيرموير المفتوح المصدر الرئيسي الآخر للأجهزة الذكية القائمة على ESP، وشائع في تثبيته مسبقاً على العديد من المقابس والمفاتيح الذكية التجارية — يُعدّ عبر واجهة ويب بدلاً من YAML ويتكامل مع Home Assistant بشكل أساسي عبر MQTT بدلاً من واجهة برمجة أصلية مشفرة. ESPEasy بديل أقدم وأخف يستهدف عقد حساسات بسيطة بواجهة إعداد ويب أساسية أكثر. WLED فيرموير متخصص يركز بالكامل على شرائط LED القابلة للعنونة بدلاً من بناء أجهزة عام الغرض. للفرق المرتاحة لكتابة فيرموير خام، يمنح Arduino العادي أو ESP-IDF مع PlatformIO تحكماً كاملاً منخفض المستوى لكن يتطلب كتابة وصيانة C++ حقيقي بدلاً من YAML تصريحي. لمعظم مستخدمي Home Assistant الذين يبنون حساسات ومفاتيح مخصصة، يبقى سير عمل YAML والتكامل الأصلي في ESPHome الخيار الأكثر إنتاجية.

متى لا تستخدمه

ESPHome ليس الأداة المناسبة إذا كنت تثبّت فيرموير على أجهزة ذكية تجارية جاهزة تعمل بفيرموير متوافق مع Tasmota وتريد تحديداً تحكماً يعتمد على MQTT أولاً — قد يناسب Tasmota إعدادك الحالي بشكل أفضل. إذا احتجت تحكماً منخفض المستوى دقيقاً جداً يتجاوز ما يكشفه نموذج مكوّنات ESPHome — بروتوكولات مخصصة، متطلبات توقيت غير معتادة، أو عتاد لا يدعمه ESPHome — فإن كتابة فيرموير خام بإطار عمل Arduino أو ESP-IDF مباشرة هو الطريق الأفضل. وإذا كنت لا تشغّل Home Assistant ولا تهتم بـ MQTT أيضاً، تختفي ميزة التكامل الرئيسية لـ ESPHome، رغم أن سير عمل YAML إلى فيرموير يبقى مفيداً بحد ذاته.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

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

ما هو ESPHome وماذا يفعل؟

يحوّل ESPHome لوحات ESP32 وESP8266 إلى أجهزة منزل ذكي دون كتابة C++. تصف الجهاز في ملف YAML قصير ويقوم ESPHome بتجميعه إلى فيرموير مخصص، وتثبيته، ويظهر الجهاز تلقائياً في Home Assistant.

هل أحتاج تثبيت الأجهزة عبر USB في كل مرة؟

فقط في المرة الأولى. يجب أن يكون التثبيت الأولي عبر USB لوضع فيرموير ESPHome على اللوحة. بعد ذلك، يدعم الفيرموير التحديثات اللاسلكية، فتستطيع دفع إعدادات جديدة لاسلكياً من لوحة التحكم.

ما المنفذ الذي تستخدمه لوحة تحكم ESPHome؟

المنفذ 6052. تصل للوحة التحكم عبر http://your-server-ip:6052 لإنشاء إعدادات الأجهزة وتجميع الفيرموير وتشغيل تثبيتات OTA. لا تكشف هذا المنفذ للإنترنت أبداً، لأن أي شخص يصل إليه يستطيع تثبيت فيرموير على أجهزتك.

لماذا لا يجد ESPHome جهازي لتحديث OTA؟

هذه عادة مشكلة mDNS. مع شبكة الجسر الافتراضية في Docker، قد لا تصل بثات mDNS إلى الحاوية. شغّل ESPHome بشبكة المضيف، أو أشِر لكل جهاز بعنوان IP الثابت الخاص به في الإعدادات.

هل يتطلب ESPHome وجود Home Assistant؟

لا، لكنهما مصمّمان للعمل معاً. تتكامل واجهة برمجة ESPHome الأصلية مع Home Assistant حتى تُكتشف الأجهزة تلقائياً. إذا كنت لا تشغّل Home Assistant، يمكنك تفعيل MQTT في YAML الجهاز والنشر لأي وسيط MQTT.