هل لاحظت أن غرفة النوم في بعض الليالي تبدو ثقيلة رغم أن المكيف يعمل، أو أن زجاج النافذة يمتلئ بقطرات الماء في الصباح، أو أن بقعة داكنة بدأت تظهر في زاوية خلف الدولاب؟ هذه كلها أسئلة عن شيئين نعيش فيهما ولا نراهما: الحرارة والرطوبة. والمقياس المعلق على الحائط يجيب عن اللحظة التي تنظر إليه فيها فقط، أما السؤال المهم فهو: ماذا حدث في الغرفة طوال الليل، وكم ساعة بقيت الرطوبة عالية، ومتى يجب أن تفتح النافذة؟ وهذا سؤال يجيب عنه جهاز صغير يقيس كل دقيقة ويحفظ القراءات ويخبرك عندما يتجاوز شيء الحد، وهو المشروع الثاني من المشاريع المنزلية في سلسلة مشاريع إنترنت الأشياء.
وفي مشروع ري النباتات قرأنا حساساً تماثلياً بالمحول ADC وشغلنا مضخة، وفي هذا المشروع لا يوجد مخرج نتحكم فيه، وإنما حساس رقمي واحد على ناقل I2C، والتحدي هنا مختلف: أن تكون القراءة صحيحة، وأن تكون في المكان الصحيح، وأن يعرف النظام كله متى لا يجب أن يصدق الرقم. وسوف نبني المشروع كاملاً: البرنامج الثابت Firmware على ESP32 مع الحساس SHT31، ثم الوسيط Mosquitto، ثم خدمة تحفظ القراءات وتطبق قاعدة خطر العفن، ثم تنبيهات على الجوال، ونجعل الجهاز يعرف نفسه لـ Home Assistant تلقائياً، ونشغل ذلك كله على جهازك بالمحاكي QEMU.
وسوف نناقش في هذا المقال ما يلي:
- ماذا نقيس: الحرارة والرطوبة النسبية ونقطة الندى، ولماذا نهتم بالرطوبة فوق 60%.
- اختيار الحساس: من المقياس التقليدي إلى DHT22 إلى حساسات I2C، ولماذا اخترنا SHT31.
- التوصيل، ومكان الحساس في الغرفة، وهو نصف دقة المشروع.
- البرنامج الثابت: قراءة الحساس بأمر واحد، وفحص CRC، وتحويل الأرقام، والتعريف لـ Home Assistant.
- خدمة الاستقبال وقاعدة العفن مع الهامش Hysteresis، والتنبيهات عبر ntfy.
- تشغيل المشروع كاملاً، ثم كسره: سلك ينفصل، وماذا يجب أن يحدث عندها.
ماذا نقيس، ولماذا الرطوبة بالذات؟
الحرارة سهلة الفهم، أما الرطوبة النسبية Relative Humidity فهي نسبة بخار الماء الموجود في الهواء إلى أكبر كمية يستطيع الهواء أن يحملها عند الحرارة نفسها. ولاحظ كلمة «عند الحرارة نفسها»، لأن الهواء الدافئ يحمل ماء أكثر من البارد، فالهواء نفسه بكمية الماء نفسها تكون رطوبته النسبية 50% في الغرفة، فإذا لمس زجاج نافذة بارد ارتفعت رطوبته النسبية عند الزجاج حتى تصل إلى 100%، فيتكثف الماء على الزجاج. والحرارة التي يبدأ عندها التكثف تسمى نقطة الندى Dew Point، وهي الرقم الثالث الذي سيحسبه جهازنا من الرقمين الأولين.
والصورة التالية فيها النتيجتان اللتان نريد أن نمنعهما، على اليمين ماء تكثف على زجاج نافذة في غرفة رطبة باردة، وعلى اليسار عفن على جدار:

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

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

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

ولاحظ أن الأرجل في اللوحات الثلاث تقريباً واحدة: طاقة وأرضي و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، فيعرف المتحكم إذا وصلت البيانات تالفة.
والنقطة الأخيرة هي التي ستنقذنا في قسم الكسر بعد قليل، فاحفظها.
التوصيل
التوصيل أربعة أسلاك كما في الشكل التالي:

- الطاقة والأرضي: من 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، فيعود الحساس إلى السكون بين القياسات.
- الشمس والمكيف: شعاع الشمس على الحساس يرفع قراءته بدرجات، وفتحة المكيف تعطيك حرارة الهواء الخارج من المكيف وليس الغرفة. ضعه على جدار داخلي، بعيداً عن النافذة وفتحة المكيف وباب الحمام والمطبخ.
- دون حماية: الحساس يحتاج أن يلمسه الهواء، ولكن الغبار والرذاذ يضرانه، والصورة التالية لطرف حساس رطوبة من جهاز قياس احترافي، ولاحظ الغطاء الذي بجانبه: فتحات طولية تمرر الهواء وتحمي الحساس من اللمس:

وإذا أردت أن تعرف هل المكان جيد، ضع بجانب الحساس مقياساً آخر ليوم كامل، وقارن الرقمين في الصباح وبعد الظهر، فإذا اختلفا في ساعات الشمس فقط فالمشكلة في المكان وليست في الحساس.
البرنامج الثابت: الحساس
المختبر في مجلد 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 التي يستخدمها الجهاز، ومن يقرؤها، في الشكل التالي:

والقراءة الدورية بجودة 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 لا قراءة فيها، وهذه هي الحقيقة، لأن الجهاز لم يعرف حرارة الغرفة في تلك الدقائق. ولوحة المتابعة التي ترسم هذه البيانات سترسم فجوة في الخط، وهذا أفضل من خط مستقيم كاذب. والشكل التالي يرسم كل قراءة رطوبة حفظتها الخدمة في هذا التشغيل، مع خطي القاعدة:

ولاحظ في الرسم المسافة بين عبور الخط البرتقالي والتنبيه: هذه هي الثلاثون دقيقة، ولو كانت الرطوبة نزلت قبلها لما وصلك شيء، وهذا ما نريده.
اكسرها: الحساس الذي اختفى
في الدقائق التي انفصل فيها السلك في المحاكاة، لم يرد الحساس على عنوانه، فلم يرسل الجهاز أي رقم، ورأيت ذلك في المخرج: سطور فشل، ثم حدث عطل، ثم فجوة في القراءات المحفوظة، ثم عودة. والسؤال الذي يجب أن تسأله الآن: ماذا لو كتبنا الكود بالطريقة التي تكتب بها أغلب الأمثلة على الإنترنت، فقرأنا ست بايتات وحولناها مباشرة دون أن ننظر إلى نتيجة القراءة؟ هناك ثلاث نتائج ممكنة، وكلها سيئة:
- المصفوفة أصفار: إذا بقيت البايتات أصفاراً لأن القراءة لم تكتب فيها، فمعادلة الحرارة تعطي
-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 بدل رقم مطمئن، لأن تعريفه يعتمد على موضوعي التوفر معاً كما سنرى.
التعريف التلقائي لـ 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 درجة، أي أنها لا تكاد تتغير مع الحرارة، وهذا ما يجعلها نقطة مرجعية مريحة في البيت.
والطريقة كما يلي:
- ضع في غطاء زجاجة صغير ملح طعام عادياً، وأضف إليه قطرات ماء حتى يصبح عجينة رطبة، ويبقى فيه ملح لم يذب، لأن المحلول يجب أن يكون مشبعاً.
- ضع الغطاء والحساس معاً في وعاء محكم الإغلاق، كعلبة طعام بلاستيكية أو كيس بسحاب، دون أن يلمس الحساس الملح، ويخرج السلك من طرف الغطاء ثم تغلق الفتحة بشريط.
- اترك الوعاء في مكان حرارته ثابتة ساعات، والأفضل ليلة كاملة، لأن الهواء في الوعاء يحتاج وقتاً ليستقر، ولا تضعه في الشمس.
- اقرأ الرطوبة من الموضوع
stateأو من Home Assistant، وقارنها بـ 75%: إذا كان الفرق في حدود دقة الحساس، ±2%، فالحساس سليم، وإذا كان الفرق كبيراً وثابتاً فإما أن تستبدله، أو تطرح الفرق في خدمة الاستقبال وتكتب ذلك بجانب الكود.
ولاحظ أن هذا الاختبار يفحص نقطة واحدة فقط، 75%، ولا يقول شيئاً عن 40% مثلاً، وللنقطة الثانية يستخدم المختبرون ملحاً آخر مثل كلوريد المغنيسيوم، وقيمته في الورقة نفسها قرابة 33%. ولاحظ أيضاً ما ذكرته ورقة البيانات: البقاء الطويل في رطوبة عالية قد يسبب انحرافاً مؤقتاً، فبعد ليلة في 75% اترك الحساس في هواء الغرفة ساعات قبل أن تعتمد قراءته.
كم مرة نقيس، وكم نحفظ؟
قد يبدو أن القياس كل ثانية أدق من القياس كل دقيقة، ولكن الغرفة لا تتغير بهذه السرعة، والحساس نفسه يحتاج 8 ثوان ليرى 63% من أي تغير في الرطوبة كما رأينا في ورقة البيانات، فالقراءات الكثيرة لا تضيف معلومة، وإنما تضيف رسائل على الشبكة وصفوفاً في قاعدة البيانات وحرارة في الحساس. ودقيقة واحدة تعطي 1440 قراءة في اليوم، أي قرابة نصف مليون صف في السنة لكل غرفة، وهذا شيء بسيط على SQLite في سيرفر صغير، ولكن إذا أصبحت الغرف عشراً والقراءات كل ثانية فسوف تبدأ تفكر في التجميع، كأن تحفظ المتوسط والأعلى والأقل لكل ساعة بعد مرور أسبوع، كما ناقشنا في مقال لوحات المتابعة.
وإذا كان الجهاز على بطارية فالحساب يتغير كله، لأن ما يستهلك البطارية ليس الحساس وإنما Wi-Fi، والحل هناك أن ينام المتحكم بين القراءات ويجمع عدة قراءات ثم يرسلها دفعة واحدة، وهذه هي المشكلة التي سنواجهها في المشروع القادم.
الأخطاء الشائعة
- الحساس داخل العلبة مع المتحكم: يقرأ حرارة المتحكم. أخرجه أو افصله بحاجز وفتحات.
- تجاهل نتيجة القراءة: رأينا في قسم الكسر ماذا يحدث: 45 درجة تحت الصفر، أو رقم قديم يبقى أسابيع.
- التنبيه على كل تجاوز: الرطوبة ترتفع دقائق مع كل حمام وكل طبخة، والتنبيه الذي لا يحمل مدة ولا هامشاً يتحول إلى ضوضاء.
- رسائل التعريف المحفوظة القديمة: غيرت اسم الجهاز فظهر في Home Assistant جهازان، أحدهما لا يتحدث. احذف التعريف القديم برسالة فارغة.
- الوثوق بالرقم الأول بعد التشغيل: الحساس يحتاج ثواني ليتأقلم إذا نقلته من مكان لآخر، وزمن استجابة الرطوبة في ورقة البيانات 8 ثوان في هواء يتحرك، وفي هواء ساكن أطول.
- الوسيط مفتوح للجميع: المختبر يسمح بالدخول دون كلمة مرور ليبقى بسيطاً، وفي البيت ضع كلمة مرور وقائمة صلاحيات كما في مقال أمن إنترنت الأشياء.
تطبيق عملي
- أضف إلى
ingest.pyقاعدة لنقطة الندى: إذا اقتربت نقطة الندى من حرارة أبرد سطح في الغرفة، وهي رقم تدخله أنت كقياس لزجاج النافذة، بأقل من درجتين، فأرسل تنبيه «خطر تكثف». - غير الغرفة المحاكاة في
sht31.cبحيث يأتي بايت CRC خاطئ مرة كل عشر قراءات، وتوقع قبل التشغيل: هل سيصل الجهاز إلى حالة العطل؟ ولماذا؟ - أضف حساساً ثانياً على العنوان 0x45 في غرفة أخرى على الناقل نفسه، وانشر قراءته على جهاز ثان في Home Assistant.
- اجعل
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.