espectre snapshot-dev
ESPectre - نظام كشف الحركة يعتمد على تحليل طيف Wi-Fi (CSI)، مع تكامل Home Assistant.
ESPectre 
حوّل ESP32 إلى مستشعر حركة Wi-Fi محلي وخاص.
عندما يتحرك شخص ما عبر غرفة، فإنه يغيّر الطريقة التي تنتقل بها إشارات Wi-Fi عبرها. يقرأ ESPectre هذه التغييرات ويبلغ عن الحركة في الوقت الفعلي. لا كاميرا، ولا ميكروفون، ولا جهاز قابل للارتداء، ولا أجهزة رادار مخصصة: فقط ESP32 مدعوم وشبكة Wi-Fi الموجودة بالفعل في الغرفة.
ESPectre هو منصة مفتوحة المصدر تجمع بين برنامج ثابت جاهز للوميض، وSDK مدمج بلغة C++، وتنفيذ MicroPython، وأدوات متصفح، وCLI للمضيف، ومجموعة بيانات مفتوحة، وأوزان نماذج مفتوحة، وسير عمل البحث المستخدم لبناء والتحقق من صحة أجهزة الكشف.
وميض من متصفحك · شاهد الأدوات المباشرة · اقرأ التوثيق · استكشف SDK
التطبيقات والتكاملات
يمكن لـ ESPectre تشغيل شاشة أو أضواء عند اكتشاف الحركة، وضبط التدفئة والتبريد استجابةً لنشاط الغرفة، وتشغيل إنذار أو إشعار عند حدوث حركة في منطقة يفترض أن تكون فارغة، وقيادة أتمتة غرف أخرى. يتصل بـ Home Assistant عبر ESPHome أو MQTT، ويكشف عن مستشعر إشغال قياسي Matter وواجهة برمجة تطبيقات HTTP مباشرة محلية، ويمكن دمجه في برنامج ESP32 مخصص عبر SDK بلغة C++.
يعالج ESPectre CSI على الجهاز ويبلغ عن حالة حركة ودرجة حركة. يمكن للتطبيقات التفاعل دون إرسال بيانات الاستشعار الخام إلى خدمة سحابية. تغطي لوحة واحدة منطقة استشعار واحدة؛ وعادةً ما يتطلب تغطية على مستوى الغرفة لوحة واحدة لكل غرفة.
يكتشف ESPectre التغييرات في البيئة الراديوية. لا يحدد الأشخاص، ولا يعدّهم، ولا يثبت أن الغرفة فارغة، ولا يحل محل نظام أمني أو طبي أو طوارئ معتمد للسلامة.
الأجهزة المدعومة
- ESP32-C6 وESP32-C5 وESP32-C3 وESP32-S3 وESP32-S2 وESP32 الكلاسيكي
- شبكة Wi-Fi 4 (802.11n) عادية على 2.4 جيجاهرتز
اختر مسار البرنامج الثابت
| المسار | الأفضل لـ | ابدأ من هنا |
|---|---|---|
| Native | المستشعرات المستقلة، وتكاملات MQTT، بما في ذلك Home Assistant MQTT Discovery، والتطبيقات المخصصة | واجهة Native الأمامية |
| ESPHome | مستخدمو Home Assistant الذين يريدون كيانات أصلية، وتوفير ESPHome، وتحديثات Device Builder | واجهة ESPHome الأمامية |
| Matter | وحدات تحكم Matter مع دعم مستشعر الإشغال؛ التحقق من صحة وحدة التحكم لا يزال محدودًا | واجهة Matter الأمامية |
| Micro-ESPectre | استشعار خفيف الوزن في MicroPython مع مراقبة HTTP مباشرة محلية للقراءة فقط | README الخاص بـ Micro-ESPectre |
يمكن لـ Native وESPHome وMatter الاختيار بين كاشف lightweight، الذي يتعلم عتبة خاصة بالغرفة عند بدء التشغيل ويترك موارد أكثر لبقية التطبيق، وكاشف high_accuracy، الذي يشغّل النموذج المدرب المضمّن في المستودع. سلوكهما والمقايضات المقاسة موثقة في SETUP.md وALGORITHMS.md وتقرير الأداء.
بدء سريع
أسرع مسار يستخدم المتصفح ولا يتطلب بيئة بناء محلية. استخدم Chrome 151 لسطح المكتب أو أحدث لسير العمل الكامل المستضاف. يدعم Edge وميض المتصفح، لكن التوافق مع إعدادات الجهاز وMonitor غير مضمون:
- افتح Flash في Chrome أو Edge لسطح المكتب.
- قم بتوصيل ESP32 مدعوم عبر USB، ثم اختر برنامجًا ثابتًا وقناة إصدار.
- أكمل توفير Wi-Fi على الشاشة، أو قم بتفويض Matter مع وحدة تحكم مدعومة.
- اختياريًا، افتح إعدادات الجهاز لتثبيت نقطة وصول مفضلة أو إعداد MQTT.
- افتح Monitor لمشاهدة الحركة وضبط الكشف وفحص الجهاز.
حالة Matter: لا تزال واجهة Matter الأمامية قيد التحقق عبر أنظمة وحدة التحكم. قد تدعم وحدة التحكم مستشعرات إشغال Matter القياسية دون أن يتم اختبارها مع البرنامج الثابت الحالي. راجع توافق وحدة تحكم Matter للمصفوفة الحالية.
الإعداد المحلي
للبناء المحلي، والوميض من هذا المستودع، وبقية مسار المشغّل، ابدأ بـ SETUP.md. يكشف غلاف المستودع عن سير العمل المتاح عبر:
./espectre --help
التوثيق
| الموضوع | ما يغطيه | الأدلة |
|---|---|---|
| التثبيت والتشغيل | إعداد الجهاز، وسير عمل CLI، وضبط الكاشف | SETUP.md، CLI.md، TUNING.md |
| الفهم والتكامل | بنية وقت التشغيل، وAPI، والاكتشاف، والخوارزميات، وSDK بلغة C++ | ARCHITECTURE.md، API.md، DISCOVERY.md، ALGORITHMS.md، SDK.md |
| الجمع والتدريب | جمع CSI، وتدريب النموذج، وسجل الميزات، والأداء، والأدبيات | ML_DATA_COLLECTION.md، ML_TRAINING.md، FEATURES.md، تقرير الأداء، LITERATURE.md |
| البحث والاتجاه | خارطة الطريق، وقرارات البنية، وسجل الإصدارات | ROADMAP.md، فهرس ADR، CHANGELOG.md |
| مرجع الواجهة الأمامية | ملفات README لمسار البرنامج الثابت لـ ESPHome وNative وMatter وMicro-ESPectre | ESPHome، Native، Matter، Micro |
| المساهمة | كيفية المساهمة وأين تناقش المشروع | CONTRIBUTING.md، مناقشات GitHub |
مجموعات البيانات والنماذج والتحقق
ينشر ESPectre أصول البحث وأدلة التحقق وراء أجهزة الكشف الخاصة به:
| الأصل | ما يقدمه لك | ابدأ من هنا |
|---|---|---|
| مجموعة بيانات CSI | تسجيلات حقيقية للغرف الفارغة والحضور الثابت والحركة، مع كتالوج ومصدر في dataset_info.json | data/ |
| أوزان النماذج | أوزان مدربة في C++ وPython، بالإضافة إلى سير عمل التدريب والتصدير والتحقق | ML_TRAINING.md |
| سجل الميزات | الميزات التي تم اختبارها أو ترقيتها أو رفضها، بما في ذلك التجارب غير الناجحة | FEATURES.md |
| الخوارزميات والتقارير | سلوك الكاشف، وتقرير الأداء المُنشأ، وتقرير جودة مجموعة البيانات | ALGORITHMS.md |
| الأدبيات والاتجاه | البحث الخارجي، وسجلات قرارات البنية، وخارطة الطريق العامة | LITERATURE.md |
الأمان والخصوصية والشفافية
لا ينبغي أن يكون المستشعر الذي يمكنه الكشف عن الحضور صندوقًا أسود. يتجنب استشعار Wi-Fi الصور والصوت، لكن بيانات الحركة والإشغال لا تزال قادرة على كشف الروتين أو النوم أو الغياب عن المنزل. يعامل ESPectre هذا الخطر كجزء من العمل الهندسي:
- اكتشاف الحركة محلي، والاتصال السحابي غير مطلوب؛
- جمع CSI الخام اختياري ومخصص لاحتياجات البحث وتصحيح الأخطاء المحددة؛
- يوثق دليل الأمان والاستخدام المسؤول حدود النشر والموافقة وتقليل البيانات والإبلاغ عن سوء الاستخدام والإبلاغ الخاص عن الثغرات؛
- تتضمن إصدارات البرنامج الثابت قوائم مواد برمجية (SBOMs) خاصة بالبناء وإشعارات وأرشيفات تراخيص بحيث يمكن فحص محتوياتها؛
- الموقع العام وكل أداة متصفح جزء من هذا المستودع تحت docs/web، بما في ذلك مصدرها وقواعد الخصوصية وعقد التحليلات وتبعيات المتصفح المثبتة؛
- البروتوكولات والخوارزميات وأدلة الأداء والقيود وقرارات خارطة الطريق وحدود التحقق المعروفة موثقة علنًا.
استخدم ESPectre فقط في المساحات والشبكات التي يحق لك النشر فيها. أبلغ الأشخاص المتأثرين، واحصل على الموافقة حيثما كان ذلك مطلوبًا، واحمِ الوصول إلى الجهاز وبياناته، واتبع قوانين الخصوصية المعمول بها.
الإقرارات
- شكرًا لـ Espressif لجعل CSI متاحًا في ESP-IDF وللاعتراف بـ ESPectre كمشروع مجتمعي في esp-csi.
- شكرًا لمشرفي MicroPython لمراجعة واختبار ودمج مساهمة CSI الخاصة بـ ESPectre، التي أضافت طرق CSI مباشرة إلى
network.WLANالرئيسي.
الترخيص
كود ESPectre من الطرف الأول متاح بموجب GPLv3، والأجزاء المؤهلة متاحة أيضًا بموجب اتفاقية تجارية منفصلة:
- اختر GPLv3 عندما يمكن لبرنامجك الثابت أو تطبيقك الامتثال لـ GPLv3، بما في ذلك توفير المصدر المقابل. راجع LICENSE.
- إذا كنت تريد دمج ESPectre في برنامج ثابت مملوك أو مغلق المصدر دون التزامات الكشف عن المصدر بموجب GPLv3، فراجع LICENSING.md للترخيص التجاري. يغطي الترخيص التجاري المواد المؤهلة ولا يحل محل شروط الطرف الثالث؛ تظل واجهة ESPHome الأمامية بلغة C++ مقتصرة على GPLv3 فقط.
شروط الطرف الثالث وأصول الامتثال الخاصة بالبناء موصوفة في THIRD_PARTY_NOTICES.md.