مشروع متكامل

21.1 ماذا يطلب المنهج؟ – מחוון הפרויקט (Project Requirements)

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

21.2 التخطيط: الفكرة والمخطّط والمواصفات – רעיון, תרשים מלבנים, מפרט (Planning)

الفكرة، في جملة: مراقب دفيئة (חממה) صغيرة: لوحة في الدفيئة تقرأ الحرارة والرطوبة والضوء وتشغّل مروحة، ولوحة في المكتب تعرض الحالة وتقرّر متى تعمل المروحة.

المواصفات (מפרט): كل سطر يجب أن يقبل الفحص بنعم أو لا. فجملة «المشروع سريع» ليست مواصفة، وجملة «تُرسل قراءة كل 10 ثوان» مواصفة:

21.3 شجرة الملفات – עץ הקבצים (Project Tree)

نقرّر مكان كل شيء قبل أن نكتب. القاعدة: ما تشترك فيه اللوحتان في shared، وما يخص لوحة في مجلدها، والملف main.py قصير ويستدعي غيره. وعلى اللوحة نفسها ننسخ ملفات shared وملفات مجلد العقدة معا إلى المجلد الرئيسي، لأن البرنامج يبحث عن مكتباته هناك.

الملف المشترك gh_link.py: أسماء الموضوعات في مكان واحد، فلا يمكن أن تختلف بين اللوحتين. والاتصال وإعادة الاتصال من الفصل 16.

# gh_link.py - the greenhouse MQTT link, the same on both nodes.
# (c) 2026 Fahed Ghanem - MIT License - fahed-lab.com
import json
import time
from umqtt.simple import MQTTClient
import wifi

BROKER = "broker.hivemq.com"
DATA = b"school/gh1/data"
FAN_SET = b"school/gh1/fan/set"
FAN_STATE = b"school/gh1/fan/state"


class Link:
    def __init__(self, client_id, topics, handler):
        self.client = MQTTClient(client_id, BROKER)
        self.topics = topics
        self.handler = handler
        self.client.set_callback(self._deliver)

    def _deliver(self, topic, msg):
        try:
            obj = json.loads(msg)
        except ValueError:
            print("bad message on", topic)
            return
        self.handler(topic, obj)

    def connect(self, tries=4):
        wifi.connect()
        wait = 1
        for _ in range(tries):
            try:
                self.client.connect()
                for topic in self.topics:
                    self.client.subscribe(topic)
                return True
            except OSError:
                print("no broker, waiting", wait, "s")
                time.sleep(wait)
                wait *= 2
        return False

    def send(self, topic, obj):
        msg = json.dumps(obj).encode()
        try:
            self.client.publish(topic, msg)
        except OSError:
            if self.connect():
                self.client.publish(topic, msg)

    def poll(self):
        try:
            self.client.check_msg()
        except OSError:
            self.connect()

21.4 البناء خطوة خطوة – בנייה הדרגתית (Building Step by Step)

لا نكتب كل شيء ثم نجرّب. نضيف آلية واحدة، ونجرّبها وحدها، ولا نتقدّم حتى تعمل. وعندما يظهر عطل نعرف أين نبحث: في آخر ما أضفناه.

الخطوة 1: الحسّاسات:

# gh_sense.py - the sensors of the greenhouse, as one reading.
# (c) 2026 Fahed Ghanem - MIT License - fahed-lab.com
import dht
from machine import Pin
import board


class Sensors:
    def __init__(self):
        self.air = dht.DHT22(Pin(board.DHT))
        self.ldr = board.analog_in(board.LDR)

    def read(self):
        try:
            self.air.measure()
        except OSError:
            return None
        return {"t": self.air.temperature(),
                "h": self.air.humidity(),
                "light": self.ldr.read_u16() * 100 // 65535}

import time
from gh_sense import Sensors

sensors = Sensors()
for _ in range(3):
    print(sensors.read())
    time.sleep(10)

{'t': 24, 'light': 50, 'h': 60}
{'t': 24, 'light': 50, 'h': 60}
{'t': 24, 'light': 60, 'h': 60}

الخطوتان 2 و3: النشر والعرض:

# gh_view.py - what the greenhouse display shows, on a 16x2 LCD.
# (c) 2026 Fahed Ghanem - MIT License - fahed-lab.com
import board
from i2c_lcd import LCD


class View:
    def __init__(self):
        self.lcd = LCD(board.i2c())

    def data(self, d, fan):
        self.lcd.line(0, "T %.1fC  H %.0f%%" % (d["t"], d["h"]))
        self.lcd.line(1, "L %d%%  Fan %s"
                      % (d["light"], "ON" if fan else "off"))

    def no_data(self):
        self.lcd.line(0, "NO DATA")
        self.lcd.line(1, "check sensor")

import time
from gh_view import View
from gh_link import Link, DATA

view = View()


def on_message(topic, obj):
    print("got", obj)
    view.data(obj, False)


link = Link("gh1-display", (DATA,), on_message)
link.connect()
for _ in range(25):
    link.poll()
    time.sleep(1)

got {'h': 60, 't': 24.5, 'light': 50}
got {'h': 58, 't': 25.0, 'light': 61}
[LCD]
|T 25.0C  H 58%  |
|L 61%  Fan off  |
...

الخطوات 4 و5: العقدتان في صورتهما النهائية:

import time
import machine
from machine import Pin, WDT
import board
from gh_sense import Sensors
from gh_link import Link, DATA, FAN_SET, FAN_STATE

SEND_EVERY_MS = 10000

fan = Pin(board.LED, Pin.OUT)
sensors = Sensors()


def on_message(topic, cmd):
    fan.value(1 if cmd["on"] else 0)
    link.send(FAN_STATE, {"on": fan.value()})
    print("fan:", fan.value())


link = Link("gh1-sensor", (FAN_SET,), on_message)
if not link.connect():
    time.sleep(30)
    machine.reset()

guard = WDT(timeout=8000)
next_send = time.ticks_ms()
while True:
    guard.feed()
    link.poll()
    if time.ticks_diff(time.ticks_ms(), next_send) >= 0:
        next_send = time.ticks_add(next_send, SEND_EVERY_MS)
        data = sensors.read()
        if data:
            link.send(DATA, data)
        else:
            print("sensor failed")
    time.sleep_ms(100)

fan: 1
[mqtt_pub]
school/gh1/data {"t": 31, "light": 60, "h": 60}
school/gh1/data {"t": 31, "light": 60, "h": 60}
school/gh1/fan/state {"on": 1}
school/gh1/data {"t": 31, "light": 60, "h": 60}
...

والآن main.py في عقدة العرض. انظروا فيه إلى want وhave: المتغيّر الأول هو ما نريده، والثاني هو ما تقوله اللوحة الأخرى. وما داما مختلفين نكرّر الأمر مع كل قراءة. فلو ضاعت رسالة تصحّحت بعد 10 ثوان. هذه حلقة مغلقة عبر الشبكة، بالفكرة نفسها التي في الفصل 20: نقيس ونقارن ونصحّح. وفي المخرجات أدناه تصمت الرسائل بعد t = 25، كأن الحسّاس انقطع.

import time
from gh_view import View
from gh_link import Link, DATA, FAN_SET, FAN_STATE

FAN_ON = 30.0
FAN_OFF = 27.0
STALE_MS = 30000

view = View()
want = False
have = False
seen = time.ticks_ms()
stale = False


def on_data(d):
    global want, seen, stale
    seen = time.ticks_ms()
    stale = False
    if d["t"] > FAN_ON:
        want = True
    elif d["t"] < FAN_OFF:
        want = False
    if want != have:
        print("T", d["t"], "ask fan", want)
        link.send(FAN_SET, {"on": want})
    view.data(d, have)


def on_message(topic, obj):
    global have
    if topic == DATA:
        on_data(obj)
    elif topic == FAN_STATE:
        have = bool(obj["on"])
        print("fan is", have)


link = Link("gh1-display", (DATA, FAN_STATE), on_message)
link.connect()
while True:
    link.poll()
    late = time.ticks_diff(time.ticks_ms(), seen)
    if late > STALE_MS and not stale:
        stale = True
        print("silent for", late // 1000, "s")
        view.no_data()
    time.sleep_ms(100)

T 31.0 ask fan True
fan is True
T 26.0 ask fan False
fan is False
silent for 30 s
[mqtt_pub]
school/gh1/fan/set {"on": true}
school/gh1/fan/set {"on": false}
[LCD]
|NO DATA         |
|check sensor    |
...

21.5 البحث عن الأعطال: عتاد أم برنامج؟ – איתור תקלות: חומרה מול תוכנה (Troubleshooting)

أول سؤال هو أين العطل، وليس كيف نصلحه. نقسم السلسلة إلى نصفين، ونفحص في الوسط، فنعرف أي النصفين سليم. وفي مشروعنا الوسيط هو الوسط الطبيعي: أي القراءات تصل إليه؟

mosquitto_sub -h broker.hivemq.com -t "school/gh1/#" -v

إن ظهرت القراءات فعقدة الحسّاسات سليمة، والعطل في جهة العرض. وإن لم تظهر فالعكس. ولفحص العتاد كله نكتب برنامجا صغيرا لا يعرف شيئا عن المشروع:

import board
import dht
from machine import Pin
import wifi


def lcd():
    return 0x27 in board.i2c().scan()


def air():
    s = dht.DHT22(Pin(board.DHT))
    s.measure()
    return s.humidity() > 0


def light():
    return 1000 < board.analog_in(board.LDR).read_u16() < 64500


def net():
    return wifi.connect(5).isconnected()


for name, test in (("lcd", lcd), ("air", air),
                   ("light", light), ("net", net)):
    try:
        ok = test()
    except OSError:
        ok = False
    print("%-6s %s" % (name, "PASS" if ok else "FAIL"))

lcd    FAIL
air    PASS
light  FAIL
net    FAIL

وعندما يكون كل شيء موصولا يعطي البرنامج: lcd PASS, air PASS, light PASS, net PASS. وأي سطر FAIL يعني عطلا في العتاد أو في التوصيل، فلا نفتّش في main.py قبل أن نصلحه.

وعندما نشكّ في العتاد نأخذ أداة القياس. المقياس المتعدّد (רב-מודד) يعطي قيمة واحدة ثابتة، ويناسب ما لا يتغيّر بسرعة. أما راسم الذبذبات (משקף תנודות) فيرسم الجهد مع الزمن، ويناسب ما يتغيّر:

21.6 استعمال الذكاء الاصطناعي: واجب التوثيق – שימוש ב-AI: חובת תיעוד (Using AI)

يُسمح باستعمال أدوات الذكاء الاصطناعي في المشروع، لكن المنهج يُلزمنا (الفصل 8 منه) بأن نوثّق ما كُتب بمساعدتها. ولا يكفي أن نقول في النهاية «استعملناها»: نسجّل ذلك عند حدوثه، في docs/ai_log.md.

## 2026-11-14 - gh_link.py, function connect()
Tool and date: (name of the tool), 2026-11-14
Asked: "retry MQTT connect with growing waits in MicroPython"
Took: the loop with wait *= 2
Changed: removed a call that does not exist in umqtt.simple
Checked: ran with the broker off, read every line, can explain it

• نفهم كل سطر: في العرض قد يُطلب منا شرح أي سطر. ما لا نقدر على شرحه لا يدخل المشروع.
• نشغّل ونفحص: الأداة تكتب أوامر تبدو صحيحة وهي غير موجودة، أو قديمة مثل adc.width() في القسم 6.4. فالمرجع هو توثيق مايكروبايثون والتجربة.
• لا نرسل أسرارا: لا ينتقل الملف secrets.py إلى أي أداة، ولا إلى أي مشاركة.
• نسجّل التعديل: ما غيّرناه بعد الأداة مهم، لأنه يبيّن ما فهمناه.

21.7 سجلّ العمل وكتاب المشروع – יומן עבודה וספר פרויקט (Logbook and Project Book)

سجلّ العمل (יומן עבודה) نكتبه في كل جلسة، ببضعة أسطر. فبعد شهر لا نتذكّر لماذا غيّرنا تلك المقاومة، والسجلّ يتذكّر. وهو أيضا المادة الخام لكتاب المشروع.

## 2026-11-12 (2 hours) - Sara, Omar
Goal: stage 3, the display shows a real reading.
Did: wired the LCD, wrote gh_view.py.
Problem: LCD lit, no text. scan() returned [].
Cause: SDA and SCL swapped. Found with scan(), fixed the wires.
Next: stage 4, the fan command.

كتاب المشروع (ספר פרויקט) نكتبه لقارئ لا يعرف شيئا عن مشروعنا. وهذا ترتيب مقترح لأجزائه:

أهمّ أفكار الفصل:

• نكتب الفكرة والمخطّط والمواصفات قبل البرنامج، وكل مواصفة تقبل الفحص بنعم أو لا.
• شجرة الملفات تقرّر مكان كل شيء، وما تشترك فيه اللوحتان له مكان واحد.
• آلية واحدة في كل خطوة، فنعرف أين نبحث عند العطل.
• نقسم السلسلة إلى نصفين، ونفصل العتاد عن البرنامج بفحص ذاتي وأداة قياس.
• نوثّق كل استعمال للذكاء الاصطناعي عند حدوثه، ونفهم كل سطر نأخذه.
• سجلّ العمل يكتب في كل جلسة، ومنه يولد كتاب المشروع.

أوامر الفصل:

قاموس المصطلحات – מילון מונחים:

أسئلة للتمرين: