> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# مشروع مراقبة غرف التبريد والثلاجات الدوائية
- URL: https://arabroot.io/articles/مشروع-مراقبة-غرف-التبريد-والثلاجات-الدوائية/
- Published: 2026-11-11T19:09:00.000Z
- Updated: 2026-11-12T06:44:29.000Z
- Description: نظام يراقب ثلاجات الأدوية بين 2 و8 درجات بمجسات DS18B20 وشريحة ESP32، لا يضيع قراءة إذا توقف الوسيط، وينبه بالمدة مع إقرار وتصعيد وتقرير يومي للمفتش.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, الإلكترونيات والطائرات المسيرة والطباعة ثلاثية الأبعاد

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

وقد شرحنا في [مقال إنترنت الأشياء من الحساس إلى لوحة المتابعة](https://arabroot.io/articles/%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D9%85%D9%86-%D8%A7%D9%84%D8%AD%D8%B3%D8%A7%D8%B3-%D8%A7%D9%84%D9%89-%D9%84%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%AA%D8%A7%D8%A8%D8%B9%D8%A9/) الطبقات التي يمر بها رقم الحرارة من غرفة التبريد إلى الشاشة، وبنينا المسار هناك بجهاز محاكى بلغة Python، ورأينا كم قراءة تضيع عندما يتوقف الوسيط. وفي هذا المقال سوف نبني المشروع نفسه كما يبنى لعميل حقيقي: برنامج ثابت Firmware حقيقي لشريحة ESP32 بلغة C، يقرأ مجسات DS18B20 بسلك واحد 1-Wire، ويحتفظ بكل قراءة في ذاكرته حتى يقر الوسيط باستلامها، وخدمة على السيرفر تطبق قاعدة الانحراف الحراري بالمدة وليس بالقراءة الواحدة، وترسل التنبيه إلى جوال الصيدلي مع زر إقرار، وتصعده إلى المدير إذا لم يقر به أحد، ثم تخرج في نهاية اليوم تقريراً يمكن أن تسلمه لمفتش. وسوف نشغل البرنامج الثابت نفسه على محاكي QEMU من Espressif، ونوقف الوسيط ربع ساعة، وننزع أحد المجسات، ونرى ماذا يصل وماذا يضيع.

وهذا المقال من سلسلة مشاريع إنترنت الأشياء، والمشاريع في السلسلة مرتبة في [دليل مشاريع إنترنت الأشياء](https://arabroot.io/articles/%D9%85%D8%B4%D8%A7%D8%B1%D9%8A%D8%B9-%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-%D9%85%D9%86-%D8%A7%D9%8A%D9%86-%D8%AA%D8%A8%D8%AF%D8%A7/)، وهذا المشروع من المشاريع التجارية فيها، والفرق بينه وبين مشاريع البيت أن الخطأ فيه له ثمن يدفعه شخص آخر: مريض يأخذ لقاحاً فقد فعاليته، أو صيدلية تتلف مخزوناً سليماً لأن السجل ناقص.

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

- ما الذي تطلبه الجهات الصحية من مراقبة ثلاجة الأدوية، ولماذا تختلف عن مراقبة ثلاجة البيت.
- القطع: المجس DS18B20 وبروتوكول السلك الواحد، وحساس الباب، والصفارة المحلية.
- كتابة مشغل DS18B20 من ورقة البيانات، والقراءات التي يجب ألا تصدقها: +85 والمجس الغائب.
- التخزين والإرسال Store and Forward: حلقة في ذاكرة الجهاز لا يخرج منها سجل إلا بإقرار من الوسيط.
- خدمة الاستقبال: حذف المكرر، وكشف الفجوات، وقاعدة الانحراف بالمدة، والتصعيد، والمراقبة من جهة السيرفر.
- المختبر كاملاً على جهازك، مع إيقاف الوسيط ونزع مجس، والتقرير اليومي.
- الأخطاء الشائعة، وتمارين تطبيقية.

## ماذا يطلب المفتش من ثلاجة الأدوية؟

قبل أن نكتب سطراً واحداً من الكود يجب أن نعرف ماذا يعني «النظام يعمل» في نظر الجهة التي تراقب الصيدلية، لأن هذا هو الذي يحدد التصميم، وليس ما نستطيع نحن أن نبنيه. والمرجع الذي اعتمدنا عليه في هذا المشروع هو دليل تخزين اللقاحات ومناولتها Vaccine Storage and Handling Toolkit من مراكز السيطرة على الأمراض والوقاية منها الأمريكية CDC، في إصداره بتاريخ يوليو 2026، وهو مرجع مفصل ومتاح للجميع، والجهات الصحية في كل بلد لها أدلتها الخاصة، فإذا كنت تبني لعميل حقيقي فاقرأ دليل الجهة التي يتبعها قبل أن تعتمد على الأرقام التالية. وفيما يلي ما يهمنا منه كمبرمجين:

- **المدى Range:** الثلاجة بين 2 و8 درجات مئوية، أي بين 36 و46 فهرنهايت.
- **مسجل البيانات الرقمي Digital Data Logger:** يوصي الدليل بجهاز يراقب باستمرار ويسجل كل القراءات على فترات ثابتة، وليس ميزان حرارة يعرض أعلى وأدنى رقم فقط، والسبب الذي يذكره الدليل هو ما رأيناه في القصة: الجهاز يخبرك كم بقيت الثلاجة خارج المدى، وليس فقط أنها خرجت.
- **فترة التسجيل Logging Interval:** قراءة كل 30 دقيقة على الأقل، وفي مشروعنا قراءة كل دقيقة.
- **الدقة Uncertainty:** يوصي الدليل بدقة ±0.5 درجة مئوية.
- **التنبيه Alarm:** تنبيه عند الخروج عن المدى، ومؤشر لضعف البطارية، وعرض الحرارة الحالية وأعلاها وأدناها.
- **المجس المعزول Buffered Probe:** مجس مغمور في قارورة فيها سائل مثل الجلايكول Glycol، أو في رمل أو كتلة معدنية، ويذكر الدليل أن الهدف منه منع الانحرافات الكاذبة False Excursions التي تحدث عندما يفتح أحدهم الباب، فالمجس يقيس حرارة شيء يشبه الدواء، وليس حرارة الهواء الذي يتغير في ثوان.
- **مكان المجس:** في وسط الثلاجة والأدوية حوله، وليس بجانب الجدار أو الباب أو فتحة الهواء.
- **السجلات:** تحفظ ثلاث سنوات، وفيها أدنى وأعلى حرارة والتاريخ والوقت واسم من قام بالفحص وما الإجراء الذي اتخذ عند الانحراف.

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

![ثلاجة أدوية مفتوحة بأرفف شبكية بيضاء، عليها علب كرتون وأكياس وصناديق بلاستيكية فيها عبوات أدوية، وإضاءة صفراء من الأعلى، وعلى الرف العلوي جهاز صغير بشاشة](https://arabroot.io/content/images/2026/11/project-cold-room-01-vaccine-fridge.webp)

ثلاجة لقاحات في دراسة لـ NIST، التي وجدت أن اللقاحات في علبها الكرتونية تحتفظ بحرارتها أطول من اللقاحات المفرغة في الصواني. الصورة: NIST، ملكية عامة Public Domain، المصدر: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Vaccine;%5FTemperature;%5FRefrigerator%5F%285941076542%29.jpg?ref=arabroot.io) (تم تحويلها إلى WebP).

وأما غرفة التبريد فهي غرفة من ألواح معزولة، بباب منزلق أو مفصلي ثقيل، ووحدة تبريد خارجها فيها الضاغط والمراوح، والصورة التالية لباب غرفة تبريد على اليمين، ولوحدة تكثيف Condensing Unit فيها ضواغط على اليسار:

![صورتان: على اليمين باب منزلق أبيض لغرفة تبريد بين ألواح معزولة بيضاء، وأمامه أرضية معدنية مضلعة، وعلى اليسار وحدة تكثيف كبيرة بإطار رمادي مفتوح فيها ضواغط زرقاء وخضراء وأنابيب نحاسية وساعات ضغط](https://arabroot.io/content/images/2026/11/project-cold-room-02-cold-room.webp)

باب غرفة تبريد منزلق، ووحدة تكثيف بضواغطها. الصورتان: Mesadbal، رخصة CC BY 4.0، المصدر: Wikimedia Commons ([الباب](https://commons.wikimedia.org/wiki/File:Cold%5FRoom%5FDoor%5F-%5FSliding%5FDoor.jpg?ref=arabroot.io)، [الوحدة](https://commons.wikimedia.org/wiki/File:Cold%5FRoom%5FCondensing%5FUnit%5F-%5FBitzer%5FCompressor.jpg?ref=arabroot.io)) (تم جمعهما وتحويلهما إلى WebP).

والسؤال الطبيعي الآن: لماذا نبني هذا أصلاً، وهناك أجهزة تسجيل جاهزة تباع لهذا الغرض بالضبط؟ والصورة التالية لواحد منها:

![جهاز تسجيل حرارة صغير رمادي فاتح، عليه شعار testo وعبارة testostor 175 Logger، وفي وجهه غطاء مستطيل وفتحات تهوية، وتحته مسطرة قياس](https://arabroot.io/content/images/2026/11/project-cold-room-03-data-logger.webp)

مسجل حرارة ورطوبة تجاري يعمل على البطارية. الصورة: Cjp24، رخصة CC BY-SA 3.0، المصدر: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Data%5Flogger.jpg?ref=arabroot.io) (تم تحويلها إلى WebP).

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

## القطع: ثلاثة مجسات وباب وصفارة

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

- **مجس الحرارة DS18B20:** ثلاثة مجسات، واحد في وسط كل ثلاجة، وواحد في غرفة التبريد، والنسخة المستخدمة هي المجس المغلف في أنبوب معدني مقاوم للماء بسلك طويل.
- **حساس الباب Reed Switch:** مفتاح مغناطيسي على إطار باب غرفة التبريد، ومغناطيس صغير على الباب نفسه.
- **صفارة Buzzer:** بجانب الباب، تعمل من الجهاز مباشرة.
- **مقاومات 4.7 كيلو أوم:** واحدة لكل مجس، بين سلك البيانات و3.3 فولت.

والصورة التالية للمجس DS18B20 في غلافه المقاوم للماء، ولاحظ الأسلاك الثلاثة في نهايته: الأحمر للطاقة، والأسود للأرضي GND، والثالث للبيانات، ولونه يختلف بين المصنعين، فتأكد منه من ورقة البائع:

![مجس حرارة بأنبوب معدني فضي صغير في نهاية سلك أسود طويل ملفوف على سطح أبيض، وفي الطرف الآخر من السلك ثلاثة أسلاك رفيعة أحمر وأصفر وأسود](https://arabroot.io/content/images/2026/11/project-cold-room-05-ds18b20.webp)

المجس DS18B20 في غلاف معدني مقاوم للماء. الصورة: Leonardo Postay، رخصة CC BY-SA 4.0، المصدر: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Sensor%5FDS18B20.jpg?ref=arabroot.io) (تم تحويلها إلى WebP).

واخترنا DS18B20 لثلاثة أسباب من ورقة بياناته Datasheet: الأول أن مداه من -55 إلى +125 درجة مئوية، ودقته ±0.5 درجة بين -10 و+85، وهي الدقة نفسها التي يوصي بها دليل CDC. والثاني أنه رقمي، يحول الحرارة إلى رقم داخله ويرسله مع رمز تحقق CRC، فالسلك الطويل إلى داخل الثلاجة لا يغير القراءة كما يغير الجهد في حساس تماثلي Analog، وقد شرحنا هذا الفرق في [مقال الأرجل الرقمية والتماثلية](https://arabroot.io/articles/%D8%A7%D9%84%D8%A7%D8%B1%D8%AC%D9%84-%D8%A7%D9%84%D8%B1%D9%82%D9%85%D9%8A%D8%A9-%D9%88%D8%A7%D9%84%D8%AA%D9%85%D8%A7%D8%AB%D9%84%D9%8A%D8%A9-%D9%81%D9%87%D9%85-gpio-%D8%AB%D9%85-pwm-%D9%85%D8%B9-%D9%85%D8%AD%D9%88%D9%84-adc/). والثالث أنه يحتاج سلك بيانات واحد فقط، وهذا مهم لأن السلك يجب أن يمر من إطار باب الثلاجة دون أن يمنع الإغلاق.

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

![أنبوب زجاجي أخضر شفاف طويل بطرفين معدنيين، وفي داخله شريحتان معدنيتان رفيعتان متقابلتان](https://arabroot.io/content/images/2026/11/project-cold-room-07-reed-switch.webp)

مفتاح مغناطيسي Reed Switch: شريحتان معدنيتان في أنبوب زجاجي. الصورة: André Karwath، رخصة CC BY-SA 2.5، المصدر: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Reed%5Fswitch%5F%28aka%29.jpg?ref=arabroot.io) (تم تحويلها إلى WebP).

والتوصيل أن طرفاً من المفتاح على الرجل GPIO27 والطرف الآخر على الأرضي، مع المقاومة الرافعة الداخلية في الشريحة، فعندما يكون الباب مغلقاً والمغناطيس بجانب المفتاح تقرأ الرجل LOW، وعندما يفتح الباب تقرأ HIGH. ولاحظ أن هذا الاختيار مقصود: إذا انقطع سلك الحساس فسوف تقرأ الرجل HIGH، أي «الباب مفتوح»، فيصل تنبيه بعد خمس دقائق ويذهب أحدهم لينظر، وهذا أفضل من العكس، أي سلك مقطوع يقول إن الباب مغلق إلى الأبد.

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

## بروتوكول السلك الواحد 1-Wire

المجس DS18B20 يتكلم بروتوكولاً اسمه السلك الواحد 1-Wire، وهو من تصميم شركة Dallas Semiconductor التي أصبحت جزءاً من Maxim ثم Analog Devices، والفكرة فيه أن سلكاً واحداً يحمل البيانات في الاتجاهين، والمقاومة الرافعة تبقيه HIGH، وكل طرف يتكلم بأن يسحبه إلى LOW لفترة محددة بالميكروثانية. والصورة التالية لقياس حقيقي بمحلل منطق Logic Analyzer على سلك 1-Wire، وفيه نبضة إعادة الضبط Reset ثم رد الجهاز، ثم إرسال بايت، ثم قراءة بايت:

![ثلاثة رسوم توقيت من محلل منطق بعنوان 1 Wire reset, write and read example with DS2432: في الأول نبضة reset طويلة ثم device response، وفي الثاني إرسال البايت 0x33 بتة بتة، وفي الثالث قراءة البايت الأول من الجهاز، وتحت كل رسم أوقات بالميكروثانية](https://arabroot.io/content/images/2026/11/project-cold-room-06-one-wire.webp)

إعادة الضبط ثم الكتابة ثم القراءة على سلك 1-Wire، كما يراها محلل منطق. الصورة: FrankBuss، ملكية عامة Public Domain، المصدر: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:1-Wire-Protocol.png?ref=arabroot.io) (تم تحويلها إلى WebP).

وتوقيت كل نبضة في ورقة بيانات المجس، وفيما يلي ما نحتاجه منها:

- **إعادة الضبط Reset:** المتحكم يسحب السلك LOW مدة 480 ميكروثانية على الأقل، ثم يتركه، والمجس الموجود يرد بنبضة حضور Presence Pulse بأن يسحب السلك LOW مدة بين 60 و240 ميكروثانية. وإذا لم يرد أحد فلا يوجد مجس على السلك، وهذه أول معلومة مهمة لنا: نعرف أن المجس غائب قبل أن نقرأ أي رقم.
- **الكتابة والقراءة:** كل بت في فتحة زمنية Time Slot بين 60 و120 ميكروثانية، والبت 1 نبضة LOW قصيرة، والبت 0 نبضة LOW طويلة، والقراءة نبضة قصيرة من المتحكم ثم ينظر إلى السلك.
- **الأوامر:** Skip ROM بالرقم 0xCC عندما يكون على السلك مجس واحد، وConvert T بالرقم 0x44 لتبدأ القياس، وRead Scratchpad بالرقم 0xBE لقراءة تسعة بايتات آخرها رمز التحقق CRC.
- **زمن التحويل:** 750 ملي ثانية بدقة 12 بت، أي أن المجس يحتاج قرابة ثانية بعد أمر القياس.

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

### المشغل Driver كما كتبناه

هناك مكتبات جاهزة لهذا المجس، ولكننا كتبنا المشغل بأنفسنا في أقل من سبعين سطراً، لأن البروتوكول بسيط، ولأننا نريد أن نعرف بالضبط ماذا يرجع المشغل في كل حالة فشل. والملف `probes.c` فيه الجزءان: المشغل الحقيقي للوحة، والصيدلية المحاكاة التي يعمل بها البرنامج نفسه على QEMU:

```c
#include "probes.h"
#include <math.h>
#include "driver/gpio.h"

const char *const PROBE_NAME[NPROBES] = { "fridge-1", "fridge-2", "room" };

#define PIN_DOOR   GPIO_NUM_27   // reed switch to GND: closed (LOW) while the magnet on the door is next to it
#define PIN_BUZZER GPIO_NUM_25

#ifndef SENSOR_SIM
// ---- Real board: one DS18B20 per GPIO, each with its own 4.7k pull-up to 3.3 V --------------------------------
// One probe per pin costs pins but buys isolation: a cut or wet cable takes down one fridge, not the whole bus,
// and no ROM addresses to record when a probe is replaced.
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_rom_sys.h"

static const gpio_num_t PIN_PROBE[NPROBES] = { GPIO_NUM_4, GPIO_NUM_16, GPIO_NUM_17 };
static portMUX_TYPE ow_lock = portMUX_INITIALIZER_UNLOCKED;   // 1-Wire slots are timed in microseconds

static void ow_low(gpio_num_t p)     { gpio_set_level(p, 0); }
static void ow_release(gpio_num_t p) { gpio_set_level(p, 1); }   // open drain: 1 = let the pull-up raise the line

// Reset pulse: master low for 480 us, then a present DS18B20 pulls the line low for 60-240 us (datasheet, Figure 11)
static bool ow_reset(gpio_num_t p) {
    portENTER_CRITICAL(&ow_lock);
    ow_low(p); esp_rom_delay_us(480);
    ow_release(p); esp_rom_delay_us(70);
    bool present = gpio_get_level(p) == 0;
    portEXIT_CRITICAL(&ow_lock);
    esp_rom_delay_us(410);
    return present;
}
static void ow_write(gpio_num_t p, uint8_t b) {
    for (int i = 0; i < 8; i++, b >>= 1) {
        portENTER_CRITICAL(&ow_lock);
        ow_low(p);
        if (b & 1) { esp_rom_delay_us(6); ow_release(p); esp_rom_delay_us(64); }   // write 1: short low
        else       { esp_rom_delay_us(60); ow_release(p); esp_rom_delay_us(10); }  // write 0: low for the whole slot
        portEXIT_CRITICAL(&ow_lock);
    }
}
static uint8_t ow_read(gpio_num_t p) {
    uint8_t b = 0;
    for (int i = 0; i < 8; i++) {
        portENTER_CRITICAL(&ow_lock);
        ow_low(p); esp_rom_delay_us(6); ow_release(p); esp_rom_delay_us(9);
        if (gpio_get_level(p)) b |= 1 << i;
        portEXIT_CRITICAL(&ow_lock);
        esp_rom_delay_us(55);
    }
    return b;
}
// CRC = X^8 + X^5 + X^4 + 1, the polynomial in the datasheet
static uint8_t crc8(const uint8_t *d, int n) {
    uint8_t crc = 0;
    while (n--) {
        uint8_t in = *d++;
        for (int i = 0; i < 8; i++, in >>= 1) {
            uint8_t mix = (crc ^ in) & 1;
            crc >>= 1;
            if (mix) crc ^= 0x8C;
        }
    }
    return crc;
}

void io_init(void) {
    for (int i = 0; i < NPROBES; i++) {
        gpio_set_direction(PIN_PROBE[i], GPIO_MODE_INPUT_OUTPUT_OD);
        ow_release(PIN_PROBE[i]);
    }
    gpio_set_direction(PIN_DOOR, GPIO_MODE_INPUT);
    gpio_set_pull_mode(PIN_DOOR, GPIO_PULLUP_ONLY);
    gpio_set_direction(PIN_BUZZER, GPIO_MODE_OUTPUT);
    gpio_set_level(PIN_BUZZER, 0);
}
void io_tick(int minute) { (void)minute; }

void probes_convert(void) {
    for (int i = 0; i < NPROBES; i++)
        if (ow_reset(PIN_PROBE[i])) { ow_write(PIN_PROBE[i], 0xCC); ow_write(PIN_PROBE[i], 0x44); }  // Skip ROM, Convert T
    vTaskDelay(pdMS_TO_TICKS(750));                                     // tCONV at 12-bit resolution
}

int probe_read(int i, float *celsius) {
    gpio_num_t p = PIN_PROBE[i];
    uint8_t s[9];
    if (!ow_reset(p)) return PROBE_NO_DEVICE;                           // nobody answered: cable cut or unplugged
    ow_write(p, 0xCC); ow_write(p, 0xBE);                               // Skip ROM, Read Scratchpad
    for (int k = 0; k < 9; k++) s[k] = ow_read(p);
    if (crc8(s, 8) != s[8]) return PROBE_CRC;                           // noise on a long cable
    int16_t raw = (int16_t)(s[1] << 8 | s[0]);
    *celsius = raw / 16.0f;
    if (raw == 0x0550) return PROBE_POWER_ON;                           // +85 C: the power-on value, no conversion done
    return PROBE_OK;
}

bool door_open(void) { return gpio_get_level(PIN_DOOR) == 1; }
void buzzer(bool on) { gpio_set_level(PIN_BUZZER, on); }

#else
// ---- Simulated pharmacy, minute by minute --------------------------------------------------------------------------
//  fridge-1: steady around 4.6 C
//  fridge-2: its first reading after power-up is the +85 C power-on value; at minute 60 its cable is pulled out
//  room    : the door is left open from minute 15 to 22 (warm air, the probe rises above 8 C for a few minutes),
//            then at minute 50 the compressor stops and the room warms 0.2 C a minute
static int now_min = -1;
static float room = 4.8f;
static bool first_read_f2 = true;

void io_init(void) {}
static bool door_is_open(int m) { return m >= 15 && m < 22; }
void io_tick(int minute) {
    for (int m = now_min + 1; m <= minute; m++) {
        if (door_is_open(m))  room += (9.8f - room) * 0.35f;             // warm air rushes in
        else if (m >= 50)     room += 0.2f;                              // compressor stopped
        else                  room += (4.8f - room) * 0.3f;              // the cooling pulls it back
    }
    now_min = minute;
}
void probes_convert(void) {}
int probe_read(int i, float *c) {
    float wobble = 0.1f * sinf(now_min * 0.7f + i);                      // small, repeatable noise
    if (i == 0) { *c = 4.6f + wobble; return PROBE_OK; }
    if (i == 1) {
        if (now_min >= 60) return PROBE_NO_DEVICE;
        if (first_read_f2) { first_read_f2 = false; *c = 85.0f; return PROBE_POWER_ON; }
        *c = 5.0f + wobble; return PROBE_OK;
    }
    *c = room + wobble;
    return PROBE_OK;
}
bool door_open(void) { return door_is_open(now_min); }
void buzzer(bool on) { (void)on; }
#endif
```

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

- الرجل في وضع المصرف المفتوح Open Drain، فالمتحكم يستطيع أن يسحب السلك LOW، ولكنه عندما يكتب 1 فهو يترك السلك للمقاومة الرافعة، ولا يدفعه HIGH، وبالتالي لا يتعارك مع المجس عندما يرد.
- كل فتحة زمنية داخل منطقة حرجة Critical Section، لأن مقاطعة Interrupt من Wi-Fi في منتصف نبضة طولها 6 ميكروثانية تغير معنى البت.
- الدالة `probe_read` ترجع أربع حالات وليس رقماً فقط: مجس غائب، أو بيانات تالفة لم تطابق CRC، أو القيمة +85، أو قراءة سليمة.
- الصيدلية المحاكاة فيها كل ما سنختبره: الباب مفتوح من الدقيقة 15 إلى 22، والضاغط يتوقف في الدقيقة 50، والمجس الثاني يقرأ +85 في أول قراءة بعد التشغيل، ثم ينفصل سلكه في الدقيقة 60.

### قراءتان يجب ألا تصدقهما

الحالة الأولى هي الرقم +85 بالضبط، والسبب في ورقة البيانات نفسها: قيمة سجل الحرارة عند التشغيل Power-on Reset هي +85 درجة مئوية، أي أن المجس الذي فقد الكهرباء لحظة ثم عادت، أو الذي قرأته قبل أن ينهي أول قياس، يرجع 85 كأنها قراءة حقيقية. وثلاجة الأدوية لا تصل إلى 85 درجة في أي ظرف، ولكن البرنامج الذي يصدق هذا الرقم سوف يرسل تنبيه انحراف حراري، ويكتب في السجل الرسمي أن الثلاجة كانت 85 درجة، وهو رقم سوف يسألك عنه المفتش. ولهذا البرنامج الثابت إذا رأى +85 بالضبط يطلب قياساً جديداً مرة واحدة قبل أن يقرر.

والحالة الثانية المجس الغائب، ومن يستخدم مكتبة DallasTemperature المشهورة في Arduino يعرف هذه الحالة بالرقم -127، فهذه هي القيمة التي تعرفها المكتبة باسم `DEVICE_DISCONNECTED_C` لتعني أن المجس لم يرد. والخطأ الذي نراه كثيراً أن يرسل البرنامج هذا الرقم كما هو، فتظهر في لوحة المتابعة حرارة -127، وتطلق قاعدة الحد الأدنى تنبيه «الثلاجة متجمدة». والحل الأنسب ألا تكون هناك قيمة رقمية أصلاً: المجس الغائب يصبح `null` في الرسالة، وحدثاً منفصلاً اسمه `probe_missing`، فالعطل عطل والحرارة حرارة، ولا يختلط أحدهما بالآخر في أي جدول.

## لا يضيع شيء: التخزين والإرسال في الجهاز

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

- **كل قراءة وكل حدث يدخل الحلقة أولاً:** مخزن دائري Ring Buffer في ذاكرة الجهاز يتسع لـ 1440 سجلاً، أي يوماً كاملاً بقراءة كل دقيقة، ولكل سجل رقم تسلسلي Sequence Number يزيد واحداً، ودقيقة القراءة، ووقتها الحقيقي إذا كانت ساعة الجهاز مضبوطة.
- **السجل لا يخرج من الحلقة إلا بإقرار:** مهمة مستقلة في البرنامج ترسل أقدم سجل بمستوى التسليم QoS 1، وتنتظر رسالة الإقرار PUBACK من الوسيط، وعندها فقط تنتقل إلى السجل التالي، وإذا لم يصل الإقرار خلال ثلاث ثوان أرسلت السجل نفسه مرة أخرى.

والشكل التالي يبين الحلقة في ثلاث لحظات: والوسيط يعمل، ثم وهو متوقف، ثم بعد عودته:

![ثلاثة صفوف من عشرة مربعات مرقمة: الأول الوسيط يعمل، المربعات 40 إلى 43 رمادية والمربع 44 برتقالي ينتظر، والثاني الوسيط متوقف، المربعان 42 و43 رماديان والمربعات 44 إلى 50 برتقالية تنتظر، والثالث بعد العودة، المربعات 46 إلى 50 رمادية والمربع 51 برتقالي، وتحت كل صف كلمتا tail وhead، وفي الأسفل مفتاح: رمادي وصل وأقره الوسيط، وبرتقالي ينتظر في الحلقة](https://arabroot.io/content/images/2026/11/project-cold-room-09-ring.webp)

الحلقة في الجهاز: السجلات تتجمع وقت الانقطاع، ثم تخرج بالترتيب بأرقامها الأصلية

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

والسؤال الثاني: ماذا لو امتلأت الحلقة؟ الحلقة تتسع ليوم كامل، وإذا انقطعت الشبكة أكثر من يوم فالقرار في الكود أن يحذف الأقدم ويعد كم سجلاً حذف، ويرسل هذا العدد في كل رسالة باسم `dropped`، فيظهر في التقرير أن السجل ناقص وبكم، بدل أن يختفي النقص بصمت. وإذا كان العميل يحتاج أكثر من يوم فالحل أن تكتب الحلقة في ذاكرة الفلاش Flash، مع الانتباه إلى عدد مرات الكتابة التي تتحملها الذاكرة.

والملف `main.c` فيه الحلقة والمرسل وحلقة القراءة الرئيسية:

```c
// Cold-chain node for a pharmacy: two medicine fridges and a cold room on one ESP32.
//  - reads three DS18B20 probes every minute; a probe that does not answer, fails its CRC, or returns the +85 C
//    power-on value is never reported as a temperature
//  - cold room door: sounds the local buzzer after 5 minutes open, without waiting for any server
//  - every reading and event goes into a ring buffer with a sequence number first, and only leaves it when the broker
//    has acknowledged it (QoS 1, PUBACK). A broker or network outage delays the data, it does not lose it.
#include <stdio.h>
#include <string.h>
#include <time.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.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 "probes.h"
#ifndef SENSOR_SIM
#include "esp_sntp.h"
#endif

static const char *TAG = "cold";

#define NODE        "pharmacy-1/node-1"
#define BROKER_URI  "mqtt://10.0.2.2:1883"   // under QEMU: the machine running it; on a real board your broker
#define DOOR_ALARM_MIN 5                     // minutes open before the buzzer and the event
#define RING        1440                     // one day of readings at one a minute (44 bytes each, about 63 KB of RAM)
#define MINUTES(m)  pdMS_TO_TICKS((m) * 60000 / SCALE)

// One record in the ring: a reading of all probes, or an event. NO_TEMP marks a probe without a valid reading.
#define NO_TEMP INT16_MIN
typedef struct {
    uint32_t seq, minute, ts;      // ts: Unix time from SNTP on a real board, 0 when the clock is not set
    int16_t  t10[NPROBES];         // tenths of a degree
    uint8_t  door, is_event;
    char     what[22];             // event name
    int8_t   probe;                // event: which probe, or -1
} rec_t;

static rec_t ring[RING];
static uint32_t head, tail, next_seq, dropped;   // head: next free slot, tail: oldest not yet acknowledged
static SemaphoreHandle_t ring_lock, acked;
static volatile int last_acked = -1;            // msg_id of the latest PUBACK
static volatile bool connected;
static esp_mqtt_client_handle_t mq;
static int minute_now;

static uint32_t now_ts(void) { time_t t = time(NULL); return t > 1700000000 ? (uint32_t)t : 0; }

static void push(rec_t *r) {
    xSemaphoreTake(ring_lock, portMAX_DELAY);
    r->seq = next_seq++;
    r->minute = minute_now;
    r->ts = now_ts();
    if (head - tail == RING) { tail++; dropped++; }      // full: the oldest record is lost, and we count it
    ring[head % RING] = *r;
    head++;
    xSemaphoreGive(ring_lock);
}

static void event(const char *what, int probe) {
    rec_t r = { .is_event = 1, .probe = probe };
    snprintf(r.what, sizeof r.what, "%s", what);
    ESP_LOGW(TAG, "event %s%s%s", what, probe >= 0 ? " " : "", probe >= 0 ? PROBE_NAME[probe] : "");
    push(&r);
}

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) {
        connected = true;
        ESP_LOGI(TAG, "connected, %lu record(s) waiting in the ring", (unsigned long)(head - tail));
        esp_mqtt_client_publish(mq, "coldchain/" NODE "/status", "online", 0, 1, 1);
    } else if (id == MQTT_EVENT_DISCONNECTED) {
        if (connected) ESP_LOGW(TAG, "broker lost, keeping records in the ring");
        connected = false;
    } else if (id == MQTT_EVENT_PUBLISHED) {
        last_acked = e->msg_id;                          // PUBACK: may arrive before publish() even returns
        xSemaphoreGive(acked);
    }
}

static int format(const rec_t *r, char *topic, char *json) {
    int n;
    if (r->is_event) {
        sprintf(topic, "coldchain/" NODE "/event");
        n = sprintf(json, "{\"seq\":%lu,\"min\":%lu,\"ts\":%lu,\"now\":%d,\"event\":\"%s\",\"probe\":%s%s%s}",
                    (unsigned long)r->seq, (unsigned long)r->minute, (unsigned long)r->ts, minute_now, r->what,
                    r->probe >= 0 ? "\"" : "", r->probe >= 0 ? PROBE_NAME[r->probe] : "null", r->probe >= 0 ? "\"" : "");
        return n;
    }
    sprintf(topic, "coldchain/" NODE "/reading");
    n = sprintf(json, "{\"seq\":%lu,\"min\":%lu,\"ts\":%lu,\"now\":%d,\"door\":%d,\"t\":{",
                (unsigned long)r->seq, (unsigned long)r->minute, (unsigned long)r->ts, minute_now, r->door);
    for (int i = 0; i < NPROBES; i++) {
        if (r->t10[i] == NO_TEMP) n += sprintf(json + n, "%s\"%s\":null", i ? "," : "", PROBE_NAME[i]);
        else n += sprintf(json + n, "%s\"%s\":%.1f", i ? "," : "", PROBE_NAME[i], r->t10[i] / 10.0);
    }
    return n + sprintf(json + n, "},\"dropped\":%lu}", (unsigned long)dropped);
}

// Sender: oldest record first; it leaves the ring only after the broker's PUBACK.
static void sender(void *arg) {
    char topic[64], json[256];
    for (;;) {
        if (!connected || head == tail) { vTaskDelay(pdMS_TO_TICKS(50)); continue; }
        xSemaphoreTake(ring_lock, portMAX_DELAY);
        rec_t r = ring[tail % RING];
        xSemaphoreGive(ring_lock);
        format(&r, topic, json);
        int id = esp_mqtt_client_publish(mq, topic, json, 0, 1, 0);
        TickType_t until = xTaskGetTickCount() + pdMS_TO_TICKS(3000);
        while (id > 0 && last_acked != id && xTaskGetTickCount() < until)
            xSemaphoreTake(acked, pdMS_TO_TICKS(100));
        if (id > 0 && last_acked == id) {
            xSemaphoreTake(ring_lock, portMAX_DELAY);
            if (ring[tail % RING].seq == r.seq) tail++;    // still the oldest (not dropped meanwhile)
            xSemaphoreGive(ring_lock);
        } else {
            vTaskDelay(pdMS_TO_TICKS(200));               // no PUBACK: try the same record again
        }
    }
}

void app_main(void) {
    ESP_ERROR_CHECK(nvs_flash_init());
    ESP_ERROR_CHECK(esp_netif_init());
    ESP_ERROR_CHECK(esp_event_loop_create_default());
    io_init();
    buzzer(false);
    ring_lock = xSemaphoreCreateMutex();
    acked = xSemaphoreCreateBinary();
    ESP_ERROR_CHECK(example_connect());
#ifndef SENSOR_SIM
    esp_sntp_setoperatingmode(ESP_SNTP_OPMODE_POLL);      // real time for the inspector's report
    esp_sntp_setservername(0, "pool.ntp.org");
    esp_sntp_init();
#endif
    esp_mqtt_client_config_t cfg = {
        .broker.address.uri = BROKER_URI,
        .credentials.client_id = "cold-node-1",
        .session.last_will = { .topic = "coldchain/" NODE "/status", .msg = "offline", .qos = 1, .retain = 1 },
        .session.keepalive = 30,
        .network.reconnect_timeout_ms = 1000,
    };
    mq = esp_mqtt_client_init(&cfg);
    esp_mqtt_client_register_event(mq, ESP_EVENT_ANY_ID, on_mqtt, NULL);
    esp_mqtt_client_start(mq);
    xTaskCreate(sender, "sender", 4096, NULL, 5, NULL);

    bool fault[NPROBES] = { 0 };
    int open_for = 0;
    bool alarm = false;
    for (minute_now = 0;; minute_now++) {
        io_tick(minute_now);
        probes_convert();
        rec_t r = { .door = door_open() };
        for (int i = 0; i < NPROBES; i++) {
            float c;
            int st = probe_read(i, &c);
            if (st == PROBE_POWER_ON) {                  // +85 C right after power-up: convert again, once
                ESP_LOGW(TAG, "%s: +85.0 C is the power-on value, converting again", PROBE_NAME[i]);
                probes_convert();
                st = probe_read(i, &c);
            }
            r.t10[i] = st == PROBE_OK ? (int16_t)(c * 10 + (c >= 0 ? 0.5f : -0.5f)) : NO_TEMP;
            if (st != PROBE_OK && !fault[i]) { fault[i] = true; event(st == PROBE_NO_DEVICE ? "probe_missing" : "probe_bad_data", i); }
            if (st == PROBE_OK && fault[i])  { fault[i] = false; event("probe_ok", i); }
        }
        push(&r);
        if (minute_now % 10 == 0) {
            char line[96];
            int n = sprintf(line, "min %d:", minute_now);
            for (int i = 0; i < NPROBES; i++)
                n += r.t10[i] == NO_TEMP ? sprintf(line + n, " %s=--", PROBE_NAME[i]) : sprintf(line + n, " %s=%.1f", PROBE_NAME[i], r.t10[i] / 10.0);
            ESP_LOGI(TAG, "%s door=%d ring=%lu", line, r.door, (unsigned long)(head - tail));
        }

        open_for = r.door ? open_for + 1 : 0;
        if (open_for == DOOR_ALARM_MIN) { buzzer(true); alarm = true; event("door_open_long", 2); }
        if (!r.door && alarm)           { buzzer(false); alarm = false; event("door_closed", 2); }
        vTaskDelay(MINUTES(1));
    }
}
```

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

- كل رسالة تحمل حقلين للوقت: `min` دقيقة القراءة، و`now` دقيقة الجهاز عند الإرسال، والفرق بينهما يخبر خدمة الاستقبال أن هذه القراءة متأخرة وبكم، دون أن تحتاج ساعة الجهاز.
- الحقل `ts` هو الوقت الحقيقي، ويأتي على اللوحة الحقيقية من SNTP، وقد شرحنا مشكلة الوقت بين الجهاز والسيرفر في [مقال إنترنت الأشياء](https://arabroot.io/articles/%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D9%85%D9%86-%D8%A7%D9%84%D8%AD%D8%B3%D8%A7%D8%B3-%D8%A7%D9%84%D9%89-%D9%84%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%AA%D8%A7%D8%A8%D8%B9%D8%A9/). وفي المختبر لا توجد ساعة مضبوطة، فقيمته صفر، والتقرير يعرض الدقيقة صفر على أنها الساعة 08:00.
- الصفارة تعمل من حلقة القراءة نفسها، قبل أي اتصال بالشبكة.
- رسالة الوصية Last Will هي `offline`، يرسلها الوسيط نيابة عن الجهاز إذا انقطع اتصاله دون وداع.
- إعادة الاتصال كل ثانية `reconnect_timeout_ms`، وفي المختبر الثانية دقيقة من وقت الصيدلية.

## خدمة الاستقبال: القرار على السيرفر

الجهاز يجمع ويرسل، والقرارات التي تحتاج تاريخاً كاملاً أو إنساناً تعيش على السيرفر، وأولها قاعدة الانحراف الحراري Excursion. والقاعدة البسيطة «إذا تجاوزت القراءة 8 درجات أرسل تنبيهاً» لن تبقى أسبوعاً، لأن كل من يفتح باب غرفة التبريد ليأخذ صندوقاً يرفع حرارة الهواء حول المجس دقائق، فيصل تنبيه، ثم آخر، وبعد أسبوع يتعلم الصيدلي أن يتجاهل التنبيهات كلها، وهذا أخطر من عدم وجود تنبيه، لأن التنبيه الحقيقي سوف يأتي يوماً ويتجاهله أيضاً. وقد ناقشنا هذا المعنى بالتفصيل في [مقال التنبيهات Alerting](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D9%86%D8%A8%D9%8A%D9%87%D8%A7%D8%AA-alerting-%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D9%86%D8%A8%D9%87-%D8%B9%D9%84%D9%8A%D9%87-%D9%88%D9%85%D8%AA%D9%89-%D8%AA%D9%88%D9%82%D8%B8-%D8%A7%D8%AD%D8%AF%D8%A7/)، والقاعدة هنا أن تنبه على شيء يحتاج إنساناً، وأن تنظر إلى المدة: خارج المدى من 2 إلى 8 لعشر دقائق متتالية. وهذا يكمل المجس المعزول الذي يوصي به دليل CDC ولا يحل محله، فالمجس يبطئ تغير القراءة، والقاعدة تتجاهل ما يبقى أقل من عشر دقائق.

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

وفيما يلي بقية ما تقوم به الخدمة:

- **حذف المكرر وكشف الفجوة:** رقم تسلسلي أقل من أو يساوي آخر رقم يهمل، ورقم أكبر من المتوقع يعني سجلات لم تصل أبداً، فتحفظ الفجوة في جدول مستقل.
- **التنبيه مع زر إقرار:** كل تنبيه يذهب إلى تطبيق ntfy على جوال الصيدلي بأولوية 4، ومعه زر Acknowledge يرسل طلب POST إلى الخدمة، فتحفظ من أقر ومتى، وهو بالضبط ما يطلبه السجل: من رأى المشكلة وماذا فعل.
- **التصعيد Escalation:** تنبيه مفتوح لم يقر به أحد خلال عشر دقائق من إرساله يذهب إلى موضوع المدير بأعلى أولوية 5، لأن الصيدلي قد يكون مشغولاً أو جواله صامتاً، والمخزون لا ينتظر.
- **المراقبة من جهة السيرفر Watchdog:** رسالة الوصية تصل فقط إذا كان الوسيط يعمل، فإذا توقف الوسيط نفسه أو انقطعت الشبكة كلها فلن يخبرك أحد، ولهذا الخدمة تنظر إلى الساعة: لا بيانات خمس دقائق تعني تنبيه «لا بيانات»، دون أن تعرف السبب.

والتطبيق ntfy خادم تنبيهات مفتوح المصدر تستطيع أن تشغله على سيرفرك، وله تطبيق على Android وiOS، ويرسل له أي برنامج تنبيهاً بطلب HTTP بسيط، وتوثيقه يحدد خمس درجات للأولوية من 1 إلى 5، والدرجة 5 اهتزاز طويل ونافذة منبثقة. والأزرار في التنبيه ميزة موثقة فيه باسم Actions، ومنها زر http يرسل طلباً إلى عنوان تحدده. وانتبه إلى أن العنوان في المختبر `http://ingest:8080` لا يصل إليه الجوال، لأنه اسم داخل شبكة Docker، وفي النظام الحقيقي يكون عنواناً عاماً عليه HTTPS ومصادقة، وإلا استطاع أي شخص أن يقر بتنبيهات الصيدلية.

والملف `ingest.py` كما يلي:

```python
"""Ingest for the pharmacy cold chain.
- stores every reading and event in SQLite, once: QoS 1 may deliver a record twice, the sequence number keeps one copy
- notices gaps in the sequence numbers (records that never arrived) and late records (sent from the node's ring)
- excursion rule: a location outside 2..8 C for 10 minutes in a row, judged on the node's minutes, not on arrival time
- every alert goes to the phone with an Acknowledge button; an alert nobody acknowledged in 10 minutes is escalated
- a watchdog that does not need the node: no data for 5 minutes means something between the node and us is down"""
import json, os, re, sqlite3, threading, time, urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import paho.mqtt.client as mqtt

SCALE = int(os.environ.get("SCALE", "1"))        # the lab runs the pharmacy 60x faster
LOW, HIGH, HOLD_MIN, ESCALATE_MIN, SILENT_MIN = 2.0, 8.0, 10, 10, 5
DB = sqlite3.connect("/data/coldchain.db", check_same_thread=False)
LOCK = threading.Lock()
DB.executescript("""
CREATE TABLE IF NOT EXISTS reading(node TEXT, seq INT, min INT, ts INT, loc TEXT, temp REAL, door INT, lag INT,
                                   PRIMARY KEY(node, seq, loc));
CREATE TABLE IF NOT EXISTS event(node TEXT, seq INT, min INT, what TEXT, probe TEXT, PRIMARY KEY(node, seq));
CREATE TABLE IF NOT EXISTS alert(id INTEGER PRIMARY KEY, node TEXT, loc TEXT, kind TEXT, min INT, notified_min INT, end_min INT,
                                 peak REAL, acked_by TEXT, acked_min INT, escalated INT DEFAULT 0);
CREATE TABLE IF NOT EXISTS gap(node TEXT, from_seq INT, to_seq INT);
""")
last_seq, out_since, open_excursion, now_min = {}, {}, {}, {"v": 0}
last_arrival, silent = {"t": None}, {"v": False}

def notify(topic, title, body, prio, alert_id=None):
    headers = {"Title": title, "Priority": str(prio), "Tags": "thermometer"}
    if alert_id:   # a button on the phone that calls back this service
        headers["Actions"] = f"http, Acknowledge, http://ingest:8080/ack/{alert_id}, method=POST, clear=true"
    req = urllib.request.Request(f"http://ntfy/{topic}", data=body.encode(), headers=headers)
    urllib.request.urlopen(req, timeout=5).read()
    print(f"notify [{topic} p{prio}] {title}: {body}", flush=True)

def open_alert(node, loc, kind, minute, notified, text, peak=None, body=None):
    cur = DB.execute("INSERT INTO alert(node, loc, kind, min, notified_min, peak) VALUES(?,?,?,?,?,?)",
                     (node, loc, kind, minute, notified, peak))
    notify("coldchain", text, f"{body or loc + ', minute ' + str(minute)}. Alert #{cur.lastrowid}", 4, cur.lastrowid)
    return cur.lastrowid

def check_escalation(minute):
    for aid, loc, kind, m in DB.execute("SELECT id, loc, kind, notified_min FROM alert WHERE acked_by IS NULL AND escalated = 0 "
                                        "AND end_min IS NULL").fetchall():
        if minute - m >= ESCALATE_MIN:
            DB.execute("UPDATE alert SET escalated = 1 WHERE id = ?", (aid,))
            notify("coldchain-manager", f"Not acknowledged: {kind}",
                   f"{loc}: alert #{aid} sent at minute {m}, nobody acknowledged it in {ESCALATE_MIN} minutes", 5)

def on_reading(node, r):
    lag = r["now"] - r["min"]
    for loc, t in r["t"].items():
        DB.execute("INSERT INTO reading VALUES(?,?,?,?,?,?,?,?)", (node, r["seq"], r["min"], r["ts"], loc, t, r["door"], lag))
        if t is None:
            continue                                   # a probe fault is an event, not a temperature
        key = (node, loc)
        if LOW <= t <= HIGH:
            out_since.pop(key, None)
            aid = open_excursion.pop(key, None)
            if aid:
                DB.execute("UPDATE alert SET end_min = ? WHERE id = ?", (r["min"], aid))
                notify("coldchain", "Back in range", f"{loc} at {t} C, minute {r['min']}. Alert #{aid} closed", 3)
            continue
        since = out_since.setdefault(key, r["min"])
        if key in open_excursion:
            DB.execute("UPDATE alert SET peak = MAX(peak, ?) WHERE id = ?", (t, open_excursion[key]))
        elif r["min"] - since >= HOLD_MIN:
            open_excursion[key] = open_alert(node, loc, "excursion", since, r["min"],
                                             f"Excursion: {loc} outside 2-8 C for {HOLD_MIN} min", t,
                                             f"{loc} at {t} C, outside since minute {since}")
    now_min["v"] = max(now_min["v"], r["now"])
    check_escalation(r["now"])

def on_event(node, e):
    DB.execute("INSERT INTO event VALUES(?,?,?,?,?)", (node, e["seq"], e["min"], e["event"], e["probe"]))
    print(f"event {node} seq={e['seq']} min={e['min']} {e['event']} {e['probe'] or ''}", flush=True)
    if e["event"] == "door_open_long":
        open_alert(node, e["probe"], "door", e["min"], e["min"], "Cold room door open for 5 min")
    elif e["event"] in ("probe_missing", "probe_bad_data"):
        open_alert(node, e["probe"], "probe", e["min"], e["min"], f"Probe fault: {e['probe']} ({e['event']})")
    elif e["event"] in ("door_closed", "probe_ok"):
        DB.execute("UPDATE alert SET end_min = ? WHERE node = ? AND loc = ? AND end_min IS NULL AND kind = ?",
                   (e["min"], node, e["probe"], "door" if e["event"] == "door_closed" else "probe"))

def on_message(c, u, m):
    parts = m.topic.split("/")                         # coldchain/<site>/<node>/<kind>
    node, kind = parts[1] + "/" + parts[2], parts[3]
    with LOCK:
        last_arrival["t"] = time.time()
        if silent["v"]:
            silent["v"] = False
            notify("coldchain", "Data resumed", f"{node} is sending again", 3)
        if kind == "status":
            print(f"status {node} = {m.payload.decode()}{' (retained)' if m.retain else ''}", flush=True)
            if m.payload == b"offline" and not m.retain:   # a retained status is old state, not news
                notify("coldchain", "Node offline", f"{node} lost its connection (last will)", 4)
            return
        r = json.loads(m.payload)
        seq, prev = r["seq"], last_seq.get(node)
        if prev is not None and seq <= prev:
            print(f"duplicate {node} seq={seq} ignored", flush=True)
            return
        if prev is not None and seq != prev + 1:
            DB.execute("INSERT INTO gap VALUES(?,?,?)", (node, prev + 1, seq - 1))
            print(f"GAP {node}: seq {prev + 1}..{seq - 1} never arrived", flush=True)
        last_seq[node] = seq
        if r["now"] - r["min"] >= 2:
            print(f"late {node} seq={seq} min={r['min']} arrived at node minute {r['now']}", flush=True)
        (on_event if kind == "event" else on_reading)(node, r)
        DB.commit()
        open("/data/minute", "w").write(str(now_min["v"]))

def watchdog():
    while True:
        time.sleep(0.5)
        with LOCK:
            if last_arrival["t"] and not silent["v"] and time.time() - last_arrival["t"] > SILENT_MIN * 60 / SCALE:
                silent["v"] = True
                notify("coldchain", "No data", f"nothing from the cold chain for {SILENT_MIN} min: node, network or broker", 4)

class Ack(BaseHTTPRequestHandler):
    def do_POST(self):
        m = re.fullmatch(r"/ack/(\d+)(?:\?by=(\w+))?", self.path)
        with LOCK:
            row = m and DB.execute("SELECT loc, kind FROM alert WHERE id = ?", (int(m.group(1)),)).fetchone()
            if row:
                DB.execute("UPDATE alert SET acked_by = ?, acked_min = ? WHERE id = ?",
                           (m.group(2) or "phone", now_min["v"], int(m.group(1))))
                DB.commit()
        self.send_response(200 if row else 404)
        self.end_headers()
        text = f"alert #{m.group(1)} ({row[1]}, {row[0]}) acknowledged at minute {now_min['v']}\n" if row else "no such alert\n"
        self.wfile.write(text.encode())
        print(text.strip(), flush=True)
    def log_message(self, *a):
        pass

threading.Thread(target=watchdog, daemon=True).start()
threading.Thread(target=ThreadingHTTPServer(("", 8080), Ack).serve_forever, daemon=True).start()
c = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="coldchain-ingest", clean_session=False)
c.reconnect_delay_set(1, 2)                            # come back fast after the broker returns
c.on_connect = lambda c, u, f, rc, p: c.subscribe("coldchain/#", qos=1)
c.on_message = on_message
while True:
    try:
        c.connect("net", 1883)
        break
    except OSError:
        time.sleep(1)
c.loop_forever()
```

والشكل التالي يجمع المشروع كله، من المجس إلى جوال الصيدلي ثم المدير:

![خمس بطاقات من اليمين: الصيدلية فيها غرفة تبريد وثلاثة مجسات DS18B20 وحساس باب ولوحة ESP32 مع صفارة وحلقة 1440، ثم الوسيط Mosquitto بمستوى QoS 1 وعبارة كل سجل يبقى في الحلقة حتى يصل إقرار PUBACK، ثم خدمة الاستقبال ingest.py مع SQLite وقائمة حذف المكرر بالرقم التسلسلي وكشف الفجوات وخارج 2 إلى 8 لعشر دقائق وتصعيد بعد عشر دقائق دون إقرار وتقرير يومي CSV، ثم التنبيهات ntfy مع زر إقرار يعود إلى خدمة الاستقبال، ثم جوالان: الصيدلي بأولوية 4 والمدير بأولوية 5، وسهم من الجوال إلى خدمة الاستقبال عليه Acknowledge POST /ack، وفي الأسفل: الصفارة عند الباب تعمل دون أي شبكة والقراءات تنتظر في الجهاز إذا توقف الوسيط، وخدمة الاستقبال تعرف الانقطاع بنفسها](https://arabroot.io/content/images/2026/11/project-cold-room-04-system.webp)

المشروع كاملاً: كل طبقة تعرف ماذا تفعل عندما تتعطل الطبقة التي قبلها

## المختبر: الصيدلية كاملة على جهازك

المختبر خمس حاويات في Docker Compose: الوسيط Mosquitto، وخادم التنبيهات ntfy، وخدمة الاستقبال، وحاوية ESP-IDF التي تبني البرنامج الثابت وتشغله على QEMU، وحاوية صغيرة اسمها `net` تملك مساحة الشبكة Network Namespace التي يشترك فيها الوسيط والبرنامج الثابت. والسبب في هذه الحاوية الأخيرة أننا سوف نوقف الوسيط في منتصف التجربة، ولو كان الوسيط هو صاحب الشبكة لأخذ شبكة QEMU معه، وأما بهذا الشكل فالوسيط يتوقف ويعود والجهاز المحاكى لا يرى إلا أن الطرف الآخر لم يعد يرد، كما يحدث عندما يعاد تشغيل سيرفر حقيقي. والملف `compose.yaml` كما يلي:

```yaml
# Pharmacy cold chain lab: the ESP32 firmware in QEMU, the broker, ntfy for phone notifications, and the ingest service.
name: coldchain
services:
  net:
    # owns the network namespace that the broker and the firmware share, so the broker can be stopped and started
    # (the outage experiment) without taking the firmware's network down with it
    image: eclipse-mosquitto:2.1.2-alpine
    command: sleep 2147483647
  broker:
    image: eclipse-mosquitto:2.1.2-alpine
    network_mode: "service:net"
    volumes: [ "./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro", "broker-data:/mosquitto/data" ]
    depends_on: [ net ]
  ntfy:
    image: binwiederhier/ntfy:v2.11.0
    command: serve
    environment: { NTFY_BASE_URL: "http://ntfy" }
  ingest:
    build: { context: ., dockerfile: Dockerfile.ingest }
    image: coldchain-ingest:1
    command: python -u ingest.py
    environment: { SCALE: "60" }
    volumes: [ "./data:/data" ]
    depends_on: [ broker, ntfy ]
  firmware:
    image: espressif/idf:v5.4.1
    # inside QEMU, 10.0.2.2:1883 is port 1883 of this shared namespace: the broker
    network_mode: "service:net"
    working_dir: /lab
    volumes: [ "./:/lab" ]
    command: bash ./fw.sh
    profiles: [ firmware ]
volumes:
  broker-data: {}
```

والملف `fw.sh` يبني البرنامج الثابت مرتين، مرة للوحة الحقيقية بالمشغل الحقيقي وWi-Fi وSNTP، وهذه نبنيها لنتأكد أن الكود الحقيقي يترجم دون أخطاء، ومرة بالصيدلية المحاكاة لتعمل على QEMU، ثم يشغلها:

```bash
#!/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 (1-Wire DS18B20 driver, reed switch, SNTP, Wi-Fi), compiled only
#   build-sim: SENSOR_SIM=1 (simulated pharmacy, 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|error:"
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|error:"
(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:-125}" 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]+\) (cold|example_connect):|Guru" || true
```

والملف `run.sh` هو سيناريو اليوم كله: يشغل الخدمات والجهاز، ثم يقر الصيدلي بتنبيه الباب، ثم يوقف الوسيط عند الدقيقة 30 مدة 15 ثانية، أي ربع ساعة من وقت الصيدلية، ثم يعيده، ثم يقر الفني بعطل المجس، ولا يقر أحد بانحراف غرفة التبريد، ثم يطبع التقرير:

```bash
#!/bin/bash
# Run the whole project on one machine. From this folder:  bash run.sh
set -e
minute() { cat data/minute 2>/dev/null || echo -1; }          # the node's latest minute, as ingest saw it
wait_minute() { until [ "$(minute)" -ge "$1" ]; do sleep 0.5; done; }
ack() { docker compose exec -T ingest python -c "import urllib.request as u; print(u.urlopen(u.Request('http://localhost:8080/ack/$1?by=$2', method='POST')).read().decode(), end='')"; }

rm -rf data && mkdir -p data
docker compose down -v 2>/dev/null
docker compose up -d --build --quiet-pull net broker ntfy ingest 2>/dev/null
{ docker compose run --rm firmware 2>&1 | grep --line-buffered -E "binary size|error:|^### |^[IWE] \(" | tee out-01-firmware.txt; } &
FW=$!
until [ -f data/qemu-started ]; do sleep 2; done   # wait for the two builds

wait_minute 21; ack 1 pharmacist                   # the pharmacist taps Acknowledge on the door alert
wait_minute 30
echo "### broker stopped at node minute $(minute)"
docker compose stop broker 2>/dev/null
sleep 15                                           # 15 minutes of the pharmacy with no broker
docker compose start broker 2>/dev/null
echo "### broker started again"
wait_minute 63; ack 2 technician                   # the technician acknowledges the probe fault
wait $FW                                           # nobody acknowledges the cold room excursion
sleep 3
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
cp data/coldchain-report.csv out-04-report.csv
docker compose down -v 2>/dev/null
```

ونشغل المختبر من مجلد `lab` بالأمر التالي، وأول تشغيل يأخذ دقائق لأنه يبني البرنامج الثابت مرتين:

```bash
bash run.sh
```

### ماذا طبع الجهاز

والمخرج من الجهاز المحاكى سوف يكون كما يلي، وهو مختصر إلى سطر كل عشر دقائق مع الأحداث:

```text
Bootloader binary size 0x6580 bytes. 0xa80 bytes (9%) free.
coldchain.bin binary size 0xd78d0 bytes. Smallest app partition is 0x100000 bytes. 0x28730 bytes (16%) free.
Bootloader binary size 0x6580 bytes. 0xa80 bytes (9%) free.
coldchain.bin binary size 0x87ed0 bytes. Smallest app partition is 0x100000 bytes. 0x78130 bytes (47%) free.
### qemu
W (16346) cold: fridge-2: +85.0 C is the power-on value, converting again
I (16386) cold: connected, 0 record(s) waiting in the ring
I (16406) cold: min 0: fridge-1=4.6 fridge-2=5.1 room=4.9 door=0 ring=1
I (26406) cold: min 10: fridge-1=4.7 fridge-2=5.1 room=4.8 door=0 ring=1
W (35406) cold: event door_open_long room
I (36406) cold: min 20: fridge-1=4.7 fridge-2=5.1 room=9.4 door=1 ring=1
W (38406) cold: event door_closed room
I (46406) cold: min 30: fridge-1=4.7 fridge-2=5.0 room=4.9 door=0 ring=1
W (47716) cold: broker lost, keeping records in the ring
I (56406) cold: min 40: fridge-1=4.6 fridge-2=4.9 room=4.7 door=0 ring=9
I (65386) cold: connected, 17 record(s) waiting in the ring
I (66406) cold: min 50: fridge-1=4.6 fridge-2=4.9 room=4.9 door=0 ring=1
W (76406) cold: event probe_missing fridge-2
I (76406) cold: min 60: fridge-1=4.5 fridge-2=-- room=7.0 door=0 ring=2
I (86406) cold: min 70: fridge-1=4.5 fridge-2=-- room=9.1 door=0 ring=1
I (96436) cold: min 80: fridge-1=4.5 fridge-2=-- room=11.1 door=0 ring=1
I (106436) cold: min 90: fridge-1=4.6 fridge-2=-- room=13.1 door=0 ring=1
I (116436) cold: min 100: fridge-1=4.7 fridge-2=-- room=15.0 door=0 ring=1
I (126436) cold: min 110: fridge-1=4.7 fridge-2=-- room=17.0 door=0 ring=1
```

والأرقام في أول كل سطر هي ملي ثواني الجهاز منذ التشغيل، وفيما يلي ما نقرؤه فيها:

- **+85 في أول قراءة:** المجس الثاني رجع +85 قبل الدقيقة صفر، فطلب البرنامج قياساً جديداً، ووصلت القراءة الأولى 5.1 درجة، ولم يدخل الرقم 85 السجل أبداً.
- **الباب:** فتح في الدقيقة 15، وبعد خمس دقائق، في الدقيقة 19، عملت الصفارة وخرج الحدث `door_open_long`، وفي الدقيقة 22 أغلق الباب فخرج `door_closed`. ولاحظ قراءة الغرفة في الدقيقة 20: 9.4 درجة، أي فوق الحد، ولكنها هواء دخل من الباب وليس انحرافاً، كما سنرى في القاعدة.
- **الوسيط:** توقف بعد الدقيقة 30، فطبع الجهاز «broker lost» مرة واحدة، واستمر يقرأ ويحفظ، فوصلت الحلقة في الدقيقة 40 إلى 9 سجلات تنتظر، وعندما عاد الوسيط كان فيها 17 سجلاً، وبعد دقيقة واحدة أصبح فيها سجل واحد، أي أن الحلقة أفرغت ما فيها بالترتيب.
- **المجس المنزوع:** في الدقيقة 60 لم يرد المجس الثاني على نبضة إعادة الضبط، فخرج الحدث `probe_missing`، وأصبحت قراءته `--` في السجل وليس رقماً.
- **الضاغط:** من الدقيقة 50 ترتفع حرارة الغرفة 0.2 درجة كل دقيقة، من 4.9 إلى 17 درجة في الدقيقة 110، والجهاز نفسه لا يقرر شيئاً في هذا، فالقرار على السيرفر.

### ماذا رأت خدمة الاستقبال

```text
status pharmacy-1/node-1 = online
event pharmacy-1/node-1 seq=20 min=19 door_open_long room
notify [coldchain p4] Cold room door open for 5 min: room, minute 19. Alert #1
event pharmacy-1/node-1 seq=24 min=22 door_closed room
alert #1 (door, room) acknowledged at minute 22
status pharmacy-1/node-1 = offline
notify [coldchain p4] Node offline: pharmacy-1/node-1 lost its connection (last will)
notify [coldchain p4] No data: nothing from the cold chain for 5 min: node, network or broker
notify [coldchain p3] Data resumed: pharmacy-1/node-1 is sending again
status pharmacy-1/node-1 = offline
notify [coldchain p4] Node offline: pharmacy-1/node-1 lost its connection (last will)
status pharmacy-1/node-1 = offline (retained)
status pharmacy-1/node-1 = online
late pharmacy-1/node-1 seq=34 min=32 arrived at node minute 49
late pharmacy-1/node-1 seq=35 min=33 arrived at node minute 49
late pharmacy-1/node-1 seq=36 min=34 arrived at node minute 49
late pharmacy-1/node-1 seq=37 min=35 arrived at node minute 49
late pharmacy-1/node-1 seq=38 min=36 arrived at node minute 49
late pharmacy-1/node-1 seq=39 min=37 arrived at node minute 49
late pharmacy-1/node-1 seq=40 min=38 arrived at node minute 49
late pharmacy-1/node-1 seq=41 min=39 arrived at node minute 49
late pharmacy-1/node-1 seq=42 min=40 arrived at node minute 49
late pharmacy-1/node-1 seq=43 min=41 arrived at node minute 49
late pharmacy-1/node-1 seq=44 min=42 arrived at node minute 49
late pharmacy-1/node-1 seq=45 min=43 arrived at node minute 49
late pharmacy-1/node-1 seq=46 min=44 arrived at node minute 49
late pharmacy-1/node-1 seq=47 min=45 arrived at node minute 49
late pharmacy-1/node-1 seq=48 min=46 arrived at node minute 49
late pharmacy-1/node-1 seq=49 min=47 arrived at node minute 49
event pharmacy-1/node-1 seq=62 min=60 probe_missing fridge-2
notify [coldchain p4] Probe fault: fridge-2 (probe_missing): fridge-2, minute 60. Alert #2
alert #2 (probe, fridge-2) acknowledged at minute 65
notify [coldchain p4] Excursion: room outside 2-8 C for 10 min: room at 10.1 C, outside since minute 66. Alert #3
notify [coldchain-manager p5] Not acknowledged: excursion: room: alert #3 sent at minute 76, nobody acknowledged it in 10 minutes
status pharmacy-1/node-1 = offline
notify [coldchain p4] Node offline: pharmacy-1/node-1 lost its connection (last will)
notify [coldchain p4] No data: nothing from the cold chain for 5 min: node, network or broker
```

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

- **تنبيه الباب والإقرار:** وصل التنبيه رقم 1 في الدقيقة 19، وأقر به الصيدلي في الدقيقة 22، فلم يصعد إلى المدير.
- **أثناء توقف الوسيط:** وصل تنبيهان «Node offline» مع أن الجهاز كان يعمل ويحفظ قراءاته، والسبب ما رأيناه في التجربة: عندما أوقفنا Mosquitto انقطع اتصال الجهاز دون رسالة وداع، فوصلت رسالة الوصية، ثم وصلت مرة ثانية بعد عودة الوسيط. وبالتالي تنبيه «الجهاز انقطع» وقت انقطاع الوسيط هو تنبيه كاذب، والإشارة الصحيحة هي تنبيه «No data» من مراقبة الصمت، الذي وصل بعد خمس دقائق دون أن يعرف السبب، ثم «Data resumed» عند العودة. وأما رسالة `offline` المحفوظة Retained التي وصلت مع إعادة الاشتراك فقد طبعتها الخدمة مع كلمة `(retained)` ولم ترسل عنها تنبيهاً، لأن الرسالة المحفوظة حالة قديمة وليست خبراً جديداً.
- **القراءات المتأخرة:** ست عشرة قراءة، من الدقيقة 32 إلى 47، وصلت كلها في دقيقة الجهاز 49، بأرقامها التسلسلية من 34 إلى 49 دون أي فجوة. وهذا هو الفرق عن تجربة مقال إنترنت الأشياء: هناك ضاعت قراءات، وهنا تأخرت فقط.
- **الانحراف والتصعيد:** الغرفة تجاوزت 8 درجات في الدقيقة 66، والقاعدة انتظرت عشر دقائق، فوصل التنبيه رقم 3 في الدقيقة 76 والغرفة 10.1 درجة، ولم يقر به أحد، فذهب في الدقيقة 86 إلى موضوع المدير بأولوية 5\. وأما ارتفاع الباب إلى 9.4 درجة فلم يصل عنه تنبيه انحراف، لأنه بقي فوق 8 درجات أقل من عشر دقائق.

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

![رسم خطي لحرارة غرفة التبريد من الدقيقة 0 إلى 114: الخط حول 4.8 درجات، ثم يرتفع إلى 9.5 بين الدقيقة 15 و22 في شريط برتقالي عنوانه الباب مفتوح ويعود بسرعة، ثم شريط رمادي من 31 إلى 48 عنوانه الوسيط متوقف والخط ثابت فيه، ثم من الدقيقة 50 يرتفع الخط باستمرار حتى 17.8 درجة، ويقطع خط 8 درجات الأحمر قرابة الدقيقة 66، وخط متقطع برتقالي عند الدقيقة 76 عنوانه تنبيه الانحراف، وخط متقطع بنفسجي عند 86 عنوانه تصعيد للمدير، والشريط الأخضر المدى من 2 إلى 8](https://arabroot.io/content/images/2026/11/project-cold-room-08-room.webp)

الباب المفتوح تجاوز 8 درجات ست دقائق فلم ينبه، والضاغط المتوقف نبه بعد عشر دقائق ثم صعد بعد عشر أخرى

### التقرير اليومي

وفي نهاية اليوم يخرج الملف `report.py` التقرير الذي يسلم للصيدلي وللمفتش، ملف CSV فيه كل قراءة، ثم ملخص لكل مكان، ثم التنبيهات ومن أقر بها، ثم اكتمال السجل:

```python
"""The daily report for the pharmacist and the inspector: a CSV with every reading, then a summary per location,
the excursions and alerts with who acknowledged them, and the completeness of the record (gaps, late records).
In the lab the node has no real clock (ts = 0), so minute 0 is printed as 08:00; on a real board ts comes from SNTP."""
import csv, json, sqlite3, time, urllib.request

db = sqlite3.connect("/data/coldchain.db")
def clock(minute, ts=0):
    if ts:
        return time.strftime("%Y-%m-%d %H:%M", time.localtime(ts))
    return f"{8 + minute // 60:02d}:{minute % 60:02d}"

rows = db.execute("SELECT min, ts, loc, temp, door FROM reading ORDER BY seq, loc").fetchall()
with open("/data/coldchain-report.csv", "w", newline="") as f:
    w = csv.writer(f)
    w.writerow(["time", "location", "temp_c", "status", "door"])
    for m, ts, loc, t, door in rows:
        status = "fault" if t is None else "ok" if 2.0 <= t <= 8.0 else "out"
        w.writerow([clock(m, ts), loc, "" if t is None else t, status, "open" if door and loc == "room" else ""])
print(f"CSV: {len(rows)} rows in coldchain-report.csv, first lines:")
print("".join(open("/data/coldchain-report.csv").readlines()[:4]), end="")

print("\nlocation   readings  min   max   mean  minutes out  minutes fault")
for loc, n, lo, hi, avg, out, fault in db.execute("""
        SELECT loc, COUNT(*), MIN(temp), MAX(temp), AVG(temp),
               SUM(temp IS NOT NULL AND (temp < 2 OR temp > 8)), SUM(temp IS NULL)
        FROM reading GROUP BY loc ORDER BY loc"""):
    print(f"{loc:9} {n:9d} {lo:5.1f} {hi:5.1f} {avg:5.1f} {out:12d} {fault:14d}")

print("\nalerts:")
for aid, loc, kind, m, nm, end, peak, by, am, esc in db.execute(
        "SELECT id, loc, kind, min, notified_min, end_min, peak, acked_by, acked_min, escalated FROM alert ORDER BY id"):
    span = f"{clock(m)} to {clock(end)}" if end is not None else f"{clock(m)}, still open"
    ack = f"acknowledged by {by} at {clock(am)}" if by else "NOT acknowledged"
    print(f"#{aid} {kind:9} {loc:9} {span:22} notified {clock(nm)}  {ack}"
          f"{'  escalated to manager' if esc else ''}{f'  peak {peak:.1f} C' if peak else ''}")

seqs = db.execute("SELECT COUNT(DISTINCT seq), MIN(seq), MAX(seq) FROM "
                  "(SELECT seq FROM reading UNION SELECT seq FROM event)").fetchone()
gaps = db.execute("SELECT COUNT(*) FROM gap").fetchone()[0]
late = db.execute("SELECT COUNT(DISTINCT seq), MAX(lag) FROM reading WHERE lag >= 2").fetchone()
print(f"\nrecords: {seqs[0]} (seq {seqs[1]}..{seqs[2]}), gaps: {gaps}, "
      f"late readings: {late[0]} (latest arrived {late[1]} min after it was taken)")

for topic in ("coldchain", "coldchain-manager"):
    print(f"\n### ntfy topic '{topic}'")
    with urllib.request.urlopen(f"http://ntfy/{topic}/json?poll=1&since=all", timeout=5) as r:
        for line in r:
            n = json.loads(line)
            act = "  [button: Acknowledge]" if n.get("actions") else ""
            print(f"[p{n.get('priority', 3)}] {n.get('title')}: {n['message']}{act}")
```

والمخرج سوف يكون كما يلي:

```text
CSV: 345 rows in coldchain-report.csv, first lines:
time,location,temp_c,status,door
08:00,fridge-1,4.6,ok,
08:00,fridge-2,5.1,ok,
08:00,room,4.9,ok,

location   readings  min   max   mean  minutes out  minutes fault
fridge-1        115   4.5   4.7   4.6            0              0
fridge-2        115   4.9   5.1   5.0            0             55
room            115   4.7  17.8   8.9           54              0

alerts:
#1 door      room      08:19 to 08:22         notified 08:19  acknowledged by pharmacist at 08:22
#2 probe     fridge-2  09:00, still open      notified 09:00  acknowledged by technician at 09:05
#3 excursion room      09:06, still open      notified 09:16  NOT acknowledged  escalated to manager  peak 17.8 C

records: 118 (seq 0..117), gaps: 0, late readings: 16 (latest arrived 17 min after it was taken)

### ntfy topic 'coldchain'
[p4] Cold room door open for 5 min: room, minute 19. Alert #1  [button: Acknowledge]
[p4] Node offline: pharmacy-1/node-1 lost its connection (last will)
[p4] No data: nothing from the cold chain for 5 min: node, network or broker
[p3] Data resumed: pharmacy-1/node-1 is sending again
[p4] Node offline: pharmacy-1/node-1 lost its connection (last will)
[p4] Probe fault: fridge-2 (probe_missing): fridge-2, minute 60. Alert #2  [button: Acknowledge]
[p4] Excursion: room outside 2-8 C for 10 min: room at 10.1 C, outside since minute 66. Alert #3  [button: Acknowledge]
[p4] Node offline: pharmacy-1/node-1 lost its connection (last will)
[p4] No data: nothing from the cold chain for 5 min: node, network or broker

### ntfy topic 'coldchain-manager'
[p5] Not acknowledged: excursion: room: alert #3 sent at minute 76, nobody acknowledged it in 10 minutes
```

والتقرير يقول للمفتش ما يحتاجه في سطور قليلة:

- **الملخص:** الثلاجة الأولى بين 4.5 و4.7 طوال الوقت، والثانية بين 4.9 و5.1 ثم 55 دقيقة عطل في المجس، وغرفة التبريد 54 دقيقة خارج المدى، منها ست دقائق الباب المفتوح، والباقي الضاغط المتوقف، وأعلى قراءة 17.8 درجة.
- **التنبيهات:** كل تنبيه بوقت بدايته ووقت إرساله، ومن أقر به ومتى، والتنبيه رقم 3 مكتوب عليه «NOT acknowledged» و«escalated to manager»، وهذا السطر هو أول ما سوف يسأل عنه أي تحقيق: من علم، ومتى، وماذا فعل.
- **اكتمال السجل:** 118 سجلاً بأرقام من 0 إلى 117، وصفر فجوات، و16 قراءة متأخرة أكثرها تأخراً وصل بعد 17 دقيقة. وهذا السطر هو الدليل على أن السجل كامل، وأن ربع الساعة التي توقف فيها الوسيط موجودة في الملف كأي ربع ساعة أخرى.

ولاحظ أن عطل المجس الثاني مكتوب في الملخص بالدقائق في عمود مستقل، وأن الملف CSV يكتب حالته `fault` وخانة الحرارة فارغة، فلا يوجد في أي مكان من التقرير رقم -127 أو 85.

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

- **التنبيه على قراءة واحدة:** أسرع طريقة لتعليم الصيدلي أن يتجاهل التنبيهات، والحل قاعدة بالمدة ومجس معزول.
- **المجس بجانب فتحة الهواء أو الباب:** يقيس الهواء وليس الدواء، والدليل يقول في وسط الثلاجة والأدوية حوله.
- **إرسال -127 أو +85 كحرارة:** العطل حدث منفصل، والقيمة `null`، وإلا كتبت في السجل الرسمي حرارة لم تحدث.
- **الاعتماد على الوسيط في حفظ القراءات:** الجلسة الدائمة لا تحمي من توقف الوسيط نفسه، والحل حلقة في الجهاز وإقرار لكل سجل.
- **حساب المدة بوقت الوصول:** القراءات المتأخرة تصل دفعة واحدة، فاحسب بدقائق الجهاز أو وقته.
- **تنبيه دون إقرار ودون تصعيد:** التنبيه الذي لا يعرف أحد إن قرأه هو تنبيه لم يرسل.
- **الصفارة على السيرفر:** إذا كان التنبيه المحلي يحتاج الشبكة فهو لا يعمل عندما تكون الشبكة هي المشكلة.
- **عدم مراقبة الصمت:** رسالة الوصية تحتاج وسيطاً يعمل، فراقب غياب البيانات من جهة السيرفر.
- **نسيان المعايرة:** يوصي دليل CDC باختبار المعايرة كل سنتين إلى ثلاث، أو بحسب المصنع، فقارن كل مجس بميزان معاير واحفظ معامل التصحيح منفصلاً عن القراءة الخام.

## تطبيق عملي

1. أضف إلى الصيدلية المحاكاة في `probes.c` انقطاع كهرباء الثلاجة الأولى من الدقيقة 35 إلى 52، وتوقع قبل التشغيل: هل يصل تنبيه انحراف؟ ومتى بدقائق الجهاز، مع أن الوسيط متوقف من 30 إلى 45؟
2. غير `RING` في `main.c` إلى 10 سجلات، وشغل المختبر، وابحث في التقرير عن الحقل `dropped` وعن الفجوات.
3. أضف إلى خدمة الاستقبال قاعدة للحد الأدنى: أقل من 2 درجة لخمس دقائق، لأن تجميد بعض اللقاحات يتلفها كما يتلفها الارتفاع، وتحقق من القاعدة في دليل CDC.
4. اجعل التقرير يكتب سجل الإقرارات في ملف CSV ثان: رقم التنبيه، والمكان، والوقت، ومن أقر، والإجراء، وأضف حقل الإجراء إلى طلب الإقرار.
5. أضف إلى المختبر لوحة متابعة كما فعلنا في [مقال لوحات المتابعة مع Node-RED وGrafana](https://arabroot.io/articles/%D9%84%D9%88%D8%AD%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%AA%D8%A7%D8%A8%D8%B9%D8%A9-%D9%84%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-node-red-%D9%85%D8%B9-grafana/)، تقرأ من جدول `reading`.

## حذف المختبر Cleanup

```bash
docker compose down -v
docker image rm coldchain-ingest:1
rm -rf data firmware/build-hw firmware/build-sim firmware/sdkconfig
```

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

## الخلاصة Summary

- ابدأ من متطلبات الجهة الصحية وليس من القطع: المدى من 2 إلى 8، وتسجيل مستمر، ومجس معزول في الوسط، وسجل يحفظ من أقر وماذا فعل.
- المجس DS18B20 رقمي بدقة ±0.5 درجة، ولا تصدق منه +85 بعد التشغيل، ولا تحول غيابه إلى رقم.
- القراءات لا تضيع إذا بقيت في حلقة في الجهاز حتى يقر الوسيط باستلامها، والمكرر يحذف بالرقم التسلسلي في خدمة الاستقبال.
- التنبيه على المدة وبدقائق الجهاز، ومع زر إقرار، وتصعيد إلى المدير إذا لم يقر أحد.
- الصفارة المحلية لا تحتاج شبكة، ومراقبة الصمت على السيرفر تخبرك بالانقطاع الذي لا يستطيع الجهاز أن يخبرك به.

والمشروع التالي في السلسلة التجارية بإذن الله هو [عداد الزوار عند مدخل المتجر](https://arabroot.io/articles/%D9%85%D8%B4%D8%B1%D9%88%D8%B9-%D8%B9%D8%AF%D8%A7%D8%AF-%D8%A7%D9%84%D8%B2%D9%88%D8%A7%D8%B1-%D8%B9%D9%86%D8%AF-%D9%85%D8%AF%D8%AE%D9%84-%D8%A7%D9%84%D9%85%D8%AA%D8%AC%D8%B1/)، وفيه مشكلة من نوع آخر: الحساس سليم، ولكن شخصين يدخلان معاً.

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

- نوفمبر 2026: كتابة المقال، وتشغيل البرنامج الثابت على ESP-IDF v5.4.1 ومحاكي QEMU من Espressif، مع Mosquitto 2.1.2 وntfy 2.11.0 وPython 3.13 في Docker Engine 29.8.0، والمرجع دليل CDC لتخزين اللقاحات بإصدار يوليو 2026.