الإلكترونيات والطائرات المسيرة والطباعة ثلاثية الأبعاد الأدلة التقنية

مشروع مراقبة حرارة الغرفة ورطوبتها

جهاز ESP32 مع الحساس SHT31 يقيس الغرفة كل دقيقة، وينبهك على الجوال عندما تبقى الرطوبة عالية، ويعرف نفسه لـ Home Assistant، ولا ينشر رقماً قديماً إذا تعطل حساسه.

مشروع مراقبة حرارة الغرفة ورطوبتها

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

وفي مشروع ري النباتات قرأنا حساساً تماثلياً بالمحول ADC وشغلنا مضخة، وفي هذا المشروع لا يوجد مخرج نتحكم فيه، وإنما حساس رقمي واحد على ناقل I2C، والتحدي هنا مختلف: أن تكون القراءة صحيحة، وأن تكون في المكان الصحيح، وأن يعرف النظام كله متى لا يجب أن يصدق الرقم. وسوف نبني المشروع كاملاً: البرنامج الثابت Firmware على ESP32 مع الحساس SHT31، ثم الوسيط Mosquitto، ثم خدمة تحفظ القراءات وتطبق قاعدة خطر العفن، ثم تنبيهات على الجوال، ونجعل الجهاز يعرف نفسه لـ Home Assistant تلقائياً، ونشغل ذلك كله على جهازك بالمحاكي QEMU.

وسوف نناقش في هذا المقال ما يلي:

  • ماذا نقيس: الحرارة والرطوبة النسبية ونقطة الندى، ولماذا نهتم بالرطوبة فوق 60%.
  • اختيار الحساس: من المقياس التقليدي إلى DHT22 إلى حساسات I2C، ولماذا اخترنا SHT31.
  • التوصيل، ومكان الحساس في الغرفة، وهو نصف دقة المشروع.
  • البرنامج الثابت: قراءة الحساس بأمر واحد، وفحص CRC، وتحويل الأرقام، والتعريف لـ Home Assistant.
  • خدمة الاستقبال وقاعدة العفن مع الهامش Hysteresis، والتنبيهات عبر ntfy.
  • تشغيل المشروع كاملاً، ثم كسره: سلك ينفصل، وماذا يجب أن يحدث عندها.

ماذا نقيس، ولماذا الرطوبة بالذات؟

الحرارة سهلة الفهم، أما الرطوبة النسبية Relative Humidity فهي نسبة بخار الماء الموجود في الهواء إلى أكبر كمية يستطيع الهواء أن يحملها عند الحرارة نفسها. ولاحظ كلمة «عند الحرارة نفسها»، لأن الهواء الدافئ يحمل ماء أكثر من البارد، فالهواء نفسه بكمية الماء نفسها تكون رطوبته النسبية 50% في الغرفة، فإذا لمس زجاج نافذة بارد ارتفعت رطوبته النسبية عند الزجاج حتى تصل إلى 100%، فيتكثف الماء على الزجاج. والحرارة التي يبدأ عندها التكثف تسمى نقطة الندى Dew Point، وهي الرقم الثالث الذي سيحسبه جهازنا من الرقمين الأولين.

والصورة التالية فيها النتيجتان اللتان نريد أن نمنعهما، على اليمين ماء تكثف على زجاج نافذة في غرفة رطبة باردة، وعلى اليسار عفن على جدار:

صورتان: على اليمين نافذة بإطار معدني داكن وعلى زجاجها قطرات ماء كثيرة متكثفة وخطوط سالت منها، وعلى اليسار زاوية جدار أبيض عليها بقع عفن داكنة صغيرة كثيرة
التكثف على زجاج بارد، والعفن على جدار. الصور: Doggo19292 (ملكية عامة، المصدر)، وشي أفيدان (رخصة CC BY-SA 4.0، المصدر)، من Wikimedia Commons (تم جمعها وتحويلها إلى WebP).

وتوصي وكالة حماية البيئة الأمريكية EPA في دليلها عن العفن والرطوبة في المنزل بأن تبقى الرطوبة داخل المنزل أقل من 60%، والأفضل بين 30% و50%. ولهذا تكون القاعدة التي سنبنيها في المشروع: إذا بقيت الرطوبة فوق 65% ثلاثين دقيقة متصلة فأرسل تنبيهاً، ولا تعتبر المشكلة انتهت حتى تنزل الرطوبة تحت 60%. وقد يتساءل البعض: لماذا لا ننبه فور أن تتجاوز الرطوبة 60%؟ والإجابة أن الرطوبة ترتفع دقائق كل مرة تستحم فيها أو تطبخ أو تفتح الباب، وتنبيه على كل ارتفاع قصير يجعلك تتجاهل التنبيهات كلها بعد يومين، والمشكلة الحقيقية هي الرطوبة التي تبقى، وليس التي تمر.

اختيار الحساس

أقدم طريقة لقياس الاثنين جهاز بمؤشرين كالذي في الصورة التالية، وفيه منطقة مظللة يسميها صانعه منطقة الراحة: الحرارة بين 18 و22 درجة، والرطوبة بين 45% و70%:

مقياس حرارة ورطوبة دائري بإطار نحاسي على حائط خشبي، فيه مؤشران أسودان: الأيسر للحرارة بالمئوية من 10 إلى 40، والأيمن للرطوبة من 0 إلى 100، ومنطقة مظللة حيث يتقاطع المؤشران
مقياس حرارة ورطوبة بمؤشرين، والمنطقة المظللة منطقة الراحة. الصورة: Memecry2 (بحسب صفحة الملف)، رخصة CC BY 3.0، المصدر: Wikimedia Commons (تم تحويلها إلى WebP).

وهذا المقياس يجيب عن اللحظة فقط، ولا يحفظ، ولا ينبه، ولا يمكن لبرنامج أن يقرأه، ولهذا نحتاج حساساً إلكترونياً. وأشهر حساس في علب المبتدئين هو DHT22، والصورة التالية له، واسمه المكتوب عليه AM2302:

حساس أبيض مستطيل بفتحات مربعة في وجهه للتهوية، مكتوب عليه AOSONG AM2302 ورقم تسلسلي، وله أربع أرجل معدنية
الحساس DHT22، ويباع أيضاً باسم AM2302. الصورة: Ubahnverleih، رخصة CC0، المصدر: Wikimedia Commons (تم تحويلها إلى WebP).

والحساس DHT22 يعمل، وستجد له مكتبات في كل مكان، ولكنه يتكلم بروتوكولاً خاصاً به على سلك واحد، توقيته بالميكروثانية، فيقرأ المتحكم الصفر والواحد من طول النبضة، وأي تأخير في المتحكم أثناء القراءة يفسدها، كأن تأتي مقاطعة من Wi-Fi في منتصفها. والبديل حساسات تتكلم البروتوكول القياسي I2C الذي شرحناه في مقال البروتوكولات، فيتولى العتاد في المتحكم التوقيت، والصورة التالية لثلاثة منها على لوحات صغيرة جاهزة Breakout Boards:

ثلاث لوحات حمراء صغيرة: على اليمين لوحة BME280 بشريحة معدنية صغيرة وأرجل مكتوب عليها GND و3.3V وSDA وSCL، وفي الوسط لوحة HIH6130 بشريحة سوداء وأرجل SDA وSCL وVDD وGND، وعلى اليسار لوحة Si7021 بشريحة بيضاء صغيرة ومكتوب عليها Humidity and Temp Sensor
ثلاثة حساسات حرارة ورطوبة على I2C، من اليمين: BME280 وHIH6130 وSi7021. الصور: SparkFun، رخص CC BY 2.0 (المصدر والمصدر) وCC BY 2.5 (المصدر)، من Wikimedia Commons (تم جمعها وتحويلها إلى WebP).

ولاحظ أن الأرجل في اللوحات الثلاث تقريباً واحدة: طاقة وأرضي وSDA وSCL، وهذا هو جمال I2C: أربعة أسلاك لأي حساس، وكل حساس له عنوان على الناقل. وفي هذا المشروع اخترنا الحساس SHT31 من Sensirion، ويباع على لوحات صغيرة بالأرجل الأربعة نفسها، واخترناه لأن ورقة بياناته تعطي كل ما نحتاجه بوضوح، والأرقام التالية منها مباشرة، من ورقة بيانات SHT3x (الإصدار 7، ديسمبر 2022):

  • الجهد: من 2.15 إلى 5.5 فولت، فيعمل على 3.3 فولت من ESP32 مباشرة.
  • العنوان: 0x44 إذا كانت الرجل ADDR على الأرضي، و0x45 إذا كانت على الجهد، فتستطيع أن تضع حساسين على الناقل نفسه.
  • الدقة النموذجية Typical: ±2% في الرطوبة، و±0.2 درجة في الحرارة بين 0 و90 درجة، والنسخة الأغلى SHT35 أدق.
  • زمن الاستجابة للرطوبة: 8 ثوان للوصول إلى 63% من أي تغير مفاجئ، عند 25 درجة وهواء يتحرك بسرعة متر في الثانية، أي أن الحساس لا يرى التغير لحظياً.
  • مجال التشغيل الموصى به: من 5 إلى 60 درجة، ومن 20% إلى 80% رطوبة، وتذكر الورقة أن البقاء الطويل خارج هذا المجال، خاصة في الرطوبة العالية، قد يسبب انحرافاً مؤقتاً في القراءة.
  • فحص الأخطاء: كل رقمين يرسلهما الحساس يتبعهما بايت CRC، فيعرف المتحكم إذا وصلت البيانات تالفة.

والنقطة الأخيرة هي التي ستنقذنا في قسم الكسر بعد قليل، فاحفظها.

التوصيل

التوصيل أربعة أسلاك كما في الشكل التالي:

رسم توصيل: على اليمين لوحة ESP32 وعلى اليسار لوحة حساس SHT31 خضراء، وبينهما أربعة أسلاك: أحمر من 3V3 إلى VIN، وأسود من GND إلى GND، وأزرق من GPIO21 إلى SDA، وأصفر من GPIO22 إلى SCL، وتحت الحساس عبارة address 0x44 مع مقاومات رفع على اللوحة، وفي الوسط ملاحظة: سلك قصير والحساس بعيد عن اللوحة، وفي الأسفل: كل قراءة أمر من بايتين 0x24 0x00 ثم انتظار 15.5 ملي ثانية كحد أقصى ثم ست بايتات
توصيل الحساس SHT31 بلوحة ESP32
  • الطاقة والأرضي: من 3V3 وGND في اللوحة، ولا تستخدم 5 فولت حتى لو كان الحساس يقبلها، لأن خطي البيانات سيرتفعان حينها إلى 5 فولت بمقاومات الرفع، وأرجل ESP32 مصممة لـ 3.3 فولت.
  • الخطان SDA وSCL: على الرجلين 21 و22، وهما الرجلان المعتادتان لـ I2C في لوحات ESP32 الشائعة، وتستطيع أن تختار غيرهما لأن الشريحة توجه أي وظيفة إلى أغلب الأرجل.
  • مقاومات الرفع Pull-up: ناقل I2C يحتاج مقاومة ترفع كل خط إلى الجهد، وأغلب لوحات الحساسات تحملها، ولهذا لا نضيف شيئاً، وفي الكود نفعل أيضاً المقاومة الداخلية الضعيفة في المتحكم.
  • طول السلك: I2C صمم للمسافات داخل اللوحة الواحدة، وكلما طال السلك زادت سعته وتشوهت حواف الإشارة، فاجعله عشرات السنتيمترات، وإذا احتجت أمتاراً فهناك شرائح خاصة لتمديد الناقل.

مكان الحساس: نصف الدقة

الحساس دقته ±0.2 درجة، ولكن إذا وضعته في المكان الخطأ فسوف يقيس بدقة ±0.2 درجة شيئاً غير الغرفة. والأماكن الخطأ أشهرها ما يلي:

  • ملتصقاً باللوحة: المتحكم ESP32 ومنظم الجهد يسخنان أثناء العمل، خاصة مع Wi-Fi، فإذا وضعت الحساس فوق اللوحة أو داخل علبة مغلقة معها فسوف يقرأ الحرارة أعلى من الغرفة والرطوبة أقل منها، لأن الهواء نفسه إذا سخن نزلت رطوبته النسبية. ولهذا يكون الحساس على سلك قصير خارج العلبة أو في جزء منفصل منها بفتحات.
  • التسخين الذاتي Self-heating: الحساس نفسه يسخن إذا قاس بسرعة عالية، وتذكر ورقة البيانات أن ذلك قد يحدث في أعلى معدل قياس دوري، وهو 10 قياسات في الثانية. ونحن نقيس مرة واحدة في الدقيقة بأمر القياس المنفرد Single Shot، فيعود الحساس إلى السكون بين القياسات.
  • الشمس والمكيف: شعاع الشمس على الحساس يرفع قراءته بدرجات، وفتحة المكيف تعطيك حرارة الهواء الخارج من المكيف وليس الغرفة. ضعه على جدار داخلي، بعيداً عن النافذة وفتحة المكيف وباب الحمام والمطبخ.
  • دون حماية: الحساس يحتاج أن يلمسه الهواء، ولكن الغبار والرذاذ يضرانه، والصورة التالية لطرف حساس رطوبة من جهاز قياس احترافي، ولاحظ الغطاء الذي بجانبه: فتحات طولية تمرر الهواء وتحمي الحساس من اللمس:
طرف أسطواني أسود لجهاز قياس حرارة ورطوبة نزع غطاؤه، فظهر في طرفه عنصر قياس رفيع أبيض وسلكان رفيعان، وبجانبه غطاء أبيض شفاف بفتحات طولية
طرف حساس حرارة ورطوبة من جهاز قياس، وبجانبه غطاؤه بفتحات التهوية. الصورة: Harke، ملكية عامة، المصدر: Wikimedia Commons (تم تحويلها إلى WebP).

وإذا أردت أن تعرف هل المكان جيد، ضع بجانب الحساس مقياساً آخر ليوم كامل، وقارن الرقمين في الصباح وبعد الظهر، فإذا اختلفا في ساعات الشمس فقط فالمشكلة في المكان وليست في الحساس.

البرنامج الثابت: الحساس

المختبر في مجلد lab، وهو مبني على قالب مشروع ري النباتات نفسه: برنامج ثابت بإطار ESP-IDF، يبنى مرتين، مرة للوحة الحقيقية ومرة للمحاكي QEMU. والمحاكي QEMU من Espressif يشغل شريحة ESP32 حقيقية من ناحية المعالج والذاكرة والشبكة، ولكن لا يوجد على ناقل I2C فيه حساس SHT31، ولهذا قسمنا الكود بحيث يكون الجزء الوحيد المختلف هو العملية على الناقل نفسها: على اللوحة يرسل الأمر ويستقبل ست بايتات من الحساس، وفي المحاكي تأتي البايتات الست من غرفة محاكاة، بالشكل نفسه وبالـ CRC نفسه، وكل ما بعد ذلك كود واحد يعمل في الحالتين. والملف sht31.h كما يلي:

#pragma once
#include "esp_err.h"
// Sensirion SHT31 on I2C (address 0x44 with ADDR to GND). One single-shot measurement:
// command 0x2400 (high repeatability, no clock stretching), wait, read 6 bytes: T MSB, T LSB, CRC, RH MSB, RH LSB, CRC.
typedef enum { SHT_OK = 0, SHT_NACK, SHT_CRC } sht_status_t;
void sht31_init(void);
sht_status_t sht31_measure(float *t_c, float *rh);

#ifdef SENSOR_SIM
#define SCALE 60            // simulated time runs 60x faster: 1 minute of the room = 1 s
#else
#define SCALE 1
#endif

والملف sht31.c فيه الأجزاء الثلاثة: الكود المشترك، ثم كود اللوحة، ثم الغرفة المحاكاة:

#include "sht31.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_timer.h"

#define SHT31_ADDR 0x44

// CRC-8 from the datasheet: polynomial 0x31, init 0xFF, no reflection, no final XOR. CRC(0xBEEF) = 0x92.
static uint8_t crc8(const uint8_t *d, int n) {
    uint8_t c = 0xFF;
    for (int i = 0; i < n; i++) {
        c ^= d[i];
        for (int b = 0; b < 8; b++) c = (c & 0x80) ? (uint8_t)((c << 1) ^ 0x31) : (uint8_t)(c << 1);
    }
    return c;
}

static esp_err_t bus_measure(uint8_t out[6]);   // the only part that differs between the board and QEMU

sht_status_t sht31_measure(float *t_c, float *rh) {
    uint8_t d[6];
    if (bus_measure(d) != ESP_OK) return SHT_NACK;                    // nobody answered at 0x44
    if (crc8(d, 2) != d[2] || crc8(d + 3, 2) != d[5]) return SHT_CRC;   // noise on a long wire
    uint16_t st = (uint16_t)(d[0] << 8 | d[1]), srh = (uint16_t)(d[3] << 8 | d[4]);
    *t_c = -45.0f + 175.0f * st / 65535.0f;                            // datasheet conversion formulas
    *rh = 100.0f * srh / 65535.0f;
    return SHT_OK;
}

#ifndef SENSOR_SIM
#include "driver/i2c_master.h"
static i2c_master_dev_handle_t dev;

void sht31_init(void) {
    i2c_master_bus_config_t bus_cfg = {
        .i2c_port = I2C_NUM_0, .sda_io_num = GPIO_NUM_21, .scl_io_num = GPIO_NUM_22,
        .clk_source = I2C_CLK_SRC_DEFAULT, .glitch_ignore_cnt = 7,
        .flags.enable_internal_pullup = true,     // the breakout boards also carry their own pull-ups
    };
    i2c_master_bus_handle_t bus;
    ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &bus));
    i2c_device_config_t dev_cfg = { .dev_addr_length = I2C_ADDR_BIT_LEN_7, .device_address = SHT31_ADDR,
                                    .scl_speed_hz = 100000 };
    ESP_ERROR_CHECK(i2c_master_bus_add_device(bus, &dev_cfg, &dev));
}

static esp_err_t bus_measure(uint8_t out[6]) {
    const uint8_t cmd[2] = { 0x24, 0x00 };
    esp_err_t e = i2c_master_transmit(dev, cmd, 2, 50);
    if (e != ESP_OK) return e;
    vTaskDelay(pdMS_TO_TICKS(20));                 // high repeatability takes up to 15.5 ms
    return i2c_master_receive(dev, out, 6, 50);
}

#else
#include <math.h>
// Simulated room, in simulated minutes:
//  0-15  24 C, 48 %RH
//  15-25 laundry drying indoors with the door closed: humidity climbs to about 72 %RH
//  25-60 stays around 71-73 %RH
//  60-70 window opened: back down to about 55 %RH
//  75-84 the sensor's SDA wire comes loose: no ACK at 0x44
//  85-   the wire is back
static int64_t t0 = -1;                                     // the room's clock starts at the first measurement
void sht31_init(void) {}
static double minute_now(void) {
    if (t0 < 0) t0 = esp_timer_get_time();
    return (esp_timer_get_time() - t0) * (double)SCALE / 60e6;
}

static esp_err_t bus_measure(uint8_t out[6]) {
    double m = minute_now();
    if (m >= 75 && m < 85) return ESP_ERR_TIMEOUT;           // what a missing device looks like to the caller
    double rh = m < 15 ? 48 : m < 25 ? 48 + (m - 15) * 2.4 : m < 60 ? 72 : m < 70 ? 72 - (m - 60) * 1.7 : 55;
    double t = 24.0 + (m < 60 ? m * 0.03 : 1.8 - (m - 60) * 0.05);
    if (t < 23.5) t = 23.5;
    rh += 0.6 * sin(m * 1.3);  t += 0.05 * sin(m * 0.7);      // a little noise, like a real room
    uint16_t st = (uint16_t)lround((t + 45.0) * 65535.0 / 175.0), srh = (uint16_t)lround(rh * 65535.0 / 100.0);
    out[0] = st >> 8; out[1] = st & 0xFF; out[2] = crc8(out, 2);
    out[3] = srh >> 8; out[4] = srh & 0xFF; out[5] = crc8(out + 3, 2);
    return ESP_OK;
}
#endif

في الكود أعلاه لاحظ التالي:

  • الدالة crc8 مكتوبة من جدول خصائص الـ CRC في ورقة البيانات: كثير الحدود 0x31 والقيمة الابتدائية 0xFF، والورقة تعطي مثالاً تتأكد به من الكود: CRC للبايتين 0xBE 0xEF هو 0x92.
  • الأمر 0x24 0x00 هو القياس المنفرد بأعلى تكرارية High Repeatability ودون إمساك الساعة Clock Stretching، أي أن الحساس لا يمسك خط SCL منخفضاً أثناء القياس، وإنما ننتظر نحن 20 ملي ثانية، والورقة تقول إن القياس يأخذ 15.5 ملي ثانية كحد أقصى. ولو قرأنا قبل أن ينتهي لرد الحساس بعدم إقرار NACK.
  • معادلتا التحويل من الورقة: الحرارة -45 + 175 × ST / 65535، والرطوبة 100 × SRH / 65535، حيث ST وSRH الرقمان الخامان بستة عشر بتاً.
  • الدالة sht31_measure ترجع ثلاث حالات وليس رقمين فقط: نجحت، أو لم يرد أحد، أو وصلت البيانات تالفة، والرقمان لا يكتبان إلا في حالة النجاح. وهذا هو الفرق بين كود يعمل في المختبر وكود يعمل سنة على الحائط.
  • كود اللوحة يستخدم مشغل I2C الجديد في ESP-IDF 5 من الملف driver/i2c_master.h، وهو يبنى في البناء الأول build-hw ولكنه لا يعمل في المحاكي.
  • الغرفة المحاكاة تمر بقصة من 95 دقيقة، والوقت فيها أسرع 60 مرة، فالدقيقة ثانية: رطوبة عادية، ثم غسيل ينشر داخل غرفة مغلقة فترتفع الرطوبة إلى 72%، ثم تفتح النافذة، ثم ينفصل سلك SDA عشر دقائق ويعود.

البرنامج الثابت: القراءة والنشر

والملف main.c يقرأ كل دقيقة، ويحسب نقطة الندى، وينشر، ويعرف الجهاز لـ Home Assistant:

// Room temperature and humidity on an ESP32 with a Sensirion SHT31.
//  - one measurement a minute: temperature, relative humidity, and the dew point computed from both
//  - publishes over MQTT, and announces itself to Home Assistant with MQTT discovery (two sensors, one device)
//  - a failed read is retried once; three failed minutes in a row = sensor fault: it stops publishing values
//    (no stale number that looks fine), marks the sensor unavailable, and says so in an event
#include <stdio.h>
#include <string.h>
#include <math.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"
#include "mqtt_client.h"
#include "protocol_examples_common.h"
#include "sht31.h"

static const char *TAG = "climate";

#define DEVICE      "bedroom-1"
#define BROKER_URI  "mqtt://10.0.2.2:1883"     // under QEMU: the machine running it; on a real board your broker
#define BASE        "home/climate/" DEVICE
#define FAULT_AFTER 3                          // failed minutes in a row before we call it a fault

static esp_mqtt_client_handle_t mq;
static volatile bool connected, sensor_ok = true;

// Home Assistant MQTT discovery: <prefix>/<component>/<node_id>/<object_id>/config. Sent on every connect and
// again when Home Assistant announces itself on homeassistant/status, instead of relying on retained configs.
static void announce(void) {
    static const char *kinds[][4] = {   // object id, device class, unit, JSON key
        { "temperature", "temperature", "\xC2\xB0" "C", "t" },
        { "humidity",    "humidity",    "%",            "rh" },
    };
    for (int i = 0; i < 2; i++) {
        char topic[96], cfg[640];
        snprintf(topic, sizeof topic, "homeassistant/sensor/" DEVICE "/%s/config", kinds[i][0]);
        snprintf(cfg, sizeof cfg,
            "{\"name\":\"%s\",\"device_class\":\"%s\",\"unit_of_measurement\":\"%s\",\"state_class\":\"measurement\","
            "\"state_topic\":\"" BASE "/state\",\"value_template\":\"{{ value_json.%s }}\","
            "\"unique_id\":\"" DEVICE "_%s\","
            "\"availability\":[{\"topic\":\"" BASE "/status\"},{\"topic\":\"" BASE "/sensor\","
            "\"payload_available\":\"ok\",\"payload_not_available\":\"fault\"}],\"availability_mode\":\"all\","
            "\"device\":{\"identifiers\":[\"" DEVICE "\"],\"name\":\"Bedroom climate\",\"model\":\"ESP32 + SHT31\"}}",
            kinds[i][0], kinds[i][1], kinds[i][2], kinds[i][3], kinds[i][0]);
        esp_mqtt_client_publish(mq, topic, cfg, 0, 1, 0);
    }
    ESP_LOGI(TAG, "discovery sent (2 sensors)");
}

static void on_mqtt(void *arg, esp_event_base_t base, int32_t id, void *data) {
    esp_mqtt_event_handle_t e = data;
    if (id == MQTT_EVENT_CONNECTED) {
        ESP_LOGI(TAG, "connected to the broker");
        connected = true;
        esp_mqtt_client_publish(mq, BASE "/status", "online", 0, 1, 1);
        esp_mqtt_client_publish(mq, BASE "/sensor", sensor_ok ? "ok" : "fault", 0, 1, 1);
        esp_mqtt_client_subscribe(mq, "homeassistant/status", 1);
        announce();
    } else if (id == MQTT_EVENT_DISCONNECTED) {
        connected = false;
    } else if (id == MQTT_EVENT_DATA && e->data_len == 6 && memcmp(e->data, "online", 6) == 0) {
        ESP_LOGI(TAG, "Home Assistant restarted: announcing again");
        announce();
    }
}

// Dew point with the Magnus formula (constants 17.62 and 243.12 C, over water)
static float dew_point(float t, float rh) {
    float g = logf(rh / 100.0f) + 17.62f * t / (243.12f + t);
    return 243.12f * g / (17.62f - g);
}

void app_main(void) {
    ESP_ERROR_CHECK(nvs_flash_init());
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    sht31_init();
    ESP_ERROR_CHECK(example_connect());

    esp_mqtt_client_config_t cfg = {
        .broker.address.uri = BROKER_URI,
        .credentials.client_id = "climate-" DEVICE,
        .session.last_will = { .topic = BASE "/status", .msg = "offline", .qos = 1, .retain = 1 },
        .session.keepalive = 30,
    };
    mq = esp_mqtt_client_init(&cfg);
    esp_mqtt_client_register_event(mq, ESP_EVENT_ANY_ID, on_mqtt, NULL);
    esp_mqtt_client_start(mq);
    for (int i = 0; i < 100 && !connected; i++) vTaskDelay(pdMS_TO_TICKS(100));

    int seq = 0, failed = 0;
    for (int minute = 0;; minute++) {
        float t, rh;
        sht_status_t s = sht31_measure(&t, &rh);
        if (s != SHT_OK) {                              // one retry: a single glitch is not a fault
            vTaskDelay(pdMS_TO_TICKS(50));
            s = sht31_measure(&t, &rh);
        }
        if (s == SHT_OK) {
            if (!sensor_ok) {
                ESP_LOGI(TAG, "sensor back after %d failed minutes", failed);
                esp_mqtt_client_publish(mq, BASE "/event", "{\"event\":\"sensor_ok\"}", 0, 1, 0);
                esp_mqtt_client_publish(mq, BASE "/sensor", "ok", 0, 1, 1);
                sensor_ok = true;
            }
            failed = 0;
            char j[128];
            snprintf(j, sizeof j, "{\"seq\":%d,\"min\":%d,\"t\":%.1f,\"rh\":%.1f,\"dew\":%.1f}",
                     seq++, minute, t, rh, dew_point(t, rh));
            if (minute % 5 == 0) ESP_LOGI(TAG, "%s", j);   // the log shows every 5th; MQTT gets every minute
            esp_mqtt_client_publish(mq, BASE "/state", j, 0, 0, 0);
        } else {
            failed++;
            ESP_LOGW(TAG, "minute %d: read failed (%s), %d in a row", minute, s == SHT_NACK ? "no ACK" : "bad CRC", failed);
            if (failed == FAULT_AFTER) {
                char j[96];
                snprintf(j, sizeof j, "{\"event\":\"sensor_fault\",\"error\":\"%s\",\"minutes\":%d}",
                         s == SHT_NACK ? "nack" : "crc", failed);
                esp_mqtt_client_publish(mq, BASE "/event", j, 0, 1, 0);
                esp_mqtt_client_publish(mq, BASE "/sensor", "fault", 0, 1, 1);
                sensor_ok = false;
                ESP_LOGE(TAG, "%s", j);
            }
        }
        vTaskDelay(pdMS_TO_TICKS(60000 / SCALE));
    }
}

في الكود أعلاه لاحظ التالي:

  • نقطة الندى بمعادلة Magnus بالثابتين 17.62 و243.12، وهي تقريب معروف يكفي لغرفة، ونحسبها في الجهاز لكي يجدها كل من يقرأ الرسالة جاهزة.
  • إعادة المحاولة مرة واحدة: قراءة فاشلة واحدة قد تكون تشويشاً لحظياً، فنعيد بعد 50 ملي ثانية. وإذا فشلت ثلاث دقائق متتالية نعتبره عطلاً، فنرسل حدث sensor_fault وننشر fault على الموضوع sensor.
  • لا ننشر رقماً قديماً: في دقائق الفشل لا يرسل الجهاز أي قراءة، ولا يعيد آخر رقم نجح. وسنرى في قسم الكسر لماذا هذا مهم.
  • موضوعان للتوفر Availability: الموضوع status يقول هل الجهاز متصل، وتكتب فيه الوصية Last Will كلمة offline إذا انقطع، والموضوع sensor يقول هل القراءة موثوقة. والجهاز قد يكون متصلاً وحساسه معطل، وهما حالتان مختلفتان تحتاجان تصرفاً مختلفاً.
  • التعريف لـ Home Assistant: سنعود إليه في قسم مستقل.

والمواضيع Topics التي يستخدمها الجهاز، ومن يقرؤها، في الشكل التالي:

رسم: لوحة ESP32 مع SHT31 على اليمين، يخرج منها سهم إلى الوسيط Mosquitto، ومنه سهمان: إلى خدمة الاستقبال ingest.py مع SQLite ومنها سهم إلى الجوال عبر ntfy، وإلى شاشة Home Assistant، وتحت الرسم جدول المواضيع: state قراءة كل دقيقة بجودة QoS 0، وstatus فيها online عند الاتصال وoffline من الوصية ومحفوظة، وsensor فيها ok أو fault ومحفوظة، وevent للأحداث التي تحتاج إنساناً بجودة QoS 1، وhomeassistant/sensor/bedroom-1/…/config تعريف الجهاز لـ Home Assistant يرسل عند كل اتصال، وhomeassistant/status إذا أعيد تشغيل Home Assistant يعيد الجهاز التعريف
المواضيع التي ينشر عليها الجهاز، والطرفان اللذان يقرآنها

والقراءة الدورية بجودة QoS 0، لأن ضياع قراءة واحدة من ستين في الساعة لا يغير شيئاً والتي بعدها تأتي بعد دقيقة، أما الأحداث فبجودة QoS 1، لأن حدث العطل الذي يضيع لن يتكرر. وإذا أردت التفصيل في الفرق بين المستويات فقد شرحناه في مقال MQTT مع Mosquitto.

خدمة الاستقبال وقاعدة العفن

الجهاز يقيس وينشر فقط، والقرار هل هذه مشكلة تستحق تنبيهاً يكون في خدمة الاستقبال على السيرفر، كما رتبنا الطبقات في مقال معمارية إنترنت الأشياء، والسبب أنك تستطيع أن تغير القاعدة دون أن تعيد برمجة جهاز معلق على الحائط. والملف ingest.py كما يلي:

"""Ingest for the room climate project.
- subscribes to home/climate/# and keeps every reading in SQLite (/data/climate.db)
- mold-risk rule: humidity above 65 %RH for 30 minutes in a row -> one notification; cleared below 60 %RH
- sensor fault, sensor back, and device offline (its last will) -> notifications through ntfy (topic "climate")
- also logs the Home Assistant discovery configs it sees, to check what the device announced"""
import json, sqlite3, time, urllib.request
import paho.mqtt.client as mqtt

HIGH, CLEAR, FOR_MIN = 65.0, 60.0, 30
DB = sqlite3.connect("/data/climate.db")
DB.execute("CREATE TABLE IF NOT EXISTS reading(device TEXT, ts INT, seq INT, minute INT, t REAL, rh REAL, dew REAL)")
humid_since, mold_alerted = {}, {}

def notify(device, title, body, prio, tag="thermometer", minute=None):
    req = urllib.request.Request("http://ntfy/climate", data=f"{device}: {body}".encode(),
                                 headers={"Title": title, "Priority": str(prio), "Tags": tag})
    urllib.request.urlopen(req, timeout=5).read()
    print(f"notify {device}: {title}" + (f" (minute {minute})" if minute is not None else ""), flush=True)

def mold_rule(device, minute, rh):
    if rh > HIGH:
        humid_since.setdefault(device, minute)
        if minute - humid_since[device] >= FOR_MIN and not mold_alerted.get(device):
            notify(device, "Mold risk", f"humidity {rh:.0f}% for {minute - humid_since[device]} minutes, "
                   "ventilate the room or run a dehumidifier", 4, "droplet", minute)
            mold_alerted[device] = True
    elif rh < CLEAR:                                   # hysteresis: 60-65 neither starts nor clears
        if mold_alerted.get(device):
            notify(device, "Humidity back to normal", f"humidity {rh:.1f}%", 2, "droplet", minute)
        humid_since.pop(device, None)
        mold_alerted[device] = False

def on_message(c, u, m):
    if m.topic.startswith("homeassistant/sensor/"):
        cfg = json.loads(m.payload)
        print(f"discovery {m.topic}: {cfg['device_class']} in {cfg['unit_of_measurement']}, "
              f"unique_id={cfg['unique_id']}", flush=True)
        return
    _, _, device, kind = m.topic.split("/")           # home/climate/<device>/<kind>
    text = m.payload.decode()
    if kind == "status":
        print(f"status {device} = {text}", flush=True)
        if text == "offline":
            notify(device, "Device offline", "the controller lost its connection", 3)
    elif kind == "sensor":
        print(f"sensor {device} = {text}", flush=True)
    elif kind == "event":
        e = json.loads(text)
        print(f"event {device} {text}", flush=True)
        if e["event"] == "sensor_fault":
            notify(device, "Sensor fault", f"no reading for {e['minutes']} minutes ({e['error']}), "
                   "check the sensor wires. Values are not published while it is faulty", 4, "warning")
        elif e["event"] == "sensor_ok":
            notify(device, "Sensor back", "readings resumed", 2)
    elif kind == "state":
        r = json.loads(text)
        DB.execute("INSERT INTO reading VALUES(?,?,?,?,?,?,?)",
                   (device, int(time.time()), r["seq"], r["min"], r["t"], r["rh"], r["dew"]))
        DB.commit()
        mold_rule(device, r["min"], r["rh"])

c = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="climate-ingest")
c.on_connect = lambda c, u, f, rc, p: c.subscribe([("home/climate/#", 1), ("homeassistant/sensor/#", 1)])
c.on_message = on_message
while True:
    try:
        c.connect("broker", 1883)
        break
    except OSError:
        time.sleep(1)
c.loop_forever()

في الكود أعلاه لاحظ التالي:

  • القاعدة تستخدم رقم الدقيقة القادم من الجهاز وليس وقت وصول الرسالة، لكي تعمل مع الوقت المسرع في المحاكي، وفي جهاز حقيقي تستطيع أن تستخدم الوقت الفعلي.
  • الهامش Hysteresis: القاعدة تبدأ فوق 65% وتنتهي تحت 60%، وبينهما لا تتغير الحالة، ولو كانت القاعدة تبدأ وتنتهي عند رقم واحد لأرسلت تنبيهاً وإلغاءه كل مرة تتأرجح فيها الرطوبة حول الرقم، والرطوبة الحقيقية تتأرجح دائماً بنصف درجة أو درجة.
  • التنبيه يرسل مرة واحدة لكل فترة رطوبة، ثم رسالة واحدة عند العودة، بأولوية أقل.
  • التنبيهات بالخادم ntfy، وهو مشروع مفتوح المصدر يستقبل رسالة بطلب HTTP عادي ويوصلها إلى تطبيقه على الجوال، وتستطيع أن تشغله على سيرفرك كما في المختبر، والعنوان Title والأولوية Priority من 1 إلى 5 ترسل في ترويسات الطلب.

والملف report.py يقرأ ما حفظته الخدمة بعد التشغيل، ويطبع القراءات كل عشر دقائق، والدقائق التي لم تصل فيها قراءة، والتنبيهات التي وصلت إلى موضوع ntfy:

"""What the owner sees afterwards: the readings every 10 minutes, the minutes with no reading, and the notifications."""
import json, sqlite3, urllib.request

db = sqlite3.connect("/data/climate.db")
rows = db.execute("SELECT minute, t, rh, dew FROM reading ORDER BY seq").fetchall()
print("minute  temp   RH     dew")
for m, t, rh, dew in rows:
    if m % 10 == 0:
        print(f"{m:6d} {t:5.1f}C {rh:5.1f}% {dew:5.1f}C")
with open("/data/readings.csv", "w") as f:          # for the chart in the article
    f.writelines(f"{m},{t},{rh}\n" for m, t, rh, dew in rows)
have = {m for m, *_ in rows}
missing = [m for m in range(rows[0][0], rows[-1][0] + 1) if m not in have]
print(f"readings: {len(rows)}, minutes with no reading: {missing[0]}..{missing[-1]} ({len(missing)})" if missing
      else f"readings: {len(rows)}, no gaps")
above = [m for m, t, rh, dew in rows if rh > 65]
print(f"minutes above 65%: {len(above)} (from {above[0]} to {above[-1]})" if above else "never above 65%")
print("### notifications on ntfy topic 'climate'")
with urllib.request.urlopen("http://ntfy/climate/json?poll=1&since=all", timeout=5) as r:
    for line in r:
        n = json.loads(line)
        print(f"[priority {n.get('priority', 3)}] {n.get('title')}: {n['message']}")

تشغيل المشروع كاملاً

الملف compose.yaml يعرف أربع خدمات: الوسيط، وخادم ntfy، وخدمة الاستقبال، والبرنامج الثابت في المحاكي، ولاحظ السطر network_mode في الأخيرة: المحاكي يرى الجهاز الذي يشغله على العنوان 10.0.2.2، فجعلنا حاوية المحاكي تشارك الوسيط شبكته، فيصبح 10.0.2.2:1883 هو الوسيط نفسه:

# Room climate lab: the ESP32 firmware in QEMU, the broker, ntfy for phone notifications, and the ingest service.
name: climate
services:
  broker:
    image: eclipse-mosquitto:2.1.2-alpine
    volumes: [ "./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro" ]
  ntfy:
    image: binwiederhier/ntfy:v2.11.0
    command: serve
    environment: { NTFY_BASE_URL: "http://ntfy" }
  ingest:
    build: { context: ., dockerfile: Dockerfile.ingest }
    image: climate-ingest:1
    command: python -u ingest.py
    volumes: [ "./data:/data" ]
    depends_on: [ broker, ntfy ]
  firmware:
    image: espressif/idf:v5.4.1
    # shares the broker's network: inside QEMU, 10.0.2.2:1883 is this namespace's port 1883, the broker
    network_mode: "service:broker"
    working_dir: /lab
    volumes: [ "./:/lab" ]
    command: bash ./fw.sh
    profiles: [ firmware ]

والملف fw.sh يعمل داخل صورة ESP-IDF الرسمية: يبني نسخة اللوحة الحقيقية ليثبت أن مشغل I2C الحقيقي يبنى، ثم نسخة المحاكي، ثم يشغلها في QEMU:

#!/bin/bash
# Inside espressif/idf: build the firmware twice and run the simulated build in QEMU for $RUN_S seconds.
#   build-hw : the real board (I2C driver, Wi-Fi), compiled only, to prove the real drivers build
#   build-sim: SENSOR_SIM=1 (simulated I2C answer from a simulated room, time x60) over QEMU's emulated Ethernet
set -e
. "$IDF_PATH/export.sh" > /dev/null
python "$IDF_PATH/tools/idf_tools.py" install qemu-xtensa > /dev/null
. "$IDF_PATH/export.sh" > /dev/null
cd firmware
idf.py -B build-hw set-target esp32 > /dev/null
idf.py -B build-hw build 2>&1 | grep -E "binary size"
idf.py -B build-sim -DSENSOR_SIM=1 -DSDKCONFIG=build-sim/sdkconfig \
  -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.qemu" set-target esp32 > /dev/null
idf.py -B build-sim -DSENSOR_SIM=1 -DSDKCONFIG=build-sim/sdkconfig \
  -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.qemu" build 2>&1 | grep -E "binary size"
(cd build-sim && esptool.py --chip esp32 merge_bin --fill-flash-size 4MB -o flash.bin @flash_args > /dev/null)
echo "### qemu"
touch ../data/qemu-started
timeout "${RUN_S:-110}" qemu-system-xtensa -nographic -machine esp32 \
  -drive file=build-sim/flash.bin,if=mtd,format=raw -nic user,model=open_eth 2>&1 \
  | grep --line-buffered -E "^[IWE] \([0-9]+\) (climate|example_connect):|Guru" || true

والملف run.sh يشغل كل شيء، وبعد 40 ثانية من بدء المحاكي ينشر رسالة online على الموضوع homeassistant/status، كأن Home Assistant أعيد تشغيله، لنرى أن الجهاز يعيد تعريف نفسه:

#!/bin/bash
# Run the whole project on one machine. From this folder:  bash run.sh
set -e
rm -rf data && mkdir -p data
docker compose up -d --build --quiet-pull broker ntfy ingest 2>/dev/null
{ docker compose run --rm firmware 2>&1 | grep --line-buffered -E "binary size|^### |^[IWE] \(" | tee out-01-firmware.txt; } &
FW=$!
until [ -f data/qemu-started ]; do sleep 2; done   # wait for the two builds
sleep 40                                   # about 40 minutes of the room's time
docker compose exec -T broker mosquitto_pub -t homeassistant/status -m online -q 1   # Home Assistant restarted
wait $FW
sleep 3                                    # the broker sends the last will once the connection is gone
docker compose logs --no-log-prefix ingest | tee out-02-ingest.txt
docker compose run --rm --no-deps ingest python report.py | tee out-03-report.txt
docker compose down 2>/dev/null

ونشغله من مجلد lab بالأمر التالي، والبناء الأول يأخذ دقائق لأنه يبني ESP-IDF مرتين:

bash run.sh

ومخرج البرنامج الثابت سوف يكون كما يلي، والرقم بين القوسين في أول كل سطر هو الوقت بالملي ثانية منذ تشغيل الشريحة المحاكاة:

Bootloader binary size 0x6580 bytes. 0xa80 bytes (9%) free.
climate.bin binary size 0xdb0b0 bytes. Smallest app partition is 0x100000 bytes. 0x24f50 bytes (14%) free.
Bootloader binary size 0x6580 bytes. 0xa80 bytes (9%) free.
climate.bin binary size 0x88ad0 bytes. Smallest app partition is 0x100000 bytes. 0x77530 bytes (47%) free.
### qemu
I (12743) climate: connected to the broker
I (12783) climate: discovery sent (2 sensors)
I (12853) climate: {"seq":0,"min":0,"t":24.0,"rh":48.0,"dew":12.3}
I (17893) climate: {"seq":5,"min":5,"t":24.1,"rh":48.2,"dew":12.5}
I (22893) climate: {"seq":10,"min":10,"t":24.3,"rh":48.3,"dew":12.7}
I (27893) climate: {"seq":15,"min":15,"t":24.4,"rh":48.6,"dew":12.9}
I (32893) climate: {"seq":20,"min":20,"t":24.7,"rh":60.7,"dew":16.5}
I (37893) climate: {"seq":25,"min":25,"t":24.7,"rh":72.6,"dew":19.4}
I (42893) climate: {"seq":30,"min":30,"t":24.9,"rh":72.6,"dew":19.7}
I (46193) climate: Home Assistant restarted: announcing again
I (46213) climate: discovery sent (2 sensors)
I (47893) climate: {"seq":35,"min":35,"t":25.0,"rh":72.6,"dew":19.8}
I (52893) climate: {"seq":40,"min":40,"t":25.2,"rh":72.6,"dew":19.9}
I (57893) climate: {"seq":45,"min":45,"t":25.4,"rh":72.5,"dew":20.1}
I (62893) climate: {"seq":50,"min":50,"t":25.5,"rh":72.5,"dew":20.2}
I (67893) climate: {"seq":55,"min":55,"t":25.7,"rh":72.4,"dew":20.3}
I (72893) climate: {"seq":60,"min":60,"t":25.8,"rh":72.1,"dew":20.3}
I (77893) climate: {"seq":65,"min":65,"t":25.6,"rh":63.5,"dew":18.2}
I (82893) climate: {"seq":70,"min":70,"t":25.2,"rh":55.0,"dew":15.6}
W (87943) climate: minute 75: read failed (no ACK), 1 in a row
W (88993) climate: minute 76: read failed (no ACK), 2 in a row
W (90043) climate: minute 77: read failed (no ACK), 3 in a row
E (90093) climate: {"event":"sensor_fault","error":"nack","minutes":3}
W (91143) climate: minute 78: read failed (no ACK), 4 in a row
W (92213) climate: minute 79: read failed (no ACK), 5 in a row
W (93263) climate: minute 80: read failed (no ACK), 6 in a row
W (94313) climate: minute 81: read failed (no ACK), 7 in a row
W (95363) climate: minute 82: read failed (no ACK), 8 in a row
W (96413) climate: minute 83: read failed (no ACK), 9 in a row
W (97463) climate: minute 84: read failed (no ACK), 10 in a row
I (98463) climate: sensor back after 10 failed minutes
I (98493) climate: {"seq":75,"min":85,"t":24.5,"rh":54.4,"dew":14.7}
I (103513) climate: {"seq":80,"min":90,"t":24.3,"rh":54.4,"dew":14.5}
I (108513) climate: {"seq":85,"min":95,"t":24.0,"rh":54.4,"dew":14.2}
I (113513) climate: {"seq":90,"min":100,"t":23.8,"rh":54.5,"dew":14.1}

في المخرج أعلاه لاحظ التالي:

  • بين اتصال الجهاز بالوسيط وأول قراءة أجزاء من الثانية، والتعريف لـ Home Assistant أرسل قبل أول قراءة، ثم أرسل مرة ثانية عندما وصلت رسالة online على الموضوع homeassistant/status.
  • السجل يطبع قراءة كل خمس دقائق ليبقى قصيراً، أما الوسيط فيصله رقم كل دقيقة.
  • من الدقيقة 15 ترتفع الرطوبة مع الغسيل المنشور، فتصل 72.6% في الدقيقة 25، وترتفع نقطة الندى معها من 12.3 إلى 19.4 درجة، أي أن أي سطح في الغرفة أبرد من 19 درجة سيتكثف عليه الماء الآن، كالجدار الخارجي أو زجاج النافذة عندما يعمل المكيف.
  • في الدقيقة 75 انفصل السلك، فأعاد الجهاز المحاولة مرة كل دقيقة، وفي الدقيقة الثالثة من الفشل أعلن العطل، ثم بقي يحاول دون أن ينشر رقماً، وعندما عاد السلك في الدقيقة 85 عادت القراءات وحدها دون إعادة تشغيل.

ومخرج خدمة الاستقبال سوف يكون كما يلي:

status bedroom-1 = online
sensor bedroom-1 = ok
discovery homeassistant/sensor/bedroom-1/temperature/config: temperature in °C, unique_id=bedroom-1_temperature
discovery homeassistant/sensor/bedroom-1/humidity/config: humidity in %, unique_id=bedroom-1_humidity
discovery homeassistant/sensor/bedroom-1/temperature/config: temperature in °C, unique_id=bedroom-1_temperature
discovery homeassistant/sensor/bedroom-1/humidity/config: humidity in %, unique_id=bedroom-1_humidity
notify bedroom-1: Mold risk (minute 53)
notify bedroom-1: Humidity back to normal (minute 67)
event bedroom-1 {"event":"sensor_fault","error":"nack","minutes":3}
notify bedroom-1: Sensor fault
sensor bedroom-1 = fault
event bedroom-1 {"event":"sensor_ok"}
notify bedroom-1: Sensor back
sensor bedroom-1 = ok
status bedroom-1 = offline
notify bedroom-1: Device offline

والقصة نفسها من جهة السيرفر: الجهاز اتصل وحساسه سليم، والتعريفان وصلا مرتين، ثم تنبيه خطر العفن في الدقيقة 53، أي بعد ثلاثين دقيقة متصلة فوق 65% بدأت في الدقيقة 23، ثم عودة الرطوبة تحت 60% في الدقيقة 67 بعد فتح النافذة، وآخر قراءة قبلها كانت 63.5% في الدقيقة 65، أي أنها بقيت فوق 60% دقيقتين بعد أن نزلت تحت 65% ولم يرسل شيء، وهذا هو الهامش يعمل، ثم العطل والعودة، وأخيراً رسالة offline عندما أوقف السكربت المحاكي، وهذه لم يرسلها الجهاز، وإنما أرسلها الوسيط نيابة عنه من الوصية Last Will عندما انقطع الاتصال دون وداع.

وأخيراً التقرير:

minute  temp   RH     dew
     0  24.0C  48.0%  12.3C
    10  24.3C  48.3%  12.7C
    20  24.7C  60.7%  16.5C
    30  24.9C  72.6%  19.7C
    40  25.2C  72.6%  19.9C
    50  25.5C  72.5%  20.2C
    60  25.8C  72.1%  20.3C
    70  25.2C  55.0%  15.6C
    90  24.3C  54.4%  14.5C
   100  23.8C  54.5%  14.1C
readings: 92, minutes with no reading: 75..84 (10)
minutes above 65%: 42 (from 23 to 64)
### notifications on ntfy topic 'climate'
[priority 4] Mold risk: bedroom-1: humidity 72% for 30 minutes, ventilate the room or run a dehumidifier
[priority 2] Humidity back to normal: bedroom-1: humidity 59.6%
[priority 4] Sensor fault: bedroom-1: no reading for 3 minutes (nack), check the sensor wires. Values are not published while it is faulty
[priority 2] Sensor back: bedroom-1: readings resumed
[priority 3] Device offline: bedroom-1: the controller lost its connection

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

رسم خطي للرطوبة مع الدقائق من 0 إلى 100: خط أسود يبدأ عند 48% ثم يرتفع بعد الدقيقة 15 إلى قرابة 72% ويبقى حتى الدقيقة 60 ثم ينزل إلى قرابة 55%، وخط متقطع برتقالي عند 65% وخط متقطع أزرق عند 60%، وخط عمودي برتقالي عند لحظة تنبيه خطر العفن، وخط عمودي أزرق عند عودة الرطوبة، ومنطقة حمراء فاتحة مكتوب عليها لا قراءات بين الدقيقة 75 و85 ينقطع فيها الخط
قراءات الرطوبة في تشغيل المختبر، والفجوة حيث انفصل الحساس

ولاحظ في الرسم المسافة بين عبور الخط البرتقالي والتنبيه: هذه هي الثلاثون دقيقة، ولو كانت الرطوبة نزلت قبلها لما وصلك شيء، وهذا ما نريده.

اكسرها: الحساس الذي اختفى

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

  • المصفوفة أصفار: إذا بقيت البايتات أصفاراً لأن القراءة لم تكتب فيها، فمعادلة الحرارة تعطي -45 + 175 × 0 / 65535، أي 45 درجة تحت الصفر، والرطوبة صفر. ولوحة المتابعة سترسم هبوطاً مفاجئاً لا معنى له، وقاعدة «الحرارة تحت 10 درجات» إن كانت عندك سترسل تنبيهاً كاذباً في منتصف الليل.
  • المصفوفة 0xFF: الخط SDA الذي انفصل ترفعه مقاومة الرفع إلى الجهد، فإذا قرأ المتحكم البتات رغم ذلك فسوف يقرأ واحدات، فتصبح الحرارة -45 + 175، أي 130 درجة، والرطوبة 100%.
  • آخر قراءة ناجحة: وهذا الأسوأ، لأن الرقم يبدو طبيعياً تماماً، 24 درجة و55%، ويبقى كذلك أسابيع، والغرفة تتغير والجهاز يكرر رقماً قديماً، ولا أحد يعرف أن الحساس مات، والقاعدة لن تنبه أبداً.

ولاحظ أن الـ CRC يحمي من الحالتين الأولى والثانية حتى لو أهملت نتيجة القراءة، لأن الـ CRC الصحيح للبايتين 0x00 0x00 هو 0x81 وليس صفراً، وللبايتين 0xFF 0xFF هو 0xAC وليس 0xFF، فترفض الدالة sht31_measure القراءة بحالة SHT_CRC. وهذا سبب كاف لكي لا تحذف فحص الـ CRC من الكود لتوفير سطرين. ولكن الحالة الثالثة لا يحمي منها إلا قرار في التصميم: الجهاز لا يكرر رقماً لم يقسه الآن، وإنما يقول بصراحة إنه لا يعرف. وفي Home Assistant يظهر الحساس عندها «غير متوفر» Unavailable بدل رقم مطمئن، لأن تعريفه يعتمد على موضوعي التوفر معاً كما سنرى.

💡
إذا علق ناقل I2C نفسه، بأن انقطعت الكهرباء عن الحساس في منتصف قراءة فبقي ممسكاً بالخط SDA منخفضاً، فلن ترد أي شريحة على الناقل حتى تعيد ضبطه، والحل المعروف أن يرسل المتحكم نبضات على SCL حتى يحرر الحساس الخط، أو أن تقطع الطاقة عن الحساس وتعيدها، ولهذا يوصل بعض المصممين طاقة الحساس من رجل يتحكم فيها المتحكم.

التعريف التلقائي لـ Home Assistant

Home Assistant يستطيع أن يقرأ أي موضوع MQTT إذا كتبت له تعريفاً يدوياً، ولكن الأسهل أن يعرف الجهاز نفسه، وهذا ما يسمى الاكتشاف MQTT Discovery: ينشر الجهاز رسالة تعريف على موضوع بالشكل التالي، كما في توثيق تكامل MQTT:

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

والبادئة الافتراضية homeassistant، والمكون sensor، فتصبح مواضيعنا homeassistant/sensor/bedroom-1/temperature/config وhomeassistant/sensor/bedroom-1/humidity/config. وفي رسالة التعريف التي يبنيها الكود لاحظ ما يلي:

  • device_class وunit_of_measurement تخبر Home Assistant أن هذا حساس حرارة بالمئوية، فيعرض الأيقونة والوحدة الصحيحة ويحفظ التاريخ.
  • value_template يأخذ الرقم من رسالة JSON، فالرسالة الواحدة على الموضوع state تخدم الحساسين معاً.
  • unique_id يجعل الحساس يبقى هو نفسه إذا أعيد تشغيل أي طرف، فتستطيع أن تغير اسمه في الواجهة.
  • device يجمع الحساسين تحت جهاز واحد في الواجهة.
  • availability قائمة بموضوعين، مع availability_mode بقيمة all، أي أن الحساس متوفر فقط إذا كان الجهاز متصلاً والحساس سليماً معاً.

وقد يتساءل البعض: لماذا لا نحفظ رسالة التعريف على الوسيط Retained ونرتاح؟ والتوثيق نفسه يجيب: الرسائل المحفوظة قد تصنع كيانات شبحية تعود كلما حذفتها، والطريقة الأفضل أن يعيد الجهاز التعريف عندما ينشر Home Assistant رسالة الولادة Birth Message على الموضوع homeassistant/status، وهذا ما يفعله الكود، وما اختبرناه في المختبر. وإذا أردت أن تحذف الحساس من Home Assistant فانشر رسالة فارغة على موضوع التعريف نفسه.

وإذا كنت تستخدم Home Assistant فهناك طريق آخر للمشروع كله: ESPHome، وهو يدعم هذا الحساس بمكون جاهز، وقد استخدمناه في مقال Home Assistant مع ESPHome. والسبب في أننا كتبنا البرنامج الثابت بأنفسنا هنا أن تفهم ما يحدث تحت ESPHome: أمر من بايتين، وانتظار، وست بايتات، وCRC، ومعادلتان، وقرار ماذا تفعل عندما يفشل شيء.

هل الحساس صادق؟ اختبار الملح

المختبر أثبت أن الكود يتصرف صحيحاً، ولكنه لا يقول شيئاً عن الحساس الذي وصلك في البريد، فاللوحات الرخيصة كثيرة، وبعضها يحمل شريحة غير التي كتبت عليه. وقد يتساءل البعض: كيف أتحقق من الرطوبة دون جهاز معايرة؟ والإجابة في تجربة قديمة يستخدمها المختبرون منذ عقود: المحلول المشبع من ملح الطعام في وعاء مغلق يجعل الهواء فوقه يستقر على رطوبة نسبية ثابتة تقريباً، وقد جمع Lewis Greenspan قياسات هذه المحاليل في ورقته في مجلة NBS سنة 1977، وقيمة ملح الطعام فيها 75.47% عند 20 درجة، و75.29% عند 25 درجة، و75.09% عند 30 درجة، أي أنها لا تكاد تتغير مع الحرارة، وهذا ما يجعلها نقطة مرجعية مريحة في البيت.

والطريقة كما يلي:

  1. ضع في غطاء زجاجة صغير ملح طعام عادياً، وأضف إليه قطرات ماء حتى يصبح عجينة رطبة، ويبقى فيه ملح لم يذب، لأن المحلول يجب أن يكون مشبعاً.
  2. ضع الغطاء والحساس معاً في وعاء محكم الإغلاق، كعلبة طعام بلاستيكية أو كيس بسحاب، دون أن يلمس الحساس الملح، ويخرج السلك من طرف الغطاء ثم تغلق الفتحة بشريط.
  3. اترك الوعاء في مكان حرارته ثابتة ساعات، والأفضل ليلة كاملة، لأن الهواء في الوعاء يحتاج وقتاً ليستقر، ولا تضعه في الشمس.
  4. اقرأ الرطوبة من الموضوع state أو من Home Assistant، وقارنها بـ 75%: إذا كان الفرق في حدود دقة الحساس، ±2%، فالحساس سليم، وإذا كان الفرق كبيراً وثابتاً فإما أن تستبدله، أو تطرح الفرق في خدمة الاستقبال وتكتب ذلك بجانب الكود.

ولاحظ أن هذا الاختبار يفحص نقطة واحدة فقط، 75%، ولا يقول شيئاً عن 40% مثلاً، وللنقطة الثانية يستخدم المختبرون ملحاً آخر مثل كلوريد المغنيسيوم، وقيمته في الورقة نفسها قرابة 33%. ولاحظ أيضاً ما ذكرته ورقة البيانات: البقاء الطويل في رطوبة عالية قد يسبب انحرافاً مؤقتاً، فبعد ليلة في 75% اترك الحساس في هواء الغرفة ساعات قبل أن تعتمد قراءته.

كم مرة نقيس، وكم نحفظ؟

قد يبدو أن القياس كل ثانية أدق من القياس كل دقيقة، ولكن الغرفة لا تتغير بهذه السرعة، والحساس نفسه يحتاج 8 ثوان ليرى 63% من أي تغير في الرطوبة كما رأينا في ورقة البيانات، فالقراءات الكثيرة لا تضيف معلومة، وإنما تضيف رسائل على الشبكة وصفوفاً في قاعدة البيانات وحرارة في الحساس. ودقيقة واحدة تعطي 1440 قراءة في اليوم، أي قرابة نصف مليون صف في السنة لكل غرفة، وهذا شيء بسيط على SQLite في سيرفر صغير، ولكن إذا أصبحت الغرف عشراً والقراءات كل ثانية فسوف تبدأ تفكر في التجميع، كأن تحفظ المتوسط والأعلى والأقل لكل ساعة بعد مرور أسبوع، كما ناقشنا في مقال لوحات المتابعة.

وإذا كان الجهاز على بطارية فالحساب يتغير كله، لأن ما يستهلك البطارية ليس الحساس وإنما Wi-Fi، والحل هناك أن ينام المتحكم بين القراءات ويجمع عدة قراءات ثم يرسلها دفعة واحدة، وهذه هي المشكلة التي سنواجهها في المشروع القادم.

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

  • الحساس داخل العلبة مع المتحكم: يقرأ حرارة المتحكم. أخرجه أو افصله بحاجز وفتحات.
  • تجاهل نتيجة القراءة: رأينا في قسم الكسر ماذا يحدث: 45 درجة تحت الصفر، أو رقم قديم يبقى أسابيع.
  • التنبيه على كل تجاوز: الرطوبة ترتفع دقائق مع كل حمام وكل طبخة، والتنبيه الذي لا يحمل مدة ولا هامشاً يتحول إلى ضوضاء.
  • رسائل التعريف المحفوظة القديمة: غيرت اسم الجهاز فظهر في Home Assistant جهازان، أحدهما لا يتحدث. احذف التعريف القديم برسالة فارغة.
  • الوثوق بالرقم الأول بعد التشغيل: الحساس يحتاج ثواني ليتأقلم إذا نقلته من مكان لآخر، وزمن استجابة الرطوبة في ورقة البيانات 8 ثوان في هواء يتحرك، وفي هواء ساكن أطول.
  • الوسيط مفتوح للجميع: المختبر يسمح بالدخول دون كلمة مرور ليبقى بسيطاً، وفي البيت ضع كلمة مرور وقائمة صلاحيات كما في مقال أمن إنترنت الأشياء.

تطبيق عملي

  1. أضف إلى ingest.py قاعدة لنقطة الندى: إذا اقتربت نقطة الندى من حرارة أبرد سطح في الغرفة، وهي رقم تدخله أنت كقياس لزجاج النافذة، بأقل من درجتين، فأرسل تنبيه «خطر تكثف».
  2. غير الغرفة المحاكاة في sht31.c بحيث يأتي بايت CRC خاطئ مرة كل عشر قراءات، وتوقع قبل التشغيل: هل سيصل الجهاز إلى حالة العطل؟ ولماذا؟
  3. أضف حساساً ثانياً على العنوان 0x45 في غرفة أخرى على الناقل نفسه، وانشر قراءته على جهاز ثان في Home Assistant.
  4. اجعل report.py يحسب عدد الساعات فوق 65% لكل يوم، وهو الرقم الذي ستسأل عنه بعد شهر.

حذف المختبر Cleanup

docker compose down
docker image rm climate-ingest:1
rm -rf data firmware/build-hw firmware/build-sim

الأوامر تحذف الحاويات والـ Image وملفات البناء والقراءات، وتبقى الصورة espressif/idf:v5.4.1 لأن مشاريع السلسلة الأخرى تستخدمها، فإذا لم تعد تحتاجها فاحذفها بالأمر docker image rm espressif/idf:v5.4.1.

الخلاصة Summary

  • الرطوبة النسبية تعتمد على الحرارة، ونقطة الندى هي الحرارة التي يتكثف عندها الماء، وEPA توصي بأن تبقى الرطوبة داخل المنزل أقل من 60%.
  • القاعدة الجيدة لها مدة وهامش: فوق 65% ثلاثين دقيقة لتبدأ، وتحت 60% لتنتهي، وتنبيه واحد لكل فترة.
  • الحساس SHT31 على I2C: أمر من بايتين، وانتظار 15.5 ملي ثانية كحد أقصى، وست بايتات فيها CRC، ومعادلتان من ورقة البيانات.
  • مكان الحساس نصف دقته: بعيداً عن المتحكم والشمس والمكيف.
  • عندما يفشل الحساس لا تنشر رقماً قديماً ولا رقماً محولاً من بايتات فارغة، وإنما قل إنك لا تعرف، واجعل الحساس غير متوفر.
  • التعريف التلقائي لـ Home Assistant يرسل عند كل اتصال وعند رسالة الولادة، وليس رسالة محفوظة.

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

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة المقال، وبناء البرنامج الثابت بإطار ESP-IDF v5.4.1 وتشغيله في محاكي QEMU من Espressif، مع Mosquitto 2.1.2 وntfy 2.11.0 وPython 3.13 وpaho-mqtt 2.2.0 في Docker Engine 29.8.0.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.