# فصل ۱۰ — پروژه ترم: ایستگاه هواشناسی رومیزی — ساخت

<div dir="rtl">

# فصل ۱۰ — پروژه ترم: ایستگاه هواشناسی رومیزی — ساخت

## در این فصل چه می‌سازی

روز جایزه رسید! در این فصل **پروژهٔ ترم** را می‌سازی: ایستگاه هواشناسی رومیزی. دستگاهی که دما و رطوبت اتاق را می‌خواند، روشنایی محیط را اندازه می‌گیرد، سه صفحهٔ اطلاعات دارد که با یک دکمه عوض می‌شوند، یک پرچم کاغذی دارد که با Servo می‌چرخد و نشان می‌دهد هوا سرد است یا خوب یا گرم، و اگر دما از حد بگذرد بوق هشدار می‌زند و روی صفحه ALERT می‌نویسد. و بهترین خبر: در این فصل حتی **یک** مفهوم جدید هم نیست — تک‌تک قطعه‌ها را بلدی! چیزی که تمرین می‌کنیم، مهم‌ترین مهارت یک مهندس واقعی است: سوارکردن قطعه‌های جدا کنار هم طوری که با هم کار کنند. اسمش integration است:

![نقشهٔ ایستگاه هواشناسی: برد ESP32 در مرکز و شش قطعه دورش با فلش‌های رنگی — سنسور DHT11، سنسور نور LDR، نمایشگر OLED، یک Servo با پرچم کاغذی، Buzzer و دکمه — و چهار نشانِ گردِ A تا D که قطعه‌ها را مرحله‌بندی می‌کنند](/lesson-assets/t2-s10-term-project-build/prompt/01-image-station-blueprint.png)

آخر این فصل می‌توانی:

- یک سیستم شش‌قطعه‌ای را مرحله‌به‌مرحله سوار کنی و بعد از هر مرحله (Stage) جداگانه تستش کنی.
- برنامهٔ کاملی را با نظمِ «ثابت‌ها بالا، توابع وسط، حلقهٔ اصلی پایین» سازمان‌دهی کنی و بگویی چرا این نظم مهم است.
- دادهٔ DHT11 را با `try/except` و دادهٔ LDR را با میانگین لیستی پایدار بخوانی و روی سه صفحهٔ OLED نشان بدهی.
- با متغیر وضعیت و debounce صفحه‌ها را با دکمه عوض کنی و پرچم Servo را با فاصله امنیت بی‌لرزش نگه داری.
- برنامه را با اسم `main.py` روی برد ذخیره کنی تا ایستگاه بدون کامپیوتر — standalone — کار کند.

## قبل از شروع: چک‌لیست پیش‌نیاز

این فصل روی شانهٔ همهٔ فصل‌های قبل می‌ایستد — این‌ها باید سر جایشان باشند:

- **از فصل ۱:** تعریف تابع، پارامتر و `return` — امروز بزرگ‌ترین جایزه‌اش را می‌گیری.
- **از فصل ۳ و ۴:** `read()` و خط `atten`، مقسم ولتاژ LDR، آستانه و «فاصله امنیت».
- **از فصل ۵:** میانگین‌گیری با لیست.
- **از فصل ۶:** ماژول dht، قانون «هر ۲ ثانیه»، `try/except` و «پیچ‌های تنظیم» (ثابت‌های بالای برنامه).
- **از فصل ۷:** `i2c.scan()`، ssd1306، قانون طلایی «اول `fill(0)`، آخرش `show()`» و `fill_rect`.
- **از فصل ۸:** تابع قراردادی `set_angle`، تغذیهٔ Servo از VIN و آیین «۹۰ درجه، بعد پرچم».
- **از ترم ۱، فصل ۵ و ۸ و ۹ و ۱۰:** ذخیرهٔ `main.py`؛ دکمه با pull-up و debounce و متغیر وضعیت؛ Buzzer.

لوازم این فصل:

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ESP32 DevKit + کابل USB دیتا | ۱ | از کیت ترم ۱ |
| Breadboard بزرگ + سیم جامپر | ۱ + حدود ۲۰ سیم | دو Breadboard کوچک کنار هم |
| سنسور DHT11 (ماژول سه‌پایه) | ۱ | DHT22 — دقیق‌تر و اعشاری؛ فقط یک خط عوض می‌شود: `dht.DHT22(...)` |
| LDR + مقاومت 10k | ۱ + ۱ | هر LDR معمولی؛ سنسور DHT لختِ چهارپایه یک 10k دیگر بین VCC و DATA می‌خواهد |
| نمایشگر OLED 0.96 اینچ I2C با چیپ SSD1306 | ۱ | نمایشگر ۱٫۳ اینچ معمولاً چیپ SH1106 دارد و با کتابخانهٔ ssd1306 تصویر به‌هم‌ریخته می‌دهد |
| Servo SG90 + پرچم کاغذی دست‌ساز | ۱ | MG90S؛ پرچم از مقوا یا کاغذ سفت |
| Buzzer پسیو + دکمهٔ فشاری | ۱ + ۱ | از کیت ترم ۱ |
| پاور بانک یا شارژر گوشی USB | ۱ | برای تست standalone آخر فصل |

> 🧪 **آزمایشگاه:** قطعه‌ای کم داری؟ **کل ایستگاه** در آزمایشگاه دوره از قبل بسته است — DHT11 روی ۱۶، LDR روی ۳۵، OLED روی ۲۱ و ۲۲، دکمه روی ۳۲، Servo روی ۱۳ و Buzzer روی ۴ — و کد کامل بدون یک خط تغییر آن‌جا اجرا می‌شود. یک مزیت واقعی هم دارد: اسلایدر دما را ببر بالای ۳۲ و هشدار را بدون سشوار و کیسهٔ یخ تست کن. سه تفاوت صادقانه: صدای بوق پخش نمی‌شود، اسلایدرهای دما و رطوبت خودشان «جواب سنسور»اند (پس شاخهٔ `except OSError` هیچ‌وقت آن‌جا اجرا نمی‌شود)، و تست `main.py` مستقل فقط روی سخت‌افزار واقعی معنا دارد. [مدار را همین‌جا امتحان کن](/lab).

## ۱. قانون بزرگ ساخت: هر بار یک قطعه

اول یک سؤال. فکر می‌کنی اگر همین اول کار هر شش قطعه را یک‌جا سیم‌کشی کنیم، بعد یک برنامهٔ صدوپنجاه‌خطی بنویسیم و Run بزنیم، چه می‌شود؟ جواب صادقانه: کار نمی‌کند. و بدترین قسمتش این است که نمی‌فهمیم **کجا** کار نمی‌کند! شش قطعه یعنی شش جای ممکن برای خطا، و وقتی همه با هم وصل باشند، هر خطا می‌تواند خودش را شکل خطای دیگری نشان بدهد.

با دنیای بازی مقایسه‌اش کن: هیچ بازیکن عاقلی یک مرحلهٔ طولانی و سخت را بدون save point جلو نمی‌رود. مهندس‌ها هم همین‌طورند: هر بار فقط یک قطعه اضافه کن، تستش کن، و وقتی مطمئن شدی درست کار می‌کند، آن نقطه save توست؛ حالا برو سراغ بعدی. اگر چیزی خراب شد، می‌دانی مقصر همان آخرین قطعه است. به هر کدام از این قدم‌ها می‌گوییم یک **Stage**. این فصل چهار Stage دارد: A سنسورها، B نمایشگر و دکمه، C پرچم، D هشدار.

این هم نقشهٔ کامل سیم‌کشی — نترس! قرار نیست الان همه‌اش را ببندی؛ فقط ردیف‌های Stage A مال همین حالاست و بقیه سر وقت خودش:

![نقشهٔ کامل سیم‌کشی ایستگاه از بالا: DHT11 با سه سیم به 3V3 و GPIO16 و GND؛ مقسم LDR روی GPIO35؛ نمایشگر OLED روی پایه‌های ۲۱ و ۲۲ با برچسب آدرس 0x3C؛ دکمه روی GPIO32؛ سیم قرمز Servo به VIN با نشان هشدار «فقط ۵ ولت» و سیم نارنجی به GPIO13؛ و Buzzer روی GPIO4](/lesson-assets/t2-s10-term-project-build/prompt/03-image-station-wiring.png)

</div>

| Part | Part pin | ESP32 pin | Stage | Note |
|---|---|---|---|---|
| DHT11 module | VCC | 3V3 | A | bare 4-pin sensor: add 10k between VCC and DATA |
| DHT11 module | DATA | GPIO 16 | A | |
| DHT11 module | GND | GND | A | |
| LDR | leg 1 | 3V3 | A | voltage divider (session 4) |
| LDR | leg 2 | GPIO 35 | A | junction point with resistor |
| Resistor 10k | side 1 | GPIO 35 | A | same junction as LDR leg 2 |
| Resistor 10k | side 2 | GND | A | |
| OLED SSD1306 | GND | GND | B | |
| OLED SSD1306 | VCC | 3V3 | B | |
| OLED SSD1306 | SCL | GPIO 22 | B | |
| OLED SSD1306 | SDA | GPIO 21 | B | address 0x3C |
| Button 1 | leg A | GPIO 32 | B | internal pull-up, pressed = 0 |
| Button 1 | leg B | GND | B | |
| Servo SG90 | red | VIN (5V) | C | NEVER 3V3! (session 8) |
| Servo SG90 | brown | GND | C | common GND with ESP32 |
| Servo SG90 | orange | GPIO 13 | C | PWM 50Hz |
| Buzzer (+) | + | GPIO 4 | D | passive buzzer |
| Buzzer (-) | - | GND | D | |

<div dir="rtl">

## چالش: چرا همه را یک‌جا وصل نمی‌کنیم؟

قبل از باز کردن جواب، با صدای بلند دلیل بیاور.

---

**جواب:** چون اگر شش قطعه با هم وصل باشند و چیزی کار نکند، معلوم نیست مشکل از کدام قطعه است — هر خطا می‌تواند خودش را شکل خطای دیگری نشان بدهد. با ساختِ مرحله‌ای، هر Stage یک save point است و مقصرِ هر خرابی تقریباً همیشه آخرین قطعهٔ اضافه‌شده است.

## ۲. Stage A — سنسورها: چشم و پوستِ ایستگاه

کابل USB را جدا کن و فقط ردیف‌های Stage A را ببند:

1. DHT11 طبق پین‌مپ همیشگی: VCC به 3V3، پایهٔ DATA به GPIO16، GND به GND.
2. LDR با همان مقسم ولتاژ فصل ۴: یک پایهٔ LDR به 3V3، پایهٔ دیگر به GPIO35، و از همان نقطه یک مقاومت 10k به GND.
3. کابل را وصل کن.

قبل از برنامهٔ کامل، عادت مهندسی فصل‌های قبل: تست سریع در Shell که ببینیم سنسور اصلاً جواب می‌دهد یا نه:

</div>

```python
>>> import dht
>>> from machine import Pin
>>> s = dht.DHT11(Pin(16))
>>> s.measure()
```

<div dir="rtl">

اگر شانس من را داشته باشی، این را می‌بینی:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: [Errno 110] ETIMEDOUT
```

<div dir="rtl">

نترس — این خطا را از فصل ۶ می‌شناسی: ETIMEDOUT یعنی «سؤال کردم، ولی سنسور تا پایان مهلت جواب نداد». پس مشکل از کد نیست؛ از راهِ ارتباط است.

> 🔧 **اگر کار نکرد:** ETIMEDOUT گرفتی؟ سیم DATA را نگاه کن — شایع‌ترین علت این است که یک سوراخ آن‌طرف‌تر نشسته؛ در Breadboard، یک ردیف کنارتر یعنی یک دنیای دیگر. سیم را دقیقاً هم‌ردیفِ پایهٔ DATA بزن، دوباره `s.measure()` و بعد `s.temperature()` — باید عدد دمای اتاق بیاید. سنسورت لختِ چهارپایه است؟ یک مقاومت 10k هم بین VCC و DATA لازم دارد.

سنسور که زنده شد، برنامهٔ رسمی Stage A را بنویس — هر دو سنسور کنار هم، تا مطمئن شویم پایهٔ ایستگاه محکم است (فایل `01_sensors_check.py`):

</div>

```python
# Term 2 - Session 10 - Stage A: check kardan DHT11 va LDR ba ham
# Istgah havashenasi roomizi - ghadam e aval

from machine import Pin, ADC
import dht
import time

# ---------- sakht-afzar ----------
sensor = dht.DHT11(Pin(16))
ldr = ADC(Pin(35))
ldr.atten(ADC.ATTN_11DB)  # bedune in, faghat ta hodud e 1 volt mikhanad (dars 3)

# ---------- halghe asli ----------
while True:
    light = ldr.read()  # LDR khataye zamani nadarad, birun e try
    try:
        sensor.measure()
        t = sensor.temperature()
        h = sensor.humidity()
        print(f"Temp: {t} C | Hum: {h} % | Light: {light}")
    except OSError:
        print("Khata dar khandan sensor! sim-keshi ra check kon")
    time.sleep(2)  # DHT11 kondtar az 2 sanie javab nemidahad (dars 6)
```

<div dir="rtl">

دو نکتهٔ ریز در این کد هست که نشان می‌دهد دیگر مبتدی نیستی. اول: خواندن LDR **بیرونِ** try است، چون LDR فقط یک ولتاژ ساده است و خطای زمان‌بندی ندارد؛ ولی DHT11 یک گفت‌وگوی واقعی با تشریفات زمانی است و ممکن است وسطش قهر کند — پس داخل کمربند ایمنی try می‌نشیند. دوم: `time.sleep(2)` آخر حلقه قانون فصل ۶ است؛ DHT11 تندتر از هر ۲ ثانیه جواب تازه ندارد.

✅ **چک کن:** هر دو ثانیه یک خط گزارش می‌آید. دستت را روی LDR بگذار — عدد نور سقوط می‌کند. کنار سنسور دما فوتِ گرم کن — رطوبت می‌پرد بالا. Stage A پاس شد؛ اولین save point ثبت!

## چالش: چرا LDR بیرون try است ولی DHT11 داخل آن؟

---

**جواب:** LDR فقط یک ولتاژ ساده است که ADC هر لحظه می‌خواند — چیزی ندارد که «دیر جواب بدهد». ولی DHT11 یک گفت‌وگوی زمان‌بندی‌شده است که ممکن است شکست بخورد و OSError پرت کند؛ کمربند try فقط برای اوست تا برنامه با هر قهرِ سنسور نمیرد.

## ۳. Stage B — نمایشگر و دکمه: صورتِ ایستگاه

کابل را جدا کن و قطعه‌های Stage B را اضافه کن:

1. OLED مثل فصل ۷: GND به GND، VCC به 3V3، SCL به GPIO22 و SDA به GPIO21.
2. دکمه مثل ترم ۱: یک پایه به GPIO32، پایهٔ قطر مقابل به GND — pull-up داخلی، فشرده یعنی صفر.
3. کابل را وصل کن و آیین همیشگی I2C را اجرا کن: در Shell جاده را اسکن کن.

✅ **چک کن:** `i2c.scan()` باید `[60]` برگرداند — پلاک ۶۰ جواب داد، جاده باز است.

حالا قبل از تایپ، طراحی. سه صفحه می‌خواهیم: صفحهٔ WEATHER با دما و رطوبت، صفحهٔ LIGHT با عدد نور و یک نوار گرافیکی، و صفحهٔ ABOUT که اسم پروژه را نشان می‌دهد — شناسنامهٔ دستگاه. برنامه از کجا بفهمد الان کدام صفحه را نشان بدهد؟ با یک متغیر وضعیت — دوست قدیمی ترم ۱ — به اسم `screen` که صفر یا یک یا دو است. هر فشار دکمه یکی اضافه می‌کند و بعد از دو، برمی‌گردد صفر:

</div>

```python
if button1.value() == 0:
    screen = screen + 1
    if screen > 2:
        screen = 0
    time.sleep_ms(200)
```

<div dir="rtl">

آن `time.sleep_ms(200)` هم همان debounce ترم ۱ است؛ بدونش، یک فشار انگشت سه صفحه می‌پرد.

و حالا یک مسئلهٔ مهندسی واقعی. DHT11 گفت فقط هر ۲ ثانیه؛ ولی دکمه باید **فوری** جواب بدهد. اگر آخر حلقه `time.sleep(2)` بگذاریم، دکمه در تمام آن دو ثانیه کر است — همان دردی که ترم ۱ در چراغ راهنمایی چشیدی! راه‌حل هم با ابزارهای خودمان ساخته می‌شود: حلقه را تند بچرخان — هر ۱۰۰ میلی‌ثانیه — و یک شمارندهٔ معکوس بگذار به اسم `timer`: هر دور حلقه یکی کم می‌شود، و هر وقت به صفر رسید، نوبت خواندن سنسورهاست و شمارنده دوباره از ۲۰ شروع می‌کند. بیست ضربدر ۱۰۰ میلی‌ثانیه؟ همان ۲ ثانیهٔ محبوب DHT11:

</div>

```python
if timer <= 0:
    # inja sensor ha khande mishavand
    timer = DHT_EVERY
```

<div dir="rtl">

دو تابع دیگر هم لازم داریم و هر دو را قبلاً ساخته‌ای: `read_light_avg` همان میانگین‌گیری لیستی فصل ۵ است — پنج نمونه، جمع با حلقه، و تقسیم صحیح `//` فصل ۳ تا عددِ سالمِ صحیح بماند — چون عدد خام LDR روی صفحه پت‌پت می‌زند و زشت است. و `show_screen` که تمام نقاشی صفحه را یک‌جا انجام می‌دهد: اول `fill(0)`، آخرش `show()` — قانون طلایی فصل ۷؛ نوار نور را هم با `fill_rect` و پهنای `map_value(light, 0, 4095, 0, 128)` می‌کشد. برنامهٔ کامل Stage B (فایل `02_station_screens.py`):

</div>

```python
# Term 2 - Session 10 - Stage B: se safhe rooye OLED + dokme baraye avaz kardan
# Istgah havashenasi roomizi - ghadam e dovom

from machine import Pin, ADC, I2C
import ssd1306
import dht
import time

# ---------- pich-haye tanzim (constants) ----------
DHT_EVERY = 20      # har 20 dor e halghe (~2 sanie) yek bar DHT bekhan
LIGHT_SAMPLES = 5   # tedad nemune baraye miangin e noor (dars 5)

# ---------- sakht-afzar ----------
sensor = dht.DHT11(Pin(16))
ldr = ADC(Pin(35))
ldr.atten(ADC.ATTN_11DB)
button1 = Pin(32, Pin.IN, Pin.PULL_UP)  # feshorde = 0 (term 1)
i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)

# ---------- tabe-ha ----------
def map_value(x, in_min, in_max, out_min, out_max):
    # tabdil adad az yek baze be baze dige
    return (x - in_min) * (out_max - out_min) // (in_max - in_min) + out_min


def read_light_avg():
    # 5 nemune az LDR + miangin (dars 5) -> adad e aroom tar
    readings = []
    for i in range(LIGHT_SAMPLES):
        readings.append(ldr.read())
        time.sleep_ms(10)
    total = 0
    for r in readings:
        total = total + r
    return total // len(readings)  # taghsim e sahih -> adad e sahih


def show_screen(screen, t, h, light):
    # hame ye naghashi e safhe yek ja: aval fill(0), akharesh show()
    oled.fill(0)
    if screen == 0:
        oled.text("== WEATHER ==", 0, 0)
        oled.text(f"TEMP: {t} C", 0, 20)
        oled.text(f"HUM:  {h} %", 0, 32)
    elif screen == 1:
        oled.text("== LIGHT ==", 0, 0)
        oled.text(f"RAW: {light}", 0, 20)
        bar = map_value(light, 0, 4095, 0, 128)
        oled.fill_rect(0, 34, bar, 10, 1)
    else:
        oled.text("== ABOUT ==", 0, 0)
        oled.text("Weather Station", 0, 20)
        oled.text("Term 2 Project", 0, 32)
    oled.show()


# ---------- halghe asli ----------
screen = 0
t = 0
h = 0
light = 0
timer = 0  # shomarande ye makoos: 0 yani vaghte khandan e sensor

while True:
    if timer <= 0:
        try:
            sensor.measure()
            t = sensor.temperature()
            h = sensor.humidity()
        except OSError:
            print("Khata dar khandan DHT! sim-keshi ra check kon")
        light = read_light_avg()
        timer = DHT_EVERY
    if button1.value() == 0:
        screen = screen + 1
        if screen > 2:
            screen = 0  # bargasht be safhe ye aval
        time.sleep_ms(200)  # debounce (term 1)
    show_screen(screen, t, h, light)
    timer = timer - 1
    time.sleep_ms(100)
```

<div dir="rtl">

به نظمِ فایل هم نگاه کن: پیچ‌های تنظیم بالا، سخت‌افزار بعدش، توابع وسط، حلقهٔ اصلی پایین — از این به بعد همهٔ برنامه‌های بزرگ ما همین شکل‌اند، چون هر چیزی جای مشخص خودش را دارد.

✅ **چک کن:** صفحهٔ WEATHER می‌آید؛ فشار دکمه — صفحهٔ LIGHT با نوار؛ فشار — ABOUT؛ فشار — دوباره WEATHER. و دما هر دو ثانیه تازه می‌شود. Stage B پاس شد؛ save point دوم!

> 🔧 **اگر کار نکرد:** صفحه‌ها با دکمه عوض نمی‌شوند؟ پایهٔ دوم دکمه باید به GND برود و خودِ دکمه به GPIO32 — در Shell فشرده باید `0` بخواند. یک فشار چند صفحه می‌پرد؟ `time.sleep_ms(200)` بعد از تشخیص فشار جا افتاده. `OSError: [Errno 19] ENODEV` موقع ساخت SSD1306؟ سیم‌های SDA/SCL جابه‌جا یا شل‌اند — `i2c.scan()` هم حتماً `[]` می‌دهد؛ اول scan را سبز کن، بعد نمایشگر بساز.

## چالش: اگر ساده sleep(2) آخر حلقه می‌گذاشتیم چه خراب می‌شد؟

---

**جواب:** دکمه! در تمام آن دو ثانیه برنامه خواب است و فشارها گم می‌شوند — دکمه‌ای که گاهی کار کند، بدتر از دکمه‌ای است که هیچ‌وقت کار نکند. شمارندهٔ معکوس، حلقه را هر ۱۰۰ میلی‌ثانیه بیدار نگه می‌دارد و سنسور را باز هم فقط هر ۲ ثانیه می‌خواند — هر دو قانون راضی‌اند.

## ۴. Stage C — پرچم Servo: دستِ ایستگاه

کابل را جدا کن و Servo را وصل کن — و یادت نرفته فصل ۸ چه دیدیم:

> ⚠️ **مواظب باش:** سیم قرمز Servo فقط به VIN — نه به 3V3! آن روز که اشتباه وصل کردیم، برد مدام ری‌استارت شد و Thonny پیام Device disconnected داد. قهوه‌ای به GND و نارنجی به GPIO13.

تابع `set_angle` را کلمه‌به‌کلمه از فصل ۸ می‌آوریم — قرارداد دوره است و همه‌جا همین شکل است. قانون پرچم: زاویهٔ ۱۶۰ یعنی سرد، ۹۰ یعنی خوب، ۲۰ یعنی گرم. و طبق آداب فصل ۸: اول `set_angle(90)`، بعد پرچم کاغذی را صاف روی هورن بچسبان — «۹۰ درجه، بعد پرچم».

مرز ناحیه‌ها را هم از فصل ۶ قرض می‌گیریم: بین ۲۰ و ۲۷ درجه ناحیهٔ راحت بود. ولی اینجا یک دام هست. فرض کن دما دقیقاً لبِ مرز ۲۷ باشد. DHT11 عدد صحیح می‌دهد: یک بار ۲۷، دو ثانیه بعد ۲۶، دوباره ۲۷... و پرچم بیچاره هر دو ثانیه این‌طرف و آن‌طرف می‌پرد — تیک‌تاک، تیک‌تاک! این صحنه را کجا دیده بودیم؟ فصل ۴، پت‌پتِ چراغ خودکار. راه‌حلش هم همان‌جا ساخته شد: **فاصله امنیت**. حالت پرچم فقط وقتی عوض می‌شود که دما کامل از مرز رد شده باشد — یک درجه آن‌طرف‌تر:

![خط‌کش افقی دما با سه ناحیهٔ رنگی سرد و خوب و گرم و مرزهای ۲۰ و ۲۷؛ دور هر مرز یک نوار راه‌راهِ «فاصله امنیت» کشیده شده و بالای هر ناحیه یک پرچم کوچک Servo؛ گوشهٔ تصویر مقایسهٔ فلشِ لرزان روی مرز با فلشِ آرامِ داخل ناحیه](/lesson-assets/t2-s10-term-project-build/prompt/05-image-flag-margin-zones.png)

</div>

```python
def new_flag_state(t, state):
    # parcham ba faseleye amniat: faghat ba obur e KAMEL az marz avaz mishavad
    if t <= COLD_LIMIT - MARGIN:
        state = COLD
    if t >= COLD_LIMIT + MARGIN and t <= HOT_LIMIT - MARGIN:
        state = OK
    if t >= HOT_LIMIT + MARGIN:
        state = HOT
    return state
```

<div dir="rtl">

به این تابع دقت کن؛ یک نکتهٔ قشنگ از فصل ۱ دارد: حالت قبلی را به‌عنوان پارامتر می‌گیرد و حالت جدید را return می‌کند. اگر دما وسطِ هیچ‌کدام از شرط‌ها نبود — یعنی داخل فاصله امنیت — همان حالت قبلی، دست‌نخورده، برمی‌گردد.

حالا تستش کن (متن کامل برنامه در بخش بعد می‌آید — می‌توانی همان `03_station_full.py` را الان باز کنی و فقط بخش‌های Stage C را نگاه کنی):

> ⚠️ **مواظب باش:** برای سرد کردن، یخِ سادهٔ فریزر — همان یخِ خوراکی — کافی است؛ **«یخ خشک» نه!** آن یکی چیز دیگری است، دمایش به منفی هفتاد و چند درجه می‌رسد و دست را می‌سوزاند. کیسه باید بسته و خشک باشد و حتی یک قطره آب روی Breadboard نچکد: آب و مدار دشمن هم‌اند.

1. کیسهٔ یخ را **نزدیک** سنسور بگیر، نه چسبیده به آن.
2. چند خواندن صبر کن.
3. دست‌های گرمت را دور سنسور حلقه کن و دوباره صبر کن.

✅ **چک کن:** پرچم با یخ آرام می‌رود سمت سرد و با گرمای دستت برمی‌گردد — و روی مرز، بی‌لرزش می‌ماند. Stage C پاس شد!

## چالش: فاصله امنیت جلوی چه اتفاقی را می‌گیرد؟

---

**جواب:** جلوی پت‌پتِ لبِ مرز: وقتی دما دقیقاً روی آستانه رفت‌وبرگشت می‌کند، بدون MARGIN پرچم هر دو ثانیه می‌پرد. با فاصله امنیت، حالت فقط با عبورِ کامل از مرز عوض می‌شود و داخل نوار خنثی، همان حالت قبلی می‌ماند.

## ۵. Stage D — هشدار و پیچ‌های تنظیم: صدای ایستگاه

آخرین قطعه: Buzzer از ترم ۱ — مثبت به GPIO4، منفی به GND. و حالا بالای برنامه یک بلوک مرتب از ثابت‌ها: `COLD_LIMIT`، `HOT_LIMIT`، `MARGIN`، `ALERT_TEMP`، `DHT_EVERY` و `LIGHT_SAMPLES`. فصل ۶ اسم این‌ها را گذاشتیم «پیچ‌های تنظیم دستگاه» و امروز این حرف معنای کامل پیدا می‌کند: ایستگاه تو قرار است در اتاق **تو** کار کند، نه اتاق من. اتاقت گرم‌تر است؟ فقط پیچ `ALERT_TEMP` را بپیچان — یک عدد، یک‌جا، با اسم واضح؛ نه شکارِ عدد جادویی وسط صدوپنجاه خط کد.

منطق هشدار ساده است: موقع هر خواندن سنسور، اگر دما به `ALERT_TEMP` رسید، متغیر `alert` یک می‌شود و `double_beep()` دو بوق می‌زند؛ وگرنه صفر. حالا می‌خواهیم روی همهٔ صفحه‌ها هم خط «!! ALERT !!» دیده شود؛ پس تابع `show_screen` باید از ماجرا خبر داشته باشد — یک پارامتر جدید به اسم `alert` می‌گیرد. من امضای تابع را عوض می‌کنم و اجرا... و این را می‌بینم:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 147, in <module>
TypeError: function takes 5 positional arguments but 4 were given
```

<div dir="rtl">

مثل همیشه از خط آخر بخوان: «تابع ۵ ورودی می‌خواهد ولی ۴ تا دادی.» آهان! امضای تابع را عوض کرده‌ام ولی جایی که صدایش می‌زنم هنوز قدیمی است: `show_screen(screen, t, h, light)` مانده. این خطای کلاسیکِ integration است و سر همهٔ مهندس‌ها می‌آید: وقتی به تابعی پارامتر اضافه می‌کنی، **همهٔ** جاهایی که صدایش می‌زنی باید به‌روز شود. صدازدن را درست می‌کنیم: `show_screen(screen, t, h, light, alert)`.

برنامهٔ کامل ایستگاه — هر چهار Stage (فایل `03_station_full.py`):

</div>

```python
# Term 2 - Session 10 - Istgah havashenasi kamel (Stage A + B + C + D)
# In file ra ba esm e main.py rooye board zakhire kon ta standalone shavad

from machine import Pin, ADC, I2C, PWM
import ssd1306
import dht
import time

# ---------- pich-haye tanzim (constants) ----------
COLD_LIMIT = 20     # zir e in (ba margin): parcham SARD  (hamun COMFORT_MIN e dars 6)
HOT_LIMIT = 27      # balaye in (ba margin): parcham GARM (hamun COMFORT_MAX e dars 6)
MARGIN = 1          # faseleye amniat (dars 4) ke parcham naparad
ALERT_TEMP = 32     # az in dama be bala: boogh e hoshdar + ALERT rooye safhe
DHT_EVERY = 20      # har 20 dor e halghe (~2 sanie) yek bar DHT bekhan
LIGHT_SAMPLES = 5   # tedad nemune baraye miangin e noor (dars 5)

# halat haye parcham (state)
COLD = 0
OK = 1
HOT = 2

# ---------- sakht-afzar ----------
sensor = dht.DHT11(Pin(16))
ldr = ADC(Pin(35))
ldr.atten(ADC.ATTN_11DB)
button1 = Pin(32, Pin.IN, Pin.PULL_UP)  # feshorde = 0 (term 1)
buzzer = PWM(Pin(4))
buzzer.duty(0)  # avale kar saket bash (mesl e dars 6)
servo = PWM(Pin(13), freq=50)  # servo hatman freq=50 (dars 8)
i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)

# ---------- tabe-ha ----------
def map_value(x, in_min, in_max, out_min, out_max):
    # tabdil adad az yek baze be baze dige
    return (x - in_min) * (out_max - out_min) // (in_max - in_min) + out_min


def set_angle(deg):
    # 0 ta 180 daraje -> duty 26 ta 123 (0.5ms ta 2.4ms az 20ms)
    duty = int(26 + (deg / 180) * 97)
    servo.duty(duty)


def beep(freq_hz, duration_ms):
    # yek boogh e kutah ba buzzer (term 1)
    buzzer.freq(freq_hz)
    buzzer.duty(512)
    time.sleep_ms(duration_ms)
    buzzer.duty(0)


def double_beep():
    # do boogh e poshte ham baraye hoshdar (hamun 880 e dars 6)
    beep(880, 80)
    time.sleep_ms(80)
    beep(880, 80)


def read_light_avg():
    # 5 nemune az LDR + miangin (dars 5) -> adad e aroom tar
    readings = []
    for i in range(LIGHT_SAMPLES):
        readings.append(ldr.read())
        time.sleep_ms(10)
    total = 0
    for r in readings:
        total = total + r
    return total // len(readings)  # taghsim e sahih -> adad e sahih


def new_flag_state(t, state):
    # parcham ba faseleye amniat: faghat ba obur e KAMEL az marz avaz mishavad
    if t <= COLD_LIMIT - MARGIN:
        state = COLD
    if t >= COLD_LIMIT + MARGIN and t <= HOT_LIMIT - MARGIN:
        state = OK
    if t >= HOT_LIMIT + MARGIN:
        state = HOT
    return state


def move_flag(state):
    # se jaygah e parcham e kaghazi rooye servo
    if state == COLD:
        set_angle(160)
    elif state == OK:
        set_angle(90)
    elif state == HOT:
        set_angle(20)


def show_screen(screen, t, h, light, alert):
    # hame ye naghashi e safhe yek ja: aval fill(0), akharesh show()
    oled.fill(0)
    if screen == 0:
        oled.text("== WEATHER ==", 0, 0)
        oled.text(f"TEMP: {t} C", 0, 20)
        oled.text(f"HUM:  {h} %", 0, 32)
    elif screen == 1:
        oled.text("== LIGHT ==", 0, 0)
        oled.text(f"RAW: {light}", 0, 20)
        bar = map_value(light, 0, 4095, 0, 128)
        oled.fill_rect(0, 34, bar, 10, 1)
    else:
        oled.text("== ABOUT ==", 0, 0)
        oled.text("Weather Station", 0, 20)
        oled.text("Term 2 Project", 0, 32)
    if alert == 1:
        oled.text("!! ALERT !!", 20, 52)  # ghabl az show() bashad!
    oled.show()


# ---------- halghe asli ----------
screen = 0
flag_state = OK
t = 0
h = 0
light = 0
alert = 0
timer = 0  # shomarande ye makoos: 0 yani vaghte khandan e sensor

set_angle(90)  # shoroo az vasat: "90 daraje, bad parcham"

while True:
    if timer <= 0:
        try:
            sensor.measure()
            t = sensor.temperature()
            h = sensor.humidity()
        except OSError:
            print("Khata dar khandan DHT! sim-keshi ra check kon")
        light = read_light_avg()
        flag_state = new_flag_state(t, flag_state)
        move_flag(flag_state)
        if t >= ALERT_TEMP:
            alert = 1
            double_beep()
        else:
            alert = 0
        timer = DHT_EVERY
    if button1.value() == 0:
        screen = screen + 1
        if screen > 2:
            screen = 0  # bargasht be safhe ye aval
        time.sleep_ms(200)  # debounce (term 1)
    show_screen(screen, t, h, light, alert)
    timer = timer - 1
    time.sleep_ms(100)
```

<div dir="rtl">

> 💡 **نکته — وقتی خواندن شکست بخورد چه عددی دستِ برنامه است؟** به ترتیب خط‌ها نگاه کن: `except OSError` فقط پیام چاپ می‌کند، و بعدش پرچم و هشدار روی همان `t` قدیمی حساب می‌شوند. برای یک خواندنِ ازدست‌رفته وسط کار این عمداً خوب است — دستگاه به‌خاطر یک سکسکه پرچمش را نمی‌پراند. ولی یک حالت خاص دارد: اگر **همان اولین** خواندن شکست بخورد، `t` هنوز همان صفرِ بالای برنامه است و پرچم می‌رود روی «سرد». چیزی خراب نشده؛ با اولین خواندن موفق سر جایش برمی‌گردد، مگر دما درست ۲۰ یا ۲۷ باشد که داخل فاصله امنیت است و پرچم تا خواندنِ بیرون از آن سرد می‌ماند. اگر آزارت می‌دهد، همین حالا یک ارتقای کوچک برای خودت داری: یک متغیر «هنوز دادهٔ واقعی نگرفته‌ام» بگذار و تا اولین خواندن موفق، پرچم و هشدار را دست نزن — دقیقاً همان ترفندی که فصل ۱۱ برای MIN/MAX می‌سازیم.

اما تست هشدار چطور؟ صبر کنیم اتاق ۳۲ درجه شود؟! ترفند تست مهندسی: آستانه را موقتاً بیاور پایین.

1. `ALERT_TEMP` را موقتاً کمی زیر دمای فعلی اتاقت بگذار (مثلاً چند درجه کمتر از عددی که صفحهٔ WEATHER نشان می‌دهد).
2. Run بزن و منتظر اولین خواندن سنسور بمان.
3. تست که تمام شد، `ALERT_TEMP` را به مقدار اصلی‌اش برگردان.

✅ **چک کن:** دو بوق هشدار می‌آید و خط «!! ALERT !!» پایین همهٔ صفحه‌ها می‌نشیند. هر چهار Stage سبز!

> 🔧 **اگر کار نکرد:** بوق آمد ولی خط ALERT روی صفحه نیامد — و هیچ خطای قرمزی هم در کار نیست؟ این خطای «بی‌صدا»ی فصل ۷ است: خط `oled.text("!! ALERT !!", 20, 52)` بعد از `oled.show()` نوشته شده. هر چه بعد از show بیاید فقط در چرک‌نویسِ حافظه می‌ماند و هیچ‌وقت به شیشهٔ صفحه نمی‌رسد — خط را ببر بالای `oled.show()`. و اگر وقتی Servo می‌چرخد صفحه خاموش یا برد ری‌استارت می‌شود، افت ولتاژ داری: سیم قرمز Servo فقط به VIN و کابل USB کوتاه و دیتادار.

## ۶. لحظهٔ استقلال: main.py

و آخرین حرکت این فصل، مهم‌ترینش است. این برنامه تا الان فقط وقتی اجرا می‌شود که ما در Thonny دکمهٔ Run را بزنیم. ولی این یک **دستگاه** است؛ باید مستقل باشد. از ترم ۱، فصل ۵ یادت هست: فایلی که با اسم `main.py` روی خود برد ذخیره شود، با هر بار برق‌دار شدن خودش اجرا می‌شود:

![دو قاب کنار هم: در قاب اول ایستگاه با کابل USB به لپ‌تاپ وصل است و فایل main.py مثل یک ایمپلنت حافظه در دل تراشهٔ ESP32 می‌نشیند؛ در قاب دوم لپ‌تاپ محو شده و خداحافظی می‌کند و ایستگاه با پاور بانک روشن است، با نشان افتخار STANDALONE](/lesson-assets/t2-s10-term-project-build/prompt/06-image-mainpy-standalone.png)

1. منوی File، بعد Save as.
2. مقصد: MicroPython device — نه This computer.
3. اسم فایل، دقیقاً: `main.py`.
4. حالا لحظهٔ حقیقت — کابل USB را از کامپیوتر جدا کن و ایستگاه را به پاور بانک بزن.

✅ **چک کن:** ایستگاه بالا می‌آید، صفحه روشن می‌شود و پرچم روی ۹۰ می‌ایستد — بدون کامپیوتر، بدون Thonny. به این می‌گویند standalone. تو یک دستگاه واقعی ساخته‌ای؛ چیزی که می‌شود روی میز گذاشت و به مهمان نشان داد. جشن بگیر!

> 🔧 **اگر کار نکرد:** با USB کار می‌کند ولی با پاور بانک هیچ اتفاقی نمی‌افتد؟ برنامه یا با اسم دیگری ذخیره شده یا روی کامپیوتر ذخیره شده، نه روی برد: دوباره File ← Save as ← MicroPython device ← نام دقیق `main.py`. (بعضی پاور بانک‌ها هم با مصرف کم خودشان را خاموش می‌کنند — شارژر دیواری USB را امتحان کن.)

## چالش: اگر با اسم station.py ذخیره کنیم چه می‌شود؟

برنامه را با اسم `station.py` روی برد ذخیره کرده‌ای؛ به پاور بانک می‌زنی — چه اتفاقی می‌افتد و چرا؟

---

**جواب:** هیچ! فایل روی برد هست، ولی برد بعد از هر روشن شدن فقط دنبال فایلی به اسم `main.py` می‌گردد و همان را خودکار اجرا می‌کند. `station.py` سر جایش می‌ماند و هیچ‌وقت خودبه‌خود اجرا نمی‌شود — این اسمِ خاص یعنی «اجرای خودکار».

## واژه‌های تازه این فصل

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Station | اِستِیشِن | ایستگاه — دستگاهی که چند کار مرتبط را یک‌جا انجام می‌دهد |
| Integration | اینتِگرِیشِن | سوارکردن قطعه‌های جدا کنار هم طوری که با هم درست کار کنند |
| Stage | اِستِیج | مرحله — هر قدم ساخت که جداگانه تست می‌شود؛ save point مهندس‌ها |
| Constant | کانْستَنت | مقدار ثابتِ بانامِ بالای برنامه — «پیچ تنظیم» دستگاه |
| Alert | اَلِرت | هشدار — واکنش دستگاه وقتی عددی از حد تعیین‌شده می‌گذرد |
| Standalone | اِستَندْاِلون | مستقل — کارکردن دستگاه بدون کامپیوتر، فقط با برق |

## تمرین‌ها

اول چک‌لیست پایان فصل: ایستگاه با هر شش قطعه یک‌جا کار می‌کند؛ هر چهار Stage را جدا-جدا تست کرده‌ای و می‌توانی توضیح بدهی چرا یک‌جا وصل‌نکردن هوشمندانه است؛ با پاور بانک هم بالا می‌آید؛ و بدون گشتن در کد می‌دانی کدام «پیچ تنظیم» آستانهٔ هشدار را عوض می‌کند. اگر هر چهار تا بله است، برو سراغ تمرین‌ها — و ایستگاه را باز نکن؛ فصل بعد به همین دستگاه نیاز داری!

- **تمرین اجباری:** به ایستگاه یک صفحهٔ چهارم اضافه کن که کمترین و بیشترین دمای دیده‌شده از لحظهٔ روشن شدن را نشان بدهد (min/max دستی فصل ۵ — مواظب مقدار اولیه باش! سرنخ: «شروع با عضو اول، نه با صفر»). سقف صفحه‌ها را هم یادت نرود: `if screen > 3`.
- **تمرین ستاره‌دار ⭐:** «حالت شب» بساز: وقتی `read_light_avg` از یک آستانهٔ تاریکی (خودت کالیبره کن — آیین فصل ۴) پایین‌تر رفت، به‌جای صفحهٔ عادی یک ماه با `fill_rect` بکش و هشدار صوتی را هم بی‌صدا کن (`alert` بماند ولی `double_beep` صدا نزند) — چون هیچ‌کس نصفه‌شب از ایستگاهش بوق نمی‌خواهد!

## در فصل بعد

فصل بعد جشن پایان ترم است: منوی ارتقا با شش ایده، دفترچهٔ مهندسی و ویدیوی «پروژهٔ من» — ایستگاهت را شخصی می‌کنی و به دنیا نشانش می‌دهی. بگذار تا آن موقع روی میزت کار کند.

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t2/s10-term-project-build (یادستان, Yaadestan)
