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

<div dir="rtl">

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

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

به پروژه پایانی ترم ۴ خوش آمدی! چیزی که می‌سازی «دستیار هوشمند» است: تو **هر جمله‌ای** که دلت خواست تایپ می‌کنی — «چراغ سبز را روشن کن»، «یه بوق بزن»، به زبان خودت — و دستگاه منظورت را می‌فهمد و انجامش می‌دهد. نه دکمه از پیش تعریف‌شده‌ای در کار است، نه جمله حفظ‌شده‌ای. و وقتی چیزی خارج از توانش بخواهی، مؤدبانه می‌گوید «بلد نیستم» — نه خراب می‌شود، نه کار عجیبی می‌کند.

هوشِ پشت صحنه همان Gemini فصل‌های قبل است؛ ولی امروز یک تفاوت بزرگ دارد: جوابش دیگر یک متن آزاد نیست که فقط بخوانیم — جوابش **اجرا می‌شود**. و همین‌جا مهم‌ترین درس امروز شروع می‌شود: به کدی که از بیرون می‌آید، چقدر باید اعتماد کرد؟ خبر خوب: تقریباً همه قطعه‌های این پروژه را بلدی. وب‌سرور؟ فصل ۳ و ۴. تماس با Gemini؟ فصل ۹. json و secrets؟ فصل ۶. فقط دو ابزار کوچک رشته امروز اضافه می‌شود — همین. پروژه را در سه مرحله می‌سازیم: Stage A صفحه فرمان، Stage B مغز AI، و Stage C اتصال به دست و پا.

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

- معماری «مغز دوطبقه» را توضیح بدهی: AI فرمانِ آزاد را فقط به یک **پیشنهاد** تبدیل می‌کند و ESP32 با **لیست سفید** تصمیم نهایی را می‌گیرد.
- یک صفحه وب با فرم ورودی متن بسازی و فرمان را با دو متد جدید رشته — `find` و `replace` — به‌علاوه برش فصل ۹ از URL بیرون بکشی.
- یک پرامپت مهندسی‌شده بنویسی که جواب Gemini را در قالب ثابت `{"action": "..."}` قفس کند و **قبل از اجرا** اعتبارسنجی‌اش کنی.
- دستیار کامل را مرحله‌به‌مرحله (Stage A/B/C) روی سخت‌افزار میز اجرا کنی — و اگر ربات ترم ۳ را داری، نسخه رباتی را هم.

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

روز جایزه ترم ۴ است — تقریباً همه‌چیز ترکیب ساخته‌های خودت است، به‌علاوه فقط دو ابزار کوچک رشته:

- **از فصل ۹:** تماس مستقیم ESP32 با Gemini — `urequests.post`، هدرها (کلید در `x-goog-api-key`)، پارس جواب تودرتو، `gc.collect`. قلب Stage B.
- **از فصل ۸:** محدودیت‌های AI و hallucination — دلیل وجودی لیست سفید امروز.
- **از فصل ۶:** ماژول `json` (loads/dumps)، دیکشنری تودرتو، و `secrets.py`.
- **از فصل ۳ و ۴:** وب‌سرور socket، مسیر URL، رشته سه‌نقل‌قولی و f-string برای HTML.
- **از فصل ۵:** ریموت وب امن ربات — الگوی «پالس کوتاه = توقف پیش‌فرض» برای نسخه رباتی.
- **از فصل ۳:** عملگر `in` روی رشته. امروز همان `in` را روی لیست هم به‌کار می‌بریم؛ ستون فقرات لیست سفید.
- **از ترم ۳، فصل ۳ و ۴:** ماژول `robot.py` و حرکت‌های زمان‌بندی‌شده (فقط نسخه رباتی).
- **جدید امروز:** متدهای `find` و `replace` رشته — همین دو تا، قول می‌دهم!

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

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ESP32 + Breadboard + کابل USB | ۱ | — |
| LED قرمز/زرد/سبز + مقاومت 220Ω (کیت ترم ۱) | ۳+۳ | حتی با یک LED هم پروژه کامل است |
| Buzzer پسیو (کیت ترم ۱) | ۱ | بدون آن هم می‌شود — action مربوطه را حذف کن |
| OLED 0.96 اینچ I2C (کیت ترم ۲) | ۱ | بدون آن هم می‌شود — خروجی در Shell |
| ربات کامل ترم ۳ | ۱ | فقط برای مسیر دوم؛ بدون آن، نسخه میز پروژه کامل است |
| WiFi 2.4GHz + کلید Gemini در `secrets.py` | — | هات‌اسپات گوشی |
| گوشی با مرورگر | ۱ | مرورگر خود کامپیوتر |

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

## ۱. مغز دوطبقه: چرا به AI فرمان محدود می‌دهیم؟

قبل از کد، یک تصمیم معماری — مهم‌ترین تصمیم پروژه. رستوران فصل ۲ و ۳ یادت هست؟ امروز برمی‌گردد: تو به گارسون **هر جوری** می‌توانی سفارش بدهی — «یه چیز داغ بیار»، «همون همیشگی!» — ولی گارسون به آشپزخانه چه می‌برد؟ فقط یکی از آیتم‌های **منو** را. آشپزخانه هرگز با جمله آزاد مشتری کار نمی‌کند؛ اگر سفارشت توی منو نباشد، گارسون می‌گوید «نداریم» و هیچ‌وقت آشپزخانه از خودش غذای عجیبی اختراع نمی‌کند.

![دیاگرام معماری دستیار: سمت چپ یک گوشی با جعبه متن که یک حباب گفتار free text می‌فرستد؛ فلش به برد ESP32 وسط؛ از برد فلشی بالا به یک ابرِ مغز با برچسب AI که یک کارت JSON کوچک {"action": "..."} با برچسب AI suggests برمی‌گرداند؛ زیر برد یک دروازه سپری‌شکل با برچسب Whitelist و فهرست هشت فرمان روی تخته؛ فقط بعد از سپر فلشی به سه LED و یک بازر و یک OLED با برچسب Action؛ مسیرِ ردشده سبز می‌درخشد و یک کارت قرمزِ ردشده از سپر به عقب می‌پرد](/lesson-assets/t4-s10-term-project-build/prompt/01-image-assistant-architecture.png)

دستیار ما دقیقاً همین است. **AI گارسون است، نه آشپز.** فرمان آزاد تو می‌رود پیش Gemini، ولی Gemini اجازه ندارد هر جوابی بدهد: با یک پرامپت مهندسی‌شده مجبورش می‌کنیم فقط یک JSON یک‌خطی برگرداند — `{"action": "..."}` — و آن action هم فقط از یک فهرست ثابت هشت‌تایی. بعد، طبقه پایین: ESP32 قبل از اجرا، جواب را با **لیست سفید** خودش چک می‌کند؛ هر چیزی خارج از لیست — هر چیزی — می‌شود «بلد نیستم».

چرا این‌قدر سخت‌گیری؟ دو کلمه: **ایمنی** و **پیش‌بینی‌پذیری**. فصل ۸ دیدی که AI گاهی با اعتمادبه‌نفس کامل چیز غلط می‌گوید — hallucination. وقتی جواب AI فقط خوانده می‌شد، اشتباهش بی‌خطر بود؛ اما حالا جوابش به موتور و بلندگو وصل است! قانون طلایی امروز را بنویس: **AI پیشنهاد می‌دهد؛ لیست سفید تصمیم می‌گیرد.**

## چالش: اگر لیست سفید نداشتیم چه می‌شد؟

جواب بده: اگر لیست سفید نبود و AI یک روز به‌جای یک فرمان درست، یک action من‌درآوردی مثل `format_disk` برمی‌گرداند، چه اتفاقی می‌افتاد؟ کدام طبقهٔ دستیار جلوی آن می‌ایستد؟

---

**جواب:** بدون لیست سفید، هر اسمی که AI بفرستد «فرمان» حساب می‌شد. برنامهٔ ما با اسمی که نمی‌شناسد کاری نمی‌کند، پس `format_disk` دیسکی را پاک نمی‌کرد؛ ولی صفحه می‌نوشت «انجام شد» و تو خیال می‌کردی کاری شده. مهم‌تر اینکه هر بار که برنامه بزرگ‌تر شود، حدسِ AI یک قدم به سخت‌افزار نزدیک‌تر است. طبقهٔ پایین، یعنی ESP32 با لیست سفیدش، همان نگهبان است: اگر اسم در فهرست ثابت ما نباشد، بی‌بحث `unknown` می‌شود و هیچ کاری اجرا نمی‌شود. خطش را در Stage B می‌نویسیم.

## ۲. Stage A: صفحه فرمان و جراحی رشته

بزن بریم سراغ ساخت! Stage A هنوز هیچ AI ندارد: فقط یک صفحه وب با یک جعبه متن که هر چه تایپ کنی، همان را پس می‌دهد — مثل طوطی. چرا؟ همان عادت همیشگی: هر قطعه جدا تست می‌شود.

اسکلت سرور را از فصل ۴ می‌آوریم؛ تنها چیز تازه در HTML، برچسب `<form>` است: یک `<input>` با اسم `cmd` و یک دکمه ارسال. وقتی دکمه را بزنی، مرورگر خودش آدرس را این‌شکلی می‌سازد و می‌فرستد: `/ask?cmd=salam` — یعنی متن تو سوار همان مسیر URL فصل ۳ می‌شود!

حالا باید متن را از دل request بیرون بکشیم. request یک رشته بلند است و فرمان ما وسطش گم است. اینجا دو ابزار جدید امروز معرفی می‌شوند. اولی `find`: به رشته می‌گویی «این تکه را کجا دیدی؟» و جواب یک عدد است — جای اولین پیدا شدن، و اگر اصلاً نبود، `-1`. تابع `get_command` را ببین:

</div>

```python
def get_command(request):
    # matn-e farman ra az URL biroon mikeshad: GET /ask?cmd=matn HTTP/1.1
    start = request.find("cmd=")     # find: jaygah-e avalin "cmd=" (-1 = nist)
    if start == -1:
        return ""                    # form hanooz ferestade nashode
    start = start + 4                # 4 harf-e "cmd=" ra rad kon
    end = request.find(" ", start)   # avalin fasele-ye bad az matn
    cmd = request[start:end]         # boresh-e reshte (jalase 9)
    cmd = cmd.replace("+", " ")      # browser fasele-ha ra + mikonad!
    return cmd
```

<div dir="rtl">

با `request.find("cmd=")` جای شروع فرمان را پیدا می‌کنیم، چهار حرف جلو می‌رویم، و پایانش هم اولین فاصله بعد از متن است: `request.find(" ", start)` — همان find، فقط گفته‌ایم «از اینجا به بعد بگرد». وسطِ این دو عدد را با برش فصل ۹ برمی‌داریم.

بیا اول این تابع را ساده تست کنیم (بدون خط `replace`). در گوشی تایپ می‌کنم «salam chetori» و جواب روی صفحه:

</div>

```text
Javab: salam+chetori
```

<div dir="rtl">

این «+»ها دیگر چیست؟! خطای قرمزی در کار نیست ولی خروجی درست هم نیست. حقیقت بامزه: مرورگر در URL اجازه فاصله ندارد؛ موقع ارسال فرم، هر فاصله را با علامت + جایگزین می‌کند. اینجا ابزار دوم امروز به میدان می‌آید: `replace`. دستور `cmd.replace("+", " ")` یعنی «هر + را با فاصله عوض کن» — همان خط آخر تابع بالا. حالا «salam chetori» تمیز برمی‌گردد. طوطی ما کار می‌کند!

> 💡 **نکته:** اگر فرمان را **فارسی** تایپ کنی، مرورگر حروف فارسی را به کدهای ٪دار عجیبی تبدیل می‌کند و متن به‌هم می‌ریزد. رمزگشایی‌شان از حوصله این پروژه بیرون است؛ راه‌حل ما: فرمان‌ها را فینگلیش یا انگلیسی بنویس — و خبر خوب اینکه Gemini فینگلیش را عالی می‌فهمد!

برنامه کامل Stage A — فایل `01_command_page.py`:

</div>

```python
# Term 4 - Session 10 - Stage A: safhe-ye farman - form-e matni rooye web
# hanooz AI dar kar nist: har chi type koni, hamoon ra pas midahad (echo)
# do abzar-e jadid-e reshte: find() va replace()
import network
import socket
import secrets
import time

def get_command(request):
    # matn-e farman ra az URL biroon mikeshad: GET /ask?cmd=matn HTTP/1.1
    start = request.find("cmd=")     # find: jaygah-e avalin "cmd=" (-1 = nist)
    if start == -1:
        return ""                    # form hanooz ferestade nashode
    start = start + 4                # 4 harf-e "cmd=" ra rad kon
    end = request.find(" ", start)   # avalin fasele-ye bad az matn
    cmd = request[start:end]         # boresh-e reshte (jalase 9)
    cmd = cmd.replace("+", " ")      # browser fasele-ha ra + mikonad!
    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")

s = socket.socket()
s.bind(("0.0.0.0", 80))
s.listen(1)
print("safhe-ye farman 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:
        answer = command   # Stage A: faghat echo - maghz-e AI dar Stage B!
        print("farman-e daryafti:", command)

    html = f"""<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width">
  <title>AIRO Assistant</title>
</head>
<body>
  <h1>AIRO Smart Assistant</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">

✅ **چک کن:** آدرس IP را از Shell بردار، در مرورگر گوشی باز کن، در جعبه یک جمله تایپ کن و BEFEREST را بزن — باید همان جمله تمیز، بدون +، جلوی «Javab» بیاید. Stage A پاس شد! 🎉

> 🔧 **اگر کار نکرد:** جواب پر از + است؟ خط `replace("+", " ")` جا افتاده. صفحه اصلاً باز نمی‌شود یا روی «dar hal-e ettesal» گیر کرده؟ WiFi وصل نیست — چک‌لیست فصل ۱: نام و پسورد در `secrets.py`، شبکه ۲.۴ گیگاهرتز.

> 🔧 **اگر بعد از یک فرمان، در Shell یک `farman-e daryafti:` دوم با متن عجیب دیدی:** مرورگر گاهی درخواست دومی هم می‌فرستد، مثلاً برای `/favicon.ico`، و سربرگ `Referer` آن آدرس قبلی را با `cmd=` همراه دارد. این همان باگ فصل ۵ است: `get_command` کل request را می‌گردد و آن را هم فرمان حساب می‌کند. در Stage C این یعنی یک تماس بیهوده با AI. درمانش دو خط در اول تابع است: `if "GET /ask" not in request:` و زیرش `return ""`.

## چالش: چرا اول start == -1 را چک می‌کنیم؟

جواب بده: در `get_command` چرا اول چک می‌کنیم `start == -1`؟ چه کسی ممکن است صفحه را بدون فرمان باز کند؟ (راهنمایی: اولین باری که آدرس IP را در مرورگر می‌زنی، URL چیست؟)

---

**جواب:** اولین باری که آدرس را باز می‌کنی، هنوز هیچ فرمی نفرستاده‌ای؛ پس در request اصلاً `cmd=` نیست و `find` عدد `-1` می‌دهد. اگر این را چک نکنیم، برش با عددِ `-1` نتیجه غلط می‌دهد. با `if start == -1: return ""` می‌گوییم «فرمانی نیامده» و صفحه پیام «منتظر فرمان تو...» را نشان می‌دهد.

## ۳. Stage B: مغز AI و قفس JSON

حالا قلب پروژه: تابعی به اسم `ask_ai` که فرمان آزاد را می‌گیرد و فقط اسم یک action برمی‌گرداند. تماس با Gemini را از فصل ۹ کلمه‌به‌کلمه بلدی — کلید در هدر `x-goog-api-key`، بدنه با `json.dumps`، پارس تودرتو. چیز تازه، **متن پرامپت** است. یک رشته سه‌نقل‌قولی به اسم `RULES` می‌نویسیم که مثل قرارداد کاری 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
If the command matches none of them, reply: {"action": "unknown"}
User command: """
```

<div dir="rtl">

به این کار می‌گویند **prompt engineering**: به‌جای امید بستن به حال خوب AI، با دقتِ یک بندِ قرارداد، خروجی را قفس می‌کنیم. فهرست هشت action مجاز را هم در یک لیست به اسم `ALLOWED` می‌گذاریم — همان لیست سفید:

</div>

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

<div dir="rtl">

اولین نسخه `ask_ai` را ساده می‌نویسم: تماس، پارس، `json.loads` مستقیم روی متن، برگرداندن action. اولین فرمان و بوم:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 75, in <module>
  File "<stdin>", line 44, in ask_ai
ValueError: syntax error in JSON
```

<div dir="rtl">

`ValueError` — همان خطای آشنای فصل ۶: «این متن، JSON سالم نیست». ولی ما که به AI گفتیم JSON بده! یک `print(text)` موقت می‌گذارم ببینم Gemini واقعاً چه فرستاده:

</div>

````text
```json
{"action": "red_on"}
```
````

<div dir="rtl">

آهان! JSON داده، ولی مثل یک هدیه، **کادوپیچ**: دور جواب سه بک‌تیک و کلمه json گذاشته — همان code fence که AIها عاشقش هستند. `json.loads` هم راست می‌گوید: بک‌تیک جزو JSON نیست. دو لایه دفاع می‌چینیم:

- **لایه اول، مؤدبانه:** در RULES صریح نوشته‌ایم «no code fences» — ولی فصل ۸ یادمان داد به قول AI صددرصد تکیه نکنیم!
- **لایه دوم، جراحی رشته:** جواب واقعی ما همیشه بین اولین `{` و اولین `}` است. با همان find امروز جای `{` و `}` را پیدا کن، بینشان را برش بزن، و `loads` را در یک `try/except ValueError` بپیچ که اگر باز هم متن خراب بود، به‌جای مرگ، `unknown` برگردد. اگر هم JSON سالم بود ولی کلید `action` نداشت، `answer["action"]` خطای `KeyError` می‌دهد و `except KeyError` همان `unknown` را برمی‌گرداند.

اجرای دوباره — فرمان اول: `red_on`؛ دوم: `green_off`؛ سوم...

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 80, in <module>
  File "<stdin>", line 39, in ask_ai
MemoryError: memory allocation failed, allocating 4608 bytes
```

<div dir="rtl">

`MemoryError` — و تو این را از فصل ۹ می‌شناسی! هر تماس امن اینترنتی حافظه زیادی از ESP32 کوچک ما می‌خواهد. راه‌حلش هم مال خودت است: `gc.collect()` — رفتگر حافظه — این بار **اول هر تماس**، همان خط اول `ask_ai`. اضافه می‌کنم؛ `r.close()` هم که سر جایش است.

اجرای سوم: هر پنج فرمان جواب درست — و به آخری دقت کن: «cheragh-e sabz ro cheshmak bezan» — چشمک‌زدن که در فهرست ما نیست! `print(text)` موقت را نگاه می‌کنم: Gemini با خوش‌خدمتی نوشته `{"action": "green_blink"}` — یک action **اختراعی**! در فهرست هشت‌تایی ما `green_blink` وجود ندارد؛ AI برای راضی‌کردن ما از خودش ساخته. و حالا لحظه‌ای که برایش صبر کرده بودیم — خط جراحی و نگهبان را ببین:

</div>

```python
    text = data["candidates"][0]["content"]["parts"][0]["text"]
    # 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)
```

<div dir="rtl">

خطِ `if action in ALLOWED` مثل نگهبان در ورودی، اسمِ `green_blink` را در لیست سفید نگاه می‌کند — نیست — و بدون بحث: `unknown`. دستگاه ما دست از پا خطا نکرد. این همان سطری است که پروژه تو را از یک اسباب‌بازی به یک محصول قابل‌اعتماد تبدیل می‌کند.

![صحنه کارتونی: یک رباتِ نگهبان جلوی یک طناب مخملی و دری با آیکون چرخ‌دنده (اتاق اجرا) ایستاده، دستش یک تخته با فهرست فرمان‌های مجاز (green_on، red_off، beep، all_off)؛ یک کارت بلیت JSON شاد با برچسب green_on با تیک سبز رد می‌شود، ولی یک بلیت گنده و مشکوک با برچسب green_blink را دستِ بالاگرفته نگهبان مؤدبانه متوقف و به نیمکتِ unknown هدایت می‌کند؛ در پس‌زمینه یک شخصیت ابرِ مغز شانه بالا می‌اندازد](/lesson-assets/t4-s10-term-project-build/prompt/03-image-whitelist-bouncer.png)

برنامه کامل Stage B — فایل `02_ai_brain.py` (این نسخه هنوز نه سرور دارد، نه سیم‌کشی؛ فقط مغز را با پنج فرمان آماده تست می‌کند):

</div>

```python
# Term 4 - Session 10 - Stage B: maghz-e AI - farman-e azad -> action-e sabet
# ghanun-e talayi-ye emrooz: AI faghat PISHNAHAD midahad; list-e sefid TASMIM migirad!
import network
import urequests
import json
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,
}

# list-e sefid: TANHA farman-hayi ke ejaze-ye ejra darand
ALLOWED = ["red_on", "red_off", "yellow_on", "yellow_off",
           "green_on", "green_off", "beep", "all_off"]

# prompt-e mohandesi-shode: ghafas-e JSON baraye javab-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
If the command matches none of them, reply: {"action": "unknown"}
User command: """

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()
    text = data["candidates"][0]["content"]["parts"][0]["text"]
    # 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)

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")

# --- test-e maghz: hanooz na server darim, na sim-keshi ---
TESTS = ["cheragh-e ghermez ro roshan kon",
         "green light off please",
         "ye boogh bezan",
         "hame chiz khamush",
         "cheragh-e sabz ro cheshmak bezan"]

for t in TESTS:
    action = ask_ai(t)
    print(t, "->", action)
    time.sleep(2)   # ehteram be rate limit (jalase 6)
```

<div dir="rtl">

✅ **چک کن:** باید هر پنج فرمان درست ترجمه شوند و فرمانِ «چشمک» به `unknown` برسد — نه به یک action اختراعی. Stage B پاس شد! 🎉

> 🔧 **اگر کار نکرد:** `ValueError` می‌گیری؟ AI جواب را کادوپیچ کرده — مطمئن شو جراحی از `{` تا `}` سر جایش است. `MemoryError` وسط تماس‌ها؟ `gc.collect()` خط اول `ask_ai` و `r.close()` بعد از هر تماس. `KeyError: candidates`؟ سرویس به‌جای جواب، error فرستاده — کلید را در `secrets.py` چک کن؛ فصل ۱۱ برایش گارد کامل می‌سازیم.

## چالش: چرا باز هم if action in ALLOWED؟

جواب بده: ما که در RULES به AI گفته‌ایم فقط از فهرست انتخاب کند؛ چرا باز هم در کد `if action in ALLOWED` را چک می‌کنیم؟ کدام درسِ فصل ۸ جوابت را می‌دهد؟

---

**جواب:** چون فصل ۸ یادمان داد AI قابل‌اعتماد صددرصد نیست؛ گاهی همان قراردادی را که به او دادیم زیر پا می‌گذارد و یک action اختراعی مثل `green_blink` می‌سازد. RULES فقط یک **درخواست** است، نه یک ضمانت. `if action in ALLOWED` تنها جایی است که واقعاً **تصمیم** گرفته می‌شود — و چون کد خودمان است، همیشه قابل‌اعتماد است.

## ۴. Stage C: دست و پا — دستیار کامل روی میز

مغز داریم، صفحه فرمان داریم؛ وقت دست و پاست. اول برق برد را قطع کن و مدار میز را طبق پین‌مپ همیشگی ببند:

</div>

| Part | Part pin | ESP32 pin | Note |
|---|---|---|---|
| LED red | anode | GPIO 25 | via 220 ohm; red_on / red_off |
| LED yellow | anode | GPIO 26 | via 220 ohm; yellow_on / yellow_off |
| LED green | anode | GPIO 27 | via 220 ohm; green_on / green_off |
| Buzzer | + | GPIO 4 | beep (PWM) |
| OLED | SDA | GPIO 21 | I2C data |
| OLED | SCL | GPIO 22 | I2C clock |
| OLED | VCC | 3V3 | display power |
| all LEDs / buzzer / OLED | cathode / - / GND | GND | shared ground |

<div dir="rtl">

![دیاگرام سیم‌کشی برد ESP32 روی Breadboard برای دستیار میز: LED قرمز از مقاومت 220 به GPIO 25، LED زرد از 220 به GPIO 26، LED سبز از 220 به GPIO 27، یک بازر پسیو به GPIO 4، و یک OLED کوچک ۰.۹۶ اینچ با سیم‌های SDA 21 و SCL 22 و 3V3 و GND؛ همه GNDها به ریل آبیِ مشترک برمی‌گردند؛ گوشه تصویر یک گوشی که یک صفحه وبِ ساده با جعبه متن نشان می‌دهد و با موجِ نقطه‌چینِ WiFi به برد وصل است](/lesson-assets/t4-s10-term-project-build/prompt/04-image-desk-assistant-wiring.png)

حالا تابع `do_action`: یک زنجیره if/elif ساده که برای هر action یک کار کوچک می‌کند. به این تابع دقت کن: نه تماس اینترنتی دارد، نه چیز عجیبی — چون هر ورودی‌اش **قبلاً از نگهبان رد شده**. بعد سه قطعه را در یک فایل سوار هم می‌کنیم: حلقه سرور از Stage A فرمان را می‌گیرد، `ask_ai` از Stage B تصمیم AI را می‌آورد، نگهبان چک می‌کند، `do_action` اجرا می‌کند و جواب روی صفحه وب و OLED می‌نشیند. دور تماس AI هم یک `try/except OSError` می‌گذاریم — درس فصل ۴: سرور هیچ‌وقت نباید بمیرد، حتی وقتی اینترنت می‌میرد.

برنامه کامل Stage C (نسخه میز) — فایل `03_assistant_desk.py`:

</div>

```python
# Term 4 - Session 10 - Stage C: dastyar-e hooshmand-e miz (noskheye bedoon-e robot)
# safhe-ye farman (Stage A) + maghz-e AI (Stage B) + dast-o-pa: LED, buzzer, OLED
# 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 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,
}

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

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
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)

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()
    text = data["candidates"][0]["content"]["parts"][0]["text"]
    # 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)

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("READY!", 0, 20)
oled.show()

s = socket.socket()
s.bind(("0.0.0.0", 80))
s.listen(1)
print("dastyar-e hooshmand 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)
        if action == "unknown":
            answer = "in farman ra balad nistam!"
        else:
            do_action(action)
            answer = "anjam shod: " + action
        oled.fill(0)
        oled.text("AIRO ASSISTANT", 0, 0)
        oled.text(action, 0, 20)
        oled.show()

    html = f"""<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width">
  <title>AIRO Assistant</title>
</head>
<body>
  <h1>AIRO Smart Assistant</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">

اجرا کن، گوشی دستت است. تایپ کن «har se cheragh ro roshan kon» و ببین چه می‌شود. جواب AI هر بار یکسان نیست. چون فقط یک action می‌تواند بدهد، معمولاً `unknown` می‌دهد یا فقط یکی از چراغ‌ها را انتخاب می‌کند. این محدودیت طراحی ماست: یک فرمان، یک action. «hame chiz khamush» را امتحان کن: `all_off` — همه خاموش. «ye boogh bezan» — بوق! و روی OLED هر بار اسم action می‌نشیند.

یک نکته را حس کردی؟ بین تایپ و اجرا دو سه ثانیه طول می‌کشد — فرمان تو دارد تا سرور Gemini آن‌سر دنیا می‌رود و برمی‌گردد؛ این تأخیر طبیعیِ هر دستگاه ابری است، از بلندگوهای هوشمند خانه تا دستیار ما.

آخر هم مثل همیشه: با اسم `main.py` روی برد ذخیره کن، کابل را بکش، آداپتور بزن — دستیار مستقل شد!

✅ **چک کن:** با گوشی حداقل شش فرمان مختلف را درست اجرا کن، و یک فرمان خارج از فهرست (مثل «pizza sefaresh bede») پیام «in farman ra balad nistam!» بگیرد — نه خطا، نه کار عجیب. Stage C پاس! پروژه ترم ۴ روی میز توست. 🎉

## ۵. مسیر دوم: همان مغز، روی چرخ‌ها

اگر ربات ترم ۳ را ساخته‌ای، جایزه ویژه: کل این پروژه با عوض‌کردن فقط **سه قطعه** روی ربات می‌نشیند — و این زیبایی معماری تمیز است:

1. فهرست `ALLOWED` می‌شود شش حرکت: `forward`، `backward`، `left`، `right`، `stop`، `dance`.
2. در `RULES` به AI می‌گوییم مغز یک ربات دوچرخ است و فهرست جدید را می‌دهیم.
3. `do_action` به‌جای LED، توابع `robot.py` را صدا می‌زند.

و اینجا قانون ایمنی فصل ۵ برمی‌گردد: هر حرکت فقط یک **پالس کوتاه** است (`forward_time` با نیم ثانیه)، چون رباتی که فرمانش از اینترنت می‌آید باید پیش‌فرضش ایستادن باشد، نه رفتن. مغز `ask_ai` و نگهبان و سرور؟ دست نمی‌خورند — حتی یک حرف.

![اسلاید مقایسه‌ای: وسط تصویر یک ماژول مغزِ درخشانِ مشترک با برچسب Same brain و آیکون سپر؛ سمت چپ یک دستیار میز — ESP32 روی Breadboard با سه LED و بازر و OLED — با برچسب Desk assistant؛ سمت راست یک ربات دوچرخ با برد درایور موتور و برچسب Robot؛ سه کارتریج قابل‌تعویض بین دو پنل شناورند با برچسب‌های ALLOWED و RULES و do_action و فلش‌هایی که نشان می‌دهد در هر دو ساخت جا می‌افتند؛ هر دو پنل به یک گوشیِ واحد با جعبه فرمان متنی وصل‌اند](/lesson-assets/t4-s10-term-project-build/prompt/05-image-two-paths.png)

> ⚠️ **مواظب باش:** `robot.py` هم باید روی برد باشد — درس ImportError ترم ۳ یادت نرود! اگر فقط روی کامپیوتر ذخیره‌اش کنی، ربات موقع اجرا با `ImportError: no module named 'robot'` می‌ایستد.

برنامه کامل نسخه رباتی — فایل `04_assistant_robot.py`:

</div>

```python
# Term 4 - Session 10 - Stage C: robot-e farman-pazir (noskheye ba robot-e term 3)
# hamun maghz + hamun list-e sefid; faghat dast-o-pa avaz shode: robot.py!
# imeni-ye jalase 5: har harekat yek pulse-e kutah - tavaghof-e pishfarz
# robot.py bayad rooye bord bashad; ejraye standalone: in file -> main.py
import network
import socket
import urequests
import json
import robot
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,
}

ALLOWED = ["forward", "backward", "left", "right", "stop", "dance"]

RULES = """You are the brain of a small two-wheel robot 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:
forward, backward, left, right, stop, dance
If the command matches none of them, reply: {"action": "unknown"}
User command: """

SPEED = 600
BURST = 0.5        # jalase 5: har farman yek pulse-e kutah = tavaghof-e pishfarz
TURN_BURST = 0.25  # baraye pichidan: pulse-e kutahtar = kontrol-e daghightar

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()
    text = data["candidates"][0]["content"]["parts"][0]["text"]
    # 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):
    # faghat action-haye list-e sefid: harekat-haye pulse-i (imeni-ye jalase 5)
    if action == "forward":
        robot.forward_time(SPEED, BURST)
    elif action == "backward":
        robot.backward_time(SPEED, BURST)
    elif action == "left":
        robot.turn_left_time(SPEED, TURN_BURST)
    elif action == "right":
        robot.turn_right_time(SPEED, TURN_BURST)
    elif action == "stop":
        robot.stop()   # tavaghof-e ezterari - adat-e khub (jalase 5)
    elif action == "dance":
        robot.turn_left_time(600, 0.15)
        robot.turn_right_time(600, 0.3)
        robot.turn_left_time(600, 0.15)

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")

s = socket.socket()
s.bind(("0.0.0.0", 80))
s.listen(1)
print("robot-e farman-pazir 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)
        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 Robot</title>
</head>
<body>
  <h1>AIRO Smart Robot</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">

ربات روی زمین، گوشی در دست: «boro jelo» — نیم قدم جلو. «beraghs!» — و رقص پیروزی ترم ۳، این بار به فرمان زبان آدمیزاد. تست که تمام شد، `main.py` و باتری — ربات فرمان‌پذیر مستقل.

✅ **چک کن:** ربات با چند فرمان متنی مختلف درست حرکت کند و بعد از هر پالس کوتاه، خودش بایستد. 🎉

## چالش: چرا پالس کوتاه و نه forward ساده؟

جواب بده: چرا در نسخه رباتی از `forward_time` (پالس کوتاه) استفاده کردیم و نه `forward` ساده؟ اگر بعد از یک فرمانِ «برو جلو» WiFi قطع شود، ربات با هر کدام چه می‌کند؟

---

**جواب:** `forward` ساده موتور را روشن می‌کند و روشن **می‌ماند** تا فرمان بعدی برسد؛ اگر بعدش WiFi قطع شود، ربات برای همیشه جلو می‌رود و از میز می‌افتد. `forward_time` فقط یک پالس نیم‌ثانیه‌ای می‌رود و خودش `stop` می‌کند؛ پس پیش‌فرضِ ربات همیشه ایستادن است — درست همان قانون ایمنی فصل ۵ برای دستگاهی که فرمانش از اینترنت می‌آید.

## قطعه یا گوشی نداری؟ نسخه کنسولی

اگر گوشی به دستت نرسیده — یا فقط می‌خواهی مغز پروژه را بدون صفحه وب امتحان کنی — نسخه کنسولی برای توست: به‌جای صفحه وب، فرمان را در Shell تایپ می‌کنی و بقیه ماجرا (تماس AI، جراحی رشته، نگهبان، اجرا) عیناً همان است. یک صداقت مهم: این نسخه هم برای کار کردن به WiFi و کلید واقعی احتیاج دارد، پس جای اجرایش برد واقعی است؛ شبیه‌ساز آزمایشگاه به اینترنت وصل نمی‌شود و تماس AI را انجام نمی‌دهد. کدش پنجمین و آخرین فایلِ پوشهٔ `src` این جلسه است:

</div>

```python
# Term 4 - Session 10 - noskheye console-i: baraye Wokwi ya test-e bedoon-e gooshi
# farman ra dar Shell (ya Serial-e Wokwi) type kon -> AI -> list-e sefid -> ejra
# dar Wokwi: dar tab-e secrets.py benevis WIFI_SSID = "Wokwi-GUEST" va WIFI_PASS = ""
# HOSHDAR: kelid-e vaghei ra faghat dar project-e KHOSUSI bogzar; link ra share nakon!
from machine import Pin, PWM, I2C
import network
import urequests
import json
import ssd1306
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,
}

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

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
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)

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()
    text = data["candidates"][0]["content"]["parts"][0]["text"]
    # 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)

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("READY!", 0, 20)
oled.show()
print("dastyar-e console-i amade ast! farman bede:")

while True:
    command = input("farman-e to: ")
    if 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)
        if action == "unknown":
            print("in farman ra balad nistam!")
        else:
            do_action(action)
        oled.fill(0)
        oled.text("AIRO ASSISTANT", 0, 0)
        oled.text(action, 0, 20)
        oled.show()
```

<div dir="rtl">

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

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Assistant | اَسیستنت | دستیار؛ دستگاهی که فرمان آزاد تو را می‌فهمد و عمل می‌کند |
| Form | فورم | جعبه ورودی صفحه وب که متن تو را داخل URL می‌فرستد |
| Whitelist | وایت‌لیست | لیست سفید؛ فهرست بسته کارهای مجاز — هر چیز بیرونش رد می‌شود |
| Validation | وَلیدِیشن | اعتبارسنجی؛ چک‌کردن جواب قبل از اعتماد و اجرا |
| Action | اَکشن | عمل؛ یکی از فرمان‌های ثابت فهرست ما |
| Prompt engineering | پرامپت انجینیرینگ | مهندسی پرامپت؛ نوشتن دستور دقیق برای قفس‌کردن خروجی AI |

## تمرین‌ها

اول چک‌لیست پروژه: دستیار (میز یا ربات) با فرمان متنی آزادِ تایپ‌شده، حداقل شش action مختلف را درست اجرا می‌کند؛ به فرمان خارج از فهرست پیام «بلد نیستم» می‌دهد، نه خطا؛ می‌توانی قانون «AI پیشنهاد می‌دهد؛ لیست سفید تصمیم می‌گیرد» را توضیح بدهی؛ و پروژه standalone با `main.py` کار می‌کند و `secrets.py` روی برد است. اگر همه بله است:

- **تمرین اجباری:** دستیارت را کامل راه بینداز و در دفترچه مهندسی «جدول تست ۱۰ فرمان» بساز: ستون‌ها = فرمان آزادی که تایپ کردی، action مورد انتظار، action واقعی، درست/غلط. حداقل دو فرمان عمداً خارج از فهرست باشد (مثل «pizza sefaresh bede») — انتظار: `unknown` و پیام «بلد نیستم». نتیجه: چند از ده؟ اگر فرمانی همیشه اشتباه فهمیده می‌شود، بنویس چرا به نظرت AI گیج شد.
- **تمرین ستاره‌دار ⭐:** یک action نهم اضافه کن: `blink` — سه بار چشمک همه LEDها. دقیقاً سه جا باید تغییر کند: فهرست داخل RULES، لیست `ALLOWED` و یک شاخه جدید در `do_action`. قبل از تست پیش‌بینی‌ات را بنویس: اگر فقط `do_action` را اضافه می‌کردی و `ALLOWED` یادت می‌رفت، چه می‌شد؟ بعد امتحانش کن — فصل بعد همین الگو را رسمی یاد می‌گیریم!

## در فصل بعد

پروژه‌ات کار می‌کند — ولی هنوز تمام نشده. فصل بعد، آخرین فصل ترم، دستیار را **ارتقا** می‌دهیم: یک قابلیت جدید با هم می‌سازیم (دستیاری که دمای واقعی اتاق را می‌گوید) و منوی ایده‌ها را باز می‌کنیم؛ صفحه دفترچه مهندسی و ویدیوی «پروژه من» را کامل می‌کنیم؛ و یک گفت‌وگوی مهم خانوادگی داریم: سرویس‌های پولی مثل GPT و Claude چه فرقی دارند و کِی سراغشان برویم؟ دستیارت را روشن نگه دار — می‌بینمت!

</div>

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