آیرو — خودآموز رباتیک

فصل ۱۰ از ۱۱

پیشرفت ترم
۰٪

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

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

هوشِ پشت صحنه همان 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 — هات‌اسپات گوشی
گوشی با مرورگر ۱ مرورگر خود کامپیوتر

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

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

دیاگرام معماری دستیار: سمت چپ یک گوشی با جعبه متن که یک حباب گفتار free text می‌فرستد؛ فلش به برد ESP32 وسط؛ از برد فلشی بالا به یک ابرِ مغز با برچسب AI که یک کارت JSON کوچک {"action": "..."} با برچسب AI suggests برمی‌گرداند؛ زیر برد یک دروازه سپری‌شکل با برچسب Whitelist و فهرست هشت فرمان روی تخته؛ فقط بعد از سپر فلشی به سه LED و یک بازر و یک OLED با برچسب Action؛ مسیرِ ردشده سبز می‌درخشد و یک کارت قرمزِ ردشده از سپر به عقب می‌پرد

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

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

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

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

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

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

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

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

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

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

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

Javab: salam+chetori

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

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

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

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

✅ چک کن: آدرس 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 را چک می‌کنیم؟

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

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

حالا قلب پروژه: تابعی به اسم ask_ai که فرمان آزاد را می‌گیرد و فقط اسم یک action برمی‌گرداند. تماس با Gemini را از فصل ۹ کلمه‌به‌کلمه بلدی — کلید در هدر x-goog-api-key، بدنه با json.dumps، پارس تودرتو. چیز تازه، متن پرامپت است. یک رشته سه‌نقل‌قولی به اسم RULES می‌نویسیم که مثل قرارداد کاری 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: """

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

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

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

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

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

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

آهان! 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؛ سوم...

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

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

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

    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)

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

صحنه کارتونی: یک رباتِ نگهبان جلوی یک طناب مخملی و دری با آیکون چرخ‌دنده (اتاق اجرا) ایستاده، دستش یک تخته با فهرست فرمان‌های مجاز (green_on، red_off، beep، all_off)؛ یک کارت بلیت JSON شاد با برچسب green_on با تیک سبز رد می‌شود، ولی یک بلیت گنده و مشکوک با برچسب green_blink را دستِ بالاگرفته نگهبان مؤدبانه متوقف و به نیمکتِ unknown هدایت می‌کند؛ در پس‌زمینه یک شخصیت ابرِ مغز شانه بالا می‌اندازد

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

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

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

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

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

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

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

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

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

دیاگرام سیم‌کشی برد 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 به برد وصل است

حالا تابع 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:

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

اجرا کن، گوشی دستت است. تایپ کن «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 و فلش‌هایی که نشان می‌دهد در هر دو ساخت جا می‌افتند؛ هر دو پنل به یک گوشیِ واحد با جعبه فرمان متنی وصل‌اند

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

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

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

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

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

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

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

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

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

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

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

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

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

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

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.