# فصل ۱۱ — پروژه ترم: ارتقا و نمایش

<div dir="rtl">

# فصل ۱۱ — پروژه ترم: ارتقا و نمایش

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

به آخرین فصل ترم ۴ خوش آمدی! ده فصل پیش، ESP32 تو دستگاهی بود که فقط دنیای چند سانتی‌متری خودش را می‌شناخت. امروز به شبکه وصل می‌شود، وب‌سرور دارد، و با یک هوش مصنوعی واقعی آن‌سر دنیا حرف می‌زند — و تو تک‌تک این پله‌ها را خودت ساختی.

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

![کولاژ جشنِ پایان مسیر: یک مسیرِ نورانیِ پیچ‌درپیچ با ایستگاه‌های نقطه‌عطف — برد ESP32 با نشانِ موج WiFi، پنجره مرورگر با یک کارت آب‌وهوای کوچک برچسب HTTP، گوشی با یک ریموت وبِ دکمه‌دار، صفحه داشبورد با گیج سنسورها، کارت JSON با آکولاد، یک گاوصندوق قفل با آیکون کلید، یک ابرِ مغز با برچسب AI، و ته مسیر یک دستیار میز (سه LED، بازر، OLED کوچک) با جعبه چتِ گوشی؛ کاغذرنگی و درخششِ ملایم، حسِ پیشرفت از چپ به راست](/lesson-assets/t4-s11-term-project-upgrade/prompt/01-image-term4-journey.png)

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

- با الگوی سه‌قدمی (RULES ← ALLOWED ← do_action) یک فرمان جدید به دستیار اضافه کنی و ارتقای «دستیار سنسوردار» را کامل بسازی.
- توضیح بدهی چرا عدد دما را سنسور می‌دهد نه AI — و این طراحی چطور جلوی hallucination را می‌گیرد.
- برای پاسخ‌های غیرمنتظره سرویس (نبودِ `candidates`) گارد بسازی و پیام خطای سرویس را کارآگاهانه بخوانی.
- درباره جایگزین‌های پولی (OpenAI GPT و Anthropic Claude) با معیار ساده و همراه خانواده تصمیم آگاهانه بگیری.
- صفحه دفترچه مهندسی را کامل و ویدیوی «پروژه من» را با رعایت ایمنی اشتراک‌گذاری ضبط کنی.

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

- **از فصل ۱۰:** دستیار هوشمند کامل (میز یا ربات) با نگهبان لیست سفید — همه‌چیزِ امروز روی آن سوار است؛ جدول تست ۱۰ فرمان (تکلیف) را انجام داده باش.
- **از فصل ۹:** بدنه تماس مستقیم با Gemini و `gc.collect`.
- **از فصل ۸:** محدودیت‌های AI و hallucination — ستون بحث «عدد از سنسور، فهم از AI».
- **از فصل ۶:** rate limit، قانون کارآگاه `print(data)` و خطای `KeyError`.
- **از فصل ۴:** خواندن DHT11 با زره `try/except` — همان سنسوری که در ترم ۲، فصل ۶ شناختی، امروز به دستیار پیوند می‌خورد.
- **از ترم ۲، فصل ۱۱:** دفترچه مهندسی و الگوی پنج‌قدمی ویدیوی «پروژه من» — امروز نسخه ابری‌اش را می‌سازیم.

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

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| دستیار کامل فصل ۱۰ (نسخه میز: LED×۳، Buzzer، OLED) | ۱ | نسخه رباتی هم قابل ارتقاست |
| DHT11 (کیت ترم ۲) | ۱ | بدون آن، ارتقای شماره ۲ منو را بساز (blink) |
| WiFi + کلید Gemini در `secrets.py` | — | هات‌اسپات گوشی |
| دفترچه مهندسی + خودکار | ۱ | همان دفترچه ترم‌های قبل |
| گوشی برای ضبط ویدیوی «پروژه من» | ۱ | دوربین کامپیوتر |

> 🧪 **آزمایشگاه:** کد نهایی این فصل در آزمایشگاه هم هست — ولی صادقانه: بخش WiFi و تماس با AI در شبیه‌ساز فعلی اجرا نمی‌شود. کد را همان‌جا ببین و کپی کن؛ اجرای واقعی به یک برد با WiFi احتیاج دارد. [برو به آزمایشگاه](/lab).

## ۱. جشن مسیر: از برد تنها تا دستیار ابری

قبل از هر ارتقایی، یک بار با عینک ترم ۱، فصل ۱ به دستیارت نگاه کن: چرخه Sense-Think-Act. دستیار تو **حس می‌کند** — فرمان متنی از مرورگر می‌آید. **فکر می‌کند** — ولی حالا فکرکردنش **دوطبقه** است: طبقه ابری، Gemini، جمله آزاد تو را می‌فهمد و پیشنهاد می‌دهد؛ طبقه محلی، نگهبان لیست سفید، تصمیم نهایی را می‌گیرد. و **عمل می‌کند** — LED و Buzzer و OLED یا چرخ‌های ربات. می‌دانی این یعنی چه؟ تو یک ربات کامل ساخته‌ای که مغزش تا ابر کش آمده!

## چالش: Sense و Think و Act دستیار تو

سه ستون بکش و دستیارت را تقسیم کن: کدام قطعه Sense است، کدام دو بخش با هم Think را می‌سازند (طبقه ابری و محلی را جدا بنویس)، و کدام قطعه‌ها Act؟ اول خودت پر کن، بعد باز کن.

---

**جواب:** Sense: فرمان متنی که از فرم مرورگر می‌آید. Think دوطبقه است: طبقه ابری = Gemini که جمله آزاد را می‌فهمد و یک action **پیشنهاد** می‌دهد؛ طبقه محلی = نگهبان `if action in ALLOWED` که **تصمیم** می‌گیرد. Act: LED و Buzzer و OLED (یا چرخ‌های ربات).

## ۲. ساخت زنده: دستیار سنسوردار

ارتقای امروز از یک سؤال ساده شروع می‌شود. از دستیار می‌پرسم: «dama-ye otagh chand ast?» — و جواب: `in farman ra balad nistam!`. خب، معلوم است؛ چنین فرمانی در فهرست نیست. ولی صبر کن... چرا خود AI جوابم را ندهد؟ Gemini که می‌داند دما یعنی چه!

اینجا یکی از قشنگ‌ترین درس‌های ترم است: Gemini **در اتاق تو دماسنج ندارد**. اگر بگذاریم آزادانه جواب بدهد، فصل ۸ را یادت بیاور: با اعتمادبه‌نفس کامل یک عدد **می‌سازد** — hallucination. قانون طراحی امروز را بنویس: **عدد از سنسور خودت می‌آید؛ فهمِ جمله از AI.** پس یک action جدید تعریف می‌کنیم: `report_temp` — AI فقط تشخیص می‌دهد که تو دنبال دمایی، و DHT11 خودت عدد واقعی را می‌دهد.

فایل فصل ۱۰ را با اسم جدید ذخیره کن — نسخه کارکرده را هرگز مستقیم دستکاری نکن — و DHT11 را مثل فصل ۴ به پایه ۱۶ ببند. فرمان جدید سه قدم دارد؛ این الگو را قاب کن، چون هر ارتقای آینده‌ات همین است:

1. **قرارداد AI** — در RULES اسم `report_temp` را به فهرست اضافه کن و یک جمله راهنما.
2. **لیست سفید** — `report_temp` را به `ALLOWED` اضافه کن.
3. **اجرا** — یک شاخه جدید در `do_action`.

من عمداً با قدم‌های یک و سه شروع می‌کنم و قدم دو را... خب، بعداً! قرارداد AI این‌طور می‌شود:

</div>

```python
RULES = """You are the brain of a desk assistant device built on ESP32.
The user command may be in Persian, Finglish or English.
Reply with ONE line of raw JSON only, no code fences, no extra words:
{"action": "NAME"}
NAME must be EXACTLY one of:
red_on, red_off, yellow_on, yellow_off, green_on, green_off, beep, all_off, report_temp
Use report_temp when the user asks about the room temperature or how warm it is.
If the command matches none of them, reply: {"action": "unknown"}
User command: """
```

<div dir="rtl">

حالا اجرا، و در گوشی: «cheghadr garm ast otagh?» — و جواب: `in farman ra balad nistam!` و در Shell: `action: unknown`. بلد نیستم؟! ولی من که فرمان را اضافه کردم!

کارآگاه‌بازی: یک `print(text)` موقت داخل `ask_ai` می‌گذارم و دوباره می‌پرسم. متن خام AI می‌آید: `{"action": "report_temp"}` — AI کارش را درست انجام داده! پس چه کسی جواب را کشت؟ خط بعدی را نگاه کن: `if action in ALLOWED` — نگهبان! `report_temp` هنوز در لیست سفید نیست و نگهبان ما — همان‌طور که آموزشش داده‌ایم — بدون استثنا ردش کرده. حتی سازنده‌اش را! این «باگ» در واقع بهترین خبر امروز است: ثابت شد نگهبان واقعاً کار می‌کند و هیچ actionِ ثبت‌نشده‌ای — نه از AI، نه از فراموش‌کاری خود ما — به سخت‌افزار نمی‌رسد.

قدم دو را کامل می‌کنم؛ `report_temp` به `ALLOWED` اضافه می‌شود:

</div>

```python
ALLOWED = ["red_on", "red_off", "yellow_on", "yellow_off",
           "green_on", "green_off", "beep", "all_off", "report_temp"]
```

<div dir="rtl">

دوباره اجرا:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 164, in <module>
  File "<stdin>", line 97, in do_action
NameError: name 'sensor' isn't defined
```

<div dir="rtl">

خطای قرمز آشنای قدیمی! `NameError` یعنی «این اسم را نمی‌شناسم» — و حق دارد: در شاخه جدید نوشته‌ام `sensor.measure()` ولی هیچ‌جا شیء `sensor` را نساخته‌ام؛ `import dht` هم یادم رفته. دو خط بالای فایل اضافه می‌شود: `import dht` و شیء سنسور:

</div>

```python
sensor = dht.DHT11(Pin(16))   # cheshm-e dama-ye dastyar (hamun pin-e jalase 4)
```

<div dir="rtl">

و شاخه سومِ do_action — خواندن با زره `try/except` طبق عادت فصل ۴، که اگر سنسور قهر کرد دستیار نمیرد:

</div>

```python
    elif action == "report_temp":
        # ghadam-e 3: adad-e dama az sensor-e KHODET - na az AI!
        try:
            sensor.measure()
            temp = sensor.temperature()
            print(f"dama-ye otagh: {temp} C")
            oled.fill(0)
            oled.text("ROOM TEMP:", 0, 0)
            oled.text(f"{temp} C", 0, 20)
            oled.show()
        except OSError:
            print("khata dar khandan-e DHT11! sim-ha ra check kon")
```

<div dir="rtl">

حالا اجرای واقعی: «dama-ye otagh chand ast?» — روی OLED: `ROOM TEMP:` و عدد واقعی اتاق! از گوشی، به زبان خودت پرسیدی و سخت‌افزار روی میزت جواب داد — با عددِ واقعی، نه حدسِ AI.

حالا که ذوق کرده‌ام، پشت‌سرهم سؤال می‌بارانم: دما؟ چراغ سبز؟ بوق؟ دما؟... و ناگهان:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 153, in <module>
  File "<stdin>", line 56, in ask_ai
KeyError: candidates
```

<div dir="rtl">

`KeyError` — از فصل ۶ می‌شناسیش: «کلیدی به این اسم در دیکشنری نیست». یعنی جواب سرویس این بار اصلاً `candidates` نداشته! قانون کارآگاه: `print(data)` — و ببین چه آمده:

</div>

```text
{'error': {'code': 429, 'message': 'Resource has been exhausted (e.g. check quota).', 'status': 'RESOURCE_EXHAUSTED'}}
```

<div dir="rtl">

سرویس به‌جای جواب، یک پیام خطا فرستاده: «سهمیه‌ات فعلاً تمام شد» — همان rate limit فصل ۶؛ سطح رایگان در هر دقیقه سقفی دارد و رگبار سؤال‌های من از آن رد شد. عدد سقف را حفظ نکن — عوض می‌شود. درس مهم‌تر: پاسخ نامعتبر فقط «JSON خراب» نیست؛ گاهی ساختارش کلاً فرق دارد. پس آخرین گارد پروژه را می‌سازیم: خطِ خواندن `candidates` را در یک `try/except KeyError` می‌پیچیم — اگر نبود، پیام سرویس را چاپ کن و `unknown` برگردان:

</div>

```python
    try:
        text = data["candidates"][0]["content"]["parts"][0]["text"]
    except KeyError:
        # guard-e jadid-e emrooz: service be jaye candidates, error dade
        print("javab-e AI candidates nadasht! payam-e service:")
        print(data)
        return "unknown"
```

<div dir="rtl">

حالا دستیار وقتی سهمیه تمام شود مؤدب می‌ماند: «بلد نیستم» — و چند لحظه بعد که سهمیه برگشت، دوباره سرحال است. `print` موقت را برمی‌دارم؛ برنامه کامل و نهایی — فایل `01_assistant_upgraded.py`:

</div>

```python
# Term 4 - Session 11 - dastyar-e sensor-dar: upgrade-e report_temp + guard-e candidates
# olgu-ye 3 ghadami-ye farman-e jadid: 1) RULES  2) ALLOWED  3) do_action
# hagh-e talayi: adad-e dama az SENSOR-e khodet miayad, na az AI (zedd-e hallucination!)
# ejraye standalone: hamin file ra ba esm-e main.py rooye bord zakhire kon
from machine import Pin, PWM, I2C
import network
import socket
import urequests
import json
import ssd1306
import dht
import secrets
import gc
import time

# address + esm-e model: gahi avaz mishavand (404 = esm-e model avaz shode)
GEMINI_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent"

# kelid dar header miravad - daghighan olgu-ye jalase 9
HEADERS = {
    "Content-Type": "application/json",
    "x-goog-api-key": secrets.GEMINI_API_KEY,
}

# ghadam-e 2: farman-e jadid dar list-e sefid (agar yadet beravad, guard radd-esh mikonad!)
ALLOWED = ["red_on", "red_off", "yellow_on", "yellow_off",
           "green_on", "green_off", "beep", "all_off", "report_temp"]

# ghadam-e 1: farman-e jadid dar gharardad-e AI
RULES = """You are the brain of a desk assistant device built on ESP32.
The user command may be in Persian, Finglish or English.
Reply with ONE line of raw JSON only, no code fences, no extra words:
{"action": "NAME"}
NAME must be EXACTLY one of:
red_on, red_off, yellow_on, yellow_off, green_on, green_off, beep, all_off, report_temp
Use report_temp when the user asks about the room temperature or how warm it is.
If the command matches none of them, reply: {"action": "unknown"}
User command: """

led_red = Pin(25, Pin.OUT)
led_yellow = Pin(26, Pin.OUT)
led_green = Pin(27, Pin.OUT)
buzzer = PWM(Pin(4), freq=880, duty=0)
i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)
sensor = dht.DHT11(Pin(16))   # cheshm-e dama-ye dastyar (hamun pin-e jalase 4)

def ask_ai(command):
    # farman-e azad -> Gemini -> faghat esm-e yek action
    gc.collect()   # jalase 9: ghabl az har tamas hafeze ra tamiz kon!
    body = {"contents": [{"parts": [{"text": RULES + command}]}]}
    r = urequests.post(GEMINI_URL, headers=HEADERS,
                       data=json.dumps(body))
    data = r.json()
    r.close()
    try:
        text = data["candidates"][0]["content"]["parts"][0]["text"]
    except KeyError:
        # guard-e jadid-e emrooz: service be jaye candidates, error dade
        print("javab-e AI candidates nadasht! payam-e service:")
        print(data)
        return "unknown"
    # jarrahi-ye reshte: faghat az avalin { ta avalin } (zedd-e code fence)
    start = text.find("{")
    end = text.find("}")
    if start == -1 or end == -1:
        return "unknown"
    try:
        answer = json.loads(text[start:end + 1])
        action = answer["action"]
    except ValueError:
        return "unknown"     # javab JSON-e salem nabud -> radd
    except KeyError:
        return "unknown"     # JSON bood vali action nadasht -> radd
    if action in ALLOWED:
        return action        # e'tebar-sanji: faghat az list-e sefid!
    return "unknown"         # har chiz-e digar -> radd (hatta agar AI esrar kard)

def do_action(action):
    # inja faghat action-haye list-e sefid miresand - ejra, bedoon-e sorprize
    if action == "red_on":
        led_red.value(1)
    elif action == "red_off":
        led_red.value(0)
    elif action == "yellow_on":
        led_yellow.value(1)
    elif action == "yellow_off":
        led_yellow.value(0)
    elif action == "green_on":
        led_green.value(1)
    elif action == "green_off":
        led_green.value(0)
    elif action == "beep":
        buzzer.duty(512)
        time.sleep(0.3)
        buzzer.duty(0)
    elif action == "all_off":
        led_red.value(0)
        led_yellow.value(0)
        led_green.value(0)
        buzzer.duty(0)
    elif action == "report_temp":
        # ghadam-e 3: adad-e dama az sensor-e KHODET - na az AI!
        try:
            sensor.measure()
            temp = sensor.temperature()
            print(f"dama-ye otagh: {temp} C")
            oled.fill(0)
            oled.text("ROOM TEMP:", 0, 0)
            oled.text(f"{temp} C", 0, 20)
            oled.show()
        except OSError:
            print("khata dar khandan-e DHT11! sim-ha ra check kon")

def get_command(request):
    # matn-e farman ra az URL biroon mikeshad: GET /ask?cmd=matn HTTP/1.1
    start = request.find("cmd=")
    if start == -1:
        return ""
    start = start + 4
    end = request.find(" ", start)
    cmd = request[start:end]
    cmd = cmd.replace("+", " ")
    return cmd

wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(secrets.WIFI_SSID, secrets.WIFI_PASS)
print("dar hal-e ettesal be WiFi...")
tries = 0
while not wlan.isconnected() and tries < 15:
    time.sleep(1)
    tries = tries + 1
if wlan.isconnected():
    print("vasl shod! IP:", wlan.ifconfig()[0])
else:
    print("vasl nashod - WiFi ra ba code-haye jalase 1 check kon")

oled.fill(0)
oled.text("AIRO ASSISTANT", 0, 0)
oled.text("V2 - READY!", 0, 20)
oled.show()

s = socket.socket()
s.bind(("0.0.0.0", 80))
s.listen(1)
print("dastyar-e sensor-dar amade ast!")

while True:
    conn, addr = s.accept()
    request = str(conn.recv(1024))

    command = get_command(request)
    if command == "":
        answer = "montazer-e farman-e to..."
    else:
        print("farman:", command)
        try:
            action = ask_ai(command)
        except OSError:
            action = "unknown"
            print("khata dar tamas ba AI - internet va kelid ra check kon")
        print("action:", action)
        # aval esm-e action rooye OLED; bad do_action (report_temp roosh minevisad)
        oled.fill(0)
        oled.text("AIRO ASSISTANT", 0, 0)
        oled.text(action, 0, 20)
        oled.show()
        if action == "unknown":
            answer = "in farman ra balad nistam!"
        else:
            do_action(action)
            answer = "anjam shod: " + action

    html = f"""<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width">
  <title>AIRO Assistant</title>
</head>
<body>
  <h1>AIRO Smart Assistant V2</h1>
  <form action="/ask">
    <input name="cmd" placeholder="farman-e to...">
    <input type="submit" value="BEFEREST">
  </form>
  <p>Javab: <b>{answer}</b></p>
</body>
</html>"""

    conn.send("HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n")
    conn.send(html)
    conn.close()
```

<div dir="rtl">

> 💡 **نکته:** یک تغییر کوچک نسبت به فصل ۱۰: آنجا اسم action **بعد از** اجرای `do_action` روی OLED می‌نشست؛ در این نسخه آن سه خط یک پله بالاتر آمده‌اند تا شاخه `report_temp` بتواند بعدش دما را روی نمایشگر بنویسد. اگر جای این دو را عوض کنی، دما فوری از صفحه پاک می‌شود و اسم action رویش می‌افتد.

✅ **چک کن:** با گوشی بپرس دمای اتاق چند است — روی OLED عددِ واقعیِ سنسور بیاید، نه یک عددِ ساختگی. حالا سنسور را کمی گرم کن و دوباره بپرس: عدد باید عوض شود. این اثبات «عدد از سنسور، نه از AI» است. 🎉

> 🔧 **اگر کار نکرد:** فرمان جدید همیشه «balad nistam» می‌گیرد ولی AI درست جواب داده؟ قدم ۲ جا افتاده — `report_temp` در `ALLOWED` نیست و نگهبان (درست!) ردش می‌کند. `NameError: name 'sensor'`؟ دو خط `import dht` و ساختِ شیء `sensor` را بالای فایل بگذار. `KeyError: candidates` وسط فرمان‌های پشت‌سرهم؟ گارد `try/except KeyError` را نگه دار، `print(data)` بزن، و چند لحظه آرام‌تر فرمان بده تا سهمیه برگردد.

> 🔧 **دو خطای نادر هنوز گارد ندارند:** اگر سرویس اصلاً JSON نفرستد، `r.json()` خطای `ValueError` می‌دهد؛ و اگر لیست `candidates` خالی باشد، `[0]` خطای `IndexError` می‌دهد. `except OSError` حلقهٔ سرور هیچ‌کدام را نمی‌گیرد و برنامه می‌ایستد. اگر ایستاد، پیام آخر Shell را بخوان و دکمهٔ RESET برد را بزن.

سه شکار امروز را مرور کن: نگهبانی که جلوی خودمان را گرفت، `NameError` فراموشی، و `KeyError` سهمیه — هر سه در دفترچه!

## چالش: الگوی سه‌قدمی و قدمِ فراموش‌شده

جواب بده: الگوی سه‌قدمی فرمان جدید چیست، و اگر فقط قدم یک و دو را انجام بدهی و قدم سه یادت برود، موقع فرمان‌دادن دقیقاً چه اتفاقی می‌افتد؟ (راهنمایی: زنجیره if/elif در `do_action` با اسم ناشناخته چه می‌کند؟)

---

**جواب:** سه قدم یعنی: (۱) اضافه‌کردن به RULES، (۲) اضافه‌کردن به `ALLOWED`، (۳) شاخه جدید در `do_action`. اگر قدم سه را یادت برود، فرمان از نگهبان **رد می‌شود** (چون در `ALLOWED` هست) و به `do_action` می‌رسد. ولی آنجا هیچ `elif`ای با آن اسم مطابقت نمی‌کند، پس زنجیره بی‌سروصدا از همه شاخه‌ها می‌گذرد و **هیچ کاری انجام نمی‌گیرد**. یعنی دستگاه می‌گوید «انجام شد» ولی در عمل هیچ اتفاقی نمی‌افتد. برای همین هر فرمان جدید حتماً باید از هر سه قدم رد شود.

## ۳. درخت مهارت دستیار: ارتقای بعدی تو

`report_temp` فقط یک شاخه بود؛ درخت مهارت دستیار تو پنج شاخه دارد:

| # | ارتقا | سختی | سوار بر شانه |
|---|---|---|---|
| ۱ | شخصیت دستیار: اسم و لحن دلخواه در RULES (مثلاً جواب‌های بامزه) | ★ | فصل ۷ — پرامپت چیست |
| ۲ | فرمان جدید `blink`: سه چشمک همه LEDها (تمرین ستاره‌دار فصل ۱۰، حالا رسمی!) | ★ | الگوی سه‌قدمی امروز |
| ۳ | دستیار سنسوردار: `report_temp` | ★★ | امروز با هم ساختیم |
| ۴ | صفحه بهتر: دکمه‌های میان‌بر فصل ۵ + فرم متنی، کنار هم در یک صفحه | ★★ | فصل ۵ — ریموت دکمه‌ای |
| ۵ | گزارشگر هوشمند: action ‏`report` که داده چند سنسور را در پرامپت می‌گذارد و جواب زبان طبیعی AI را روی صفحه وب می‌آورد | ★★★ | فصل ۸ — دستیار سنسوری |

شاخه پنج را جدی بگیر — ترکیب فصل ۸ و پروژه امروز است و دستیار را به یک گزارشگر واقعی خانه تبدیل می‌کند. اگر مسیر رباتی رفته‌ای، همه همین‌ها برای ربات هم معنا دارد: فرمان جدید `spin` یا `patrol` با همان سه قدم. قانون همیشگی یادت نرود: یکی‌یکی؛ هر ارتقا اول تست، بعد بعدی — و هر فرمان جدید حتماً از هر سه قدم رد شود، وگرنه نگهبان خودت جلویت را می‌گیرد!

## ۴. گفت‌وگوی خانوادگی: Gemini ماند یا GPT و Claude؟

حالا آن گفت‌وگوی مهم. کل این ترم با Gemini کار کردیم چون سطح رایگان دارد و ساخت کلیدش کارت بانکی نمی‌خواهد. ولی از روز اول قول دادم: این دوره به هیچ شرکتی قفل نیست. دو جایگزین بزرگ و پولی را هم بشناس: **OpenAI GPT** و **Anthropic Claude**. هر دو «پرداخت به‌ازای مصرف» هستند: مثل شارژ سیم‌کارت، هر چه بیشتر بپرسی، بیشتر پرداخت می‌کنی. عمداً نمی‌گویم کدام «بهتر» است — این جمله بدون آزمایش هیچ معنایی ندارد و شش ماه دیگر هم عوض می‌شود؛ راه درست، امتحان‌کردن هر دو با پرامپت‌های خودِ توست.

و حالا مهم‌ترین جمله فنی این بخش: پروژه تو برای مهاجرت به هیچ‌کدام، بازنویسی نمی‌خواهد! الگویی که یاد گرفتی — HTTP POST، بدنه JSON، کلید API در هدر — الگوی مشترک کل صنعت است؛ فقط سه چیز عوض می‌شود: **آدرس** سرویس، **کلید**، و **شکل JSON** بدنه و جواب. ساختار `ask_ai` تو سر جایش می‌ماند — همین است معنی مهارتِ قابل‌انتقال.

![راهنمای تصمیم برای خانواده‌ها: دور یک میز، یک والد و یک نوجوان به سه کارت سرویسِ انتزاعی نگاه می‌کنند — یکی با نشانِ جعبه‌کادو و برچسب Free tier، دو تای دیگر با نشانِ کنتورِ سکه و برچسب Pay as you go؛ بالای کارت‌ها یک دیاگرامِ الگوی مشترک که یک بلوک کد دست‌نخورده می‌ماند و فقط سه توکنِ کوچکِ قابل‌تعویض عوض می‌شوند با برچسب‌های URL و Key و JSON؛ پایین یک کارتِ چک‌لیست با چهار علامتِ سؤالِ بزرگ؛ بدون قیمت، بدون عدد، بدون لوگوی واقعی شرکت‌ها](/lesson-assets/t4-s11-term-project-upgrade/prompt/03-image-family-decision-card.png)

اما کدام را انتخاب کنید؟ این تصمیم **با خانواده** است، و چهار سؤال ساده کافی است:

1. آیا سطح رایگان Gemini برای کار ما کافی است؟ تمرین‌های این دوره طوری طراحی شده‌اند که با سطح رایگان انجام شوند، پس برای ادامه دوره هیچ خریدی لازم نیست. فقط یادت باشد سهمیه‌ها ثابت نیستند و عوض می‌شوند؛ اگر روزی به سقف خوردی، همان قانون «مؤدب بپرس» فصل ۶ جواب می‌دهد — چند لحظه صبر و فرمان‌های کمتر و هدفمندتر.
2. اگر پروژه جدی‌تر شد، هزینه واقعی چقدر می‌شود؟ قیمت‌ها را من عمداً نمی‌گویم چون مدام عوض می‌شوند — صفحه pricing هر سرویس را با خانواده نگاه کنید.
3. پرداخت و کنترلش دست کیست؟ حساب و کارت و سقف هزینه همیشه دست والدین — و کلید، مثل همیشه، در `secrets.py` و پیش والد.
4. برای زبان و پروژه شما کدام بهتر جواب می‌دهد؟ بهترین قاضی، آزمایش خودتان است.

## چالش: برای مهاجرت چه چیزی عوض می‌شود؟

جواب بده: برای مهاجرت از Gemini به یک سرویس دیگر، کدام سه چیز در کد عوض می‌شود و کدام بخش‌ها دست‌نخورده می‌مانند؟

---

**جواب:** سه چیز عوض می‌شود: **آدرس** سرویس (`GEMINI_URL`)، **کلید** (در `secrets.py` و در هدر)، و **شکل JSON** بدنه و جواب (یعنی جای `contents`/`candidates` و مسیر پارس). دست‌نخورده می‌مانند: کل معماری — الگوی POST + JSON + کلید، نگهبان لیست سفید، جراحی رشته، `do_action`، سرور و فرم. برای همین به آن می‌گویند مهارتِ قابل‌انتقال.

## ۵. دفترچه مهندسی: صفحه پروژه دستیار

مثل هر پایان ترم، پروژه بدون مستند، نصفه است. یک صفحه دفترچه باز کن و این شش بخش را پر کن:

1. **هدف** در یک جمله — «دستیاری که فرمان متنی آزاد را با AI می‌فهمد و فقط فرمان‌های لیست سفید را اجرا می‌کند.»
2. **دیاگرام معماری** — با دست بکش: گوشی، ESP32، ابر AI، نگهبان، سخت‌افزار؛ فلش‌ها را با اسم داده‌های واقعی نامگذاری کن (فرمان، پیشنهاد JSON، action تأییدشده).
3. **جدول فرمان‌ها** — برای هر action یک ردیف: اسم، جمله‌اش در RULES، واکنش سخت‌افزار. این جدول سند رسمی لیست سفید توست؛ هر ارتقا یک ردیف اضافه می‌کند.
4. **مشکلات و راه‌حل‌ها** — حداقل دو مورد واقعی؛ امروز سه نامزد درجه‌یک دیدی (نگهبان، `NameError`، `KeyError`).
5. **جدول تست ۱۰ فرمان** از تکلیف فصل ۱۰ با نرخ موفقیت — این عدد «کارنامه فهمِ» دستیار توست و بعد از هر ارتقا دوباره پرش کن.
6. **ایده بعدی** — همین حالا که ذهنت داغ است بنویسش.

![نمای از بالای یک صفحه بازِ دفترچه مهندسی که یک نوجوان پرش کرده، با شش بخشِ دست‌نویس و برچسب‌های چسبانِ انگلیسی Goal و Diagram و Commands و Bugs و Tests و Next: بخش دیاگرام یک طرحِ دستیِ گوشی به برد به ابرِ مغز به سپر به LEDها با فلش‌ها؛ بخش فرمان‌ها یک جدولِ کوچکِ دست‌کشیده با ردیف‌های اسمِ فرمان؛ بخش تست‌ها یک جدولِ خط‌شمار با تیک و ضربدر و یک نمرهٔ موفقیتِ دورگرفته؛ یک خودکار روی صفحه و یک برد ESP32 کنار دفترچه](/lesson-assets/t4-s11-term-project-upgrade/prompt/04-image-notebook-assistant-page.png)

✅ **چک کن:** هر شش بخش پر شده و بخش «مشکلات و راه‌حل‌ها» دست‌کم دو موردِ واقعی از تجربه خودت دارد.

## ۶. ویدیوی «پروژه من»: دستیارت را به دنیا نشان بده

الگوی پنج‌قدمی آشنای ترم ۲، فصل ۱۱، این بار به سبک ترم ۴:

1. **سلام و معرفی** — به دستیارت اسم بده!
2. **معماری در سی ثانیه** — با همان دیاگرام دفترچه، مسیر یک فرمان را با انگشت دنبال کن: گوشی، برد، ابر، نگهبان، چراغ.
3. **دموی زنده در یک برداشت** — سه فرمان موفق با کلمه‌بندی‌های متفاوت، یک فرمان خارج از فهرست که مؤدبانه رد می‌شود، و ارتقای خودت — بدون قطع و چسب؛ همین یک‌برداشت‌بودن است که اعتماد می‌سازد.
4. **سخت‌ترین باگ** — داستان نگهبانی که جلوی خودت را گرفت، عالی است؛ گره و گره‌گشایی.
5. **قدم بعدی** — کدام شاخه درخت مهارت؟

> ⚠️ **مواظب باش:** قوانین ایمنی اشتراک‌گذاری، این ترم یک بند مهم‌تر هم دارد. سه قانون همیشگی: اسم کامل نه؛ آدرس و مدرسه نه؛ چیز لودهنده محل زندگی در قاب نه. قانون چهارم مخصوص ترم ۴: **کلید API هرگز در قاب نیاید** — نه روی صفحه، نه روی کاغذی روی میز؛ موقع ضبط `secrets.py` را اصلاً باز نکن. اگر شک کردی حتی یک فریم دیده شده، همان قانون فصل ۶: باطل کن و کلید نو بساز. و قانون پنجم برای همیشه: **داده شخصی در پرامپت ممنوع** — دستیار تو فرمان می‌گیرد؛ اسم و راز و عکس نمی‌گیرد. ویدیو را اول خانواده ببیند، بعد با اجازه آن‌ها با گروه کلاس به اشتراک بگذار.

✅ **چک کن:** یک ویدیوی دو تا سه دقیقه‌ای داری با هر پنج قدم و دموی یک‌برداشت — بدون هیچ ردی از کلید API و داده شخصی.

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Upgrade | آپگرِید | ارتقا؛ اضافه‌کردن قابلیت به پروژه کارکرده — یکی‌یکی و با تست |
| Provider | پرووایدِر | سرویس‌دهنده؛ شرکتی که API هوش مصنوعی می‌دهد (Google، OpenAI، Anthropic) |
| Pay-as-you-go | پِی-اَز-یو-گو | پرداخت به‌ازای مصرف؛ مثل شارژ سیم‌کارت — نه اشتراک ثابت |
| Free tier | فری تیِر | سطح رایگان یک سرویس، با سهمیه محدود |
| Documentation | داکیومنتِیشن | مستندسازی؛ ثبت طراحی و مشکلات و نتیجه‌ها در دفترچه |
| Demo | دِمو | نمایش زنده و واقعی پروژه — قلب ویدیوی «پروژه من» |

## تمرین‌ها

اول کارنامه ترم ۴ را ورق بزن — چهار نشانِ فارغ‌التحصیلی: دستیار کامل و ارتقایافته با فرمان متنی آزاد (حداقل شش action + یک فرمان ردشده مؤدبانه + یک ارتقای شخصی) و اجرای standalone؛ صفحه دفترچه مهندسی با هر شش بخش؛ ویدیوی «پروژه من» با پنج قدم؛ و جدول تصمیم خانواده. اگر همه بله است، ترم ۴ رسماً مال توست — حالا تمرین‌ها:

- **تمرین اجباری:** پایان‌نامه ترم ۴! هر چهار قلم معیار را کامل کن: (۱) دستیار ارتقایافته (حداقل `report_temp` یا یک شاخه دیگر درخت مهارت) با اجرای standalone؛ (۲) صفحه پروژه دفترچه با هر شش بخش — جدول فرمان‌ها و جدول تست ۱۰ فرمان حتماً واقعی؛ (۳) ویدیوی «پروژه من» با هر پنج قدم و قوانین ایمنی؛ (۴) جدول چهار سؤال تصمیم خانواده را با والدینت پر کن — هر جوابی درست است، مهم این است که آگاهانه باشد.
- **تمرین ستاره‌دار ⭐:** شاخه ۵ درخت مهارت را بساز: action ‏`report` که دما و رطوبت DHT11 و درصد نور LDR را در پرامپت بگذارد و از AI یک گزارش یکی-دوجمله‌ای زبان طبیعی بگیرد و روی صفحه وب نشان بدهد. راهنمایی: جواب این action دیگر JSON نیست، متن آزاد است؛ پس مسیرش را از نگهبان جدا کن و فکر کن: چرا برای «گزارش خواندنی» متن آزاد اشکال ندارد ولی برای «عمل سخت‌افزاری» ممنوع بود؟ جوابت را در دفترچه بنویس — این سؤال، کل فلسفه پروژه ترم است.

## در فصل بعد

تو الان بلدی ESP32 را به WiFi وصل کنی، با HTTP و `urequests` داده بگیری، و وب‌سرور و داشبورد و ریموت بسازی. بلدی JSON را بخوانی و بسازی، کلید را در `secrets.py` امن نگه داری، مستقیم با AI حرف بزنی، و پاسخش را جراحی و **اعتبارسنجی** کنی — و همه را در یک دستیار هوشمند با نگهبان لیست سفید جمع کنی. مهم‌تر از همه، یک طرز فکر یاد گرفتی: به هر جوابی — از اینترنت یا از AI — اول اعتبارسنجی، بعد اعتماد.

و اما ترم ۵... تا امروز همه‌چیز MicroPython بود؛ ترم بعد **زبان دوم** یاد می‌گیری: C++ — زبانی که دنیای Arduino با آن می‌چرخد و سرعتش را با آزمایش زنده با چشم خودت می‌بینی. دنبال‌کننده خطت را با **کنترل PID** واقعی نرم می‌کنیم — همان که ترم ۳، فصل ۹ فقط حرف P‌اش را زدیم. با سنسور تعادل MPU6050 آشنا می‌شوی، ربات را با Bluetooth از گوشی کنترل می‌کنی، و در پایان: **پروژه نهایی آزاد** — ایده خودت، از طراحی تا نمایش، با فرایند مهندسی کامل. فارغ‌التحصیلی نزدیک است.

![تیزرِ حماسی و دوستانه: یک پلِ درخشان از جزیره‌ای با برچسب MicroPython (با نقشِ دستیار میز و مارِ آشنا) به جزیره‌ای تازه و هیجان‌انگیز با برچسب C++ که عقربهٔ سرعت‌سنجش تا ته رفته؛ روی جزیره جدید یک ربات دوچرخ روی یک مسیرِ منحنی کاملاً نرم حرکت می‌کند با برچسب PID و یک چیپِ ژیروسکوپ و آیکونِ موجِ Bluetooth کنارش؛ در افق یک سکوی جامِ قهرمانی با برچسب Final project؛ یک نوجوان با جعبه‌ابزار روی پل قدم می‌گذارد](/lesson-assets/t4-s11-term-project-upgrade/prompt/05-image-term5-teaser.png)

دستیارت را روشن نگه دار، دفترچه‌ات را ببند بهش، و به خودت افتخار کن — ترم ۴ تمام شد. خداحافظ تا ترم ۵!

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t4/s11-term-project-upgrade (یادستان, Yaadestan)
