# فصل ۴ — کالیبراسیون و رقص ربات

<div dir="rtl">

# فصل ۴ — کالیبراسیون و رقص ربات

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

فصل قبل ربات متولد شد و راه رفت — ولی یک چیز را هم دیدی: صاف‌صاف نمی‌رود. در این فصل با یک مسابقهٔ خط راست شروع می‌کنیم، می‌فهمیم چرا هیچ دو موتورِ «یکسانی» واقعاً یکسان نیستند، و رباتت را مثل مهندس‌ها **کالیبره** می‌کنی تا مثل تیر صاف برود. بعد به ماژول `robot.py` حرکت‌های زمان‌بندی‌شده اضافه می‌کنیم، چرخش ۹۰ درجه را تنظیم می‌کنیم و با همین ابزارها ربات را می‌فرستیم روی مسیر مربعی — و آخرش برایش یک **رقص کامل** طراحی می‌کنی! بخش همیار AI هم برمی‌گردد: یاد می‌گیری وقتی ربات خراب کار می‌کند، چطور از AI درست کمک بگیری. ریشهٔ کل ماجرای امروز این است:

![دو موتور گیربکسی زرد یکسان مثل دو دوندهٔ دوقلو روی پیست مسابقه: هر دو فرمان یکسان ۷۰۰ گرفته‌اند ولی یکی یک قدم جلوتر است؛ در پس‌زمینه ربات دوچرخ کوچکی از خط مستقیم خط‌چین فاصله می‌گیرد و به راست قوس می‌زند](/lesson-assets/t3-s04-calibration-choreography/prompt/01-image-motor-difference-twins.png)

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

- توضیح بدهی چرا دو موتور «کاملاً یکسان» هیچ‌وقت هم‌سرعت نیستند و ربات بدون تصحیح به یک سمت می‌کشد.
- با ضریب تصحیح و آزمایش خط راست، ربات خودت را کالیبره کنی — و بگویی چرا `duty` به `int()` نیاز دارد.
- توابع حرکت زمان‌بندی‌شده را به `robot.py` اضافه کنی و زمان چرخش ۹۰ درجهٔ ربات خودت را با آزمایش پیدا کنی.
- با `for` و یک لیست حرکات، مسیر مربعی و یک رقص کامل طراحی و اجرا کنی.
- برای گرفتن کمک Debug از AI، پیام سه‌قسمتی «علائم دقیق + کد + سؤال دقیق» بنویسی و جواب AI را با آزمایش محک بزنی.

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

قبل از ادامه، این چهار تا را چک کن — هر کدام لنگ می‌زند، اول برگرد همان فصل:

- **از فصل ۲:** درایور L298N — جهت با IN1/IN2 و IN3/IN4، سرعت با PWM روی ENA/ENB.
- **از فصل ۳:** ربات مونتاژشده + ماژول `robot.py` با توابع حرکت و import فایل خودمان — امروز همین ماژول ارتقا می‌یابد.
- **از ترم ۲، فصل ۲ و ۵:** PWM و duty بین ۰ تا ۱۰۲۳ + لیست و حلقه روی لیست (برای رقص).
- **از ترم ۲، فصل ۳ و ۴:** تابع `int()` و ذهنیت کالیبراسیون — «به‌جای حدس، با آزمایش عدد درست را پیدا کن».

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

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ربات کامل فصل ۳ (شاسی + ۲ موتور + L298N + ESP32 + باتری) | ۱ | — |
| باتری پر (۴×AA یا ۲×۱۸۶۵۰) | ۱ دست | حتماً پر؛ کالیبراسیون با باتری ضعیف بی‌فایده است |
| نوار چسب رنگی برای خط صاف روی زمین | حدود ۲ متر | نخ کشیده، درز کاشی‌های کف، یا لبهٔ فرش |
| متر یا خط‌کش بلند | ۱ | وجب دست! (دقت کمتر ولی کافی) |
| زمین صاف و باز | حدود ۲×۲ متر | راهروی خانه |
| کامپیوتر با Thonny + کابل USB | ۱ | مسیر شبیه‌ساز آخر فصل (منطق کد؛ بدون حرکت واقعی) |

یک قانون ایمنی برای کل فصل: هر کد جدید را که برای اولین بار اجرا می‌کنی، اول ربات را روی جعبه بگذار تا چرخ‌ها در هوا بچرخند. رباتِ روی جعبه با کد اشتباه فقط وول می‌خورد؛ رباتِ روی میز از لبه پرت می‌شود!

## ۱. مسابقهٔ خط راست

یک خط صاف روی زمین بچسبان، ربات را اول خط بگذار — طوری که چسب از وسط دو چرخ رد شود — و ازش بخواه دو ثانیه مستقیم برود. فقط همین! برنامه‌اش چیز جدیدی ندارد (فایل `01_line_test.py`):

</div>

```python
# Term 3 - Session 04 - test-e khat-e rast: robot cheghadr saf miravad?
# ghabl az ejra: robot.py bayad rooye borde zakhire shode bashad (jalase 3)
import robot
import time

robot.forward(700)   # ba sorat-e motevaset boro jelo
time.sleep(2)        # 2 sanie harekat
robot.stop()
print("be masir negah kon: saf bud ya be yek samt keshid?")
```

<div dir="rtl">

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

✅ **چک کن:** آزمایش را سه بار تکرار کن. اگر هر سه بار به همان یک سمت کشید، یک **الگوی ثابت** داری، نه یک اتفاق — و الگوی ثابت یعنی قابل درمان است.

## ۲. چرا دوقلوها هم‌سرعت نیستند؟

به دو موتورت نگاه کن. ظاهرشان صددرصد یکسان است، از یک کارخانه، از یک جعبه. ولی مثل دوقلوها هستند: شبیه هم‌اند، اما یکی‌شان همیشه در دو کمی تندتر می‌دود — تصویر اول فصل! داخل هر موتور یک سیم‌پیچ و یک گیربکس با چند چرخ‌دنده است. سیم‌پیچِ یکی چند دور بیشتر یا کمتر خورده، چرخ‌دنده‌های یکی کمی سفت‌تر همدیگر را می‌سایند، حتی لاستیک یک چرخ ممکن است یک میلی‌متر کلفت‌تر باشد. نتیجه؟ با فرمان یکسان — هر دو duty برابر ۷۰۰ — یکی مثلاً سه چهار درصد تندتر می‌چرخد. سه درصد به نظر هیچی است، ولی در دو متر مسیر، می‌شود همان قوسی که دیدی.

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

## چالش: کشیدن به چپ

اگر ربات تو به چپ بکشد، کدام موتور کندتر است و باید کدام موتور را آرام‌تر کنیم؟

---

**جواب:** موتور چپ کندتر است (ربات به سمت موتور کندتر می‌پیچد) و ما موتورِ تندتر — یعنی راست — را کمی آرام می‌کنیم تا هم‌سرعتِ چپ شود.

## ۳. ضریب تصحیح: کالیبراسیون واقعی

راه‌حل چیست؟ نمی‌توانیم داخل موتور را عوض کنیم، ولی می‌توانیم با نرم‌افزار جبران کنیم: **موتورِ تندتر را کمی آرام می‌کنیم تا هم‌سرعتِ موتور کندتر شود.** به این کار می‌گویند کالیبراسیون — همان ذهنیت ترم ۲، فصل ۴ با آستانهٔ سنسور نور: به‌جای حدس زدن، با آزمایش عدد درست را پیدا می‌کنیم.

ابزارش یک ضرب ساده است. اگر duty موتور چپ را در عددی مثل `0.92` ضرب کنیم، موتور چپ هشت درصد آرام‌تر می‌شود. به این عدد می‌گوییم **ضریب تصحیح** — Correction Factor. فایل `robot.py` را باز کن؛ می‌خواهیم مغز ربات را ارتقا بدهیم. بالای فایل، بعد از تعریف پایه‌ها، دو متغیر جدید:

</div>

```python
FACTOR_LEFT = 0.92
FACTOR_RIGHT = 1.0
```

<div dir="rtl">

اسم‌ها با حروف بزرگ — همان قرارداد آشنای ترم ۲ برای عددهای تنظیمی که وسط برنامه عوض نمی‌شوند. موتور راستِ ربات نمونه کندتر بود، پس ضریبش ۱٫۰ می‌ماند (دست‌نخورده) و چپِ تندتر با ۰٫۹۲ آرام می‌شود. حالا یک تابع کوچک که سرعت هر دو موتور را با ضریب خودش تنظیم کند، تا این ضرب فقط یک جا در کل ماژول باشد:

</div>

```python
def set_speed(speed):
    ena.duty(speed * FACTOR_LEFT)
    enb.duty(speed * FACTOR_RIGHT)
```

<div dir="rtl">

و داخل همهٔ توابع حرکت، به‌جای دو خط `duty` قبلی، فقط `set_speed(speed)` را صدا می‌زنیم. ذخیره روی برد، و تست خط راست را دوباره اجرا کن:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
  File "robot.py", line 30, in forward
  File "robot.py", line 22, in set_speed
TypeError: can't convert float to int
```

<div dir="rtl">

خطای قرمز! نترس — مثل همیشه از خط آخر بخوان: «نمی‌توانم float را به int تبدیل کنم». و خط‌های بالایش آدرس می‌دهند: مشکل در `set_speed` داخل `robot.py`. (شمارهٔ خط‌ها در فایل تو شاید کمی فرق داشته باشد.) فکر کنیم: `700 * 0.92` چند می‌شود؟ ۶۴۴٫۰ — یک عدد **اعشاری**، چون هر وقت int را در float ضرب کنی، جواب float است. ولی `duty` فقط عدد صحیح قبول می‌کند؛ نمی‌شود به موتور گفت «۶۴۴ و نیم قدم برو»! راه‌حل را از ترم ۲، فصل ۳ می‌شناسی: تابع `int()` که اعشار را می‌اندازد و قسمت صحیح را نگه می‌دارد. تابع را درست کن:

</div>

```python
def set_speed(speed):
    # duty faghat adad-e sahih ghabul mikonad -> int() lazem ast
    ena.duty(int(speed * FACTOR_LEFT))
    enb.duty(int(speed * FACTOR_RIGHT))
```

<div dir="rtl">

ذخیره، اجرا... دیگر آن قوس بزرگ به راست نیست — ولی حالا کمی به چپ می‌کشد! یعنی چه؟ یعنی زیادی موتور چپ را آرام کردیم؛ ۰٫۹۲ زیادی کم بود. عدد را کمی بالا ببر: ۰٫۹۵.

و حالا یک نکتهٔ طلایی که خیلی‌ها را ساعت‌ها معطل کرده: `robot.py` را عوض می‌کنی، ذخیره می‌کنی، تست را اجرا می‌کنی و... هیچ فرقی نکرد! چرا؟! مشکل این‌جاست: MicroPython ماژول‌ها را فقط **بار اول** import واقعاً می‌خواند؛ دفعه‌های بعد از حافظه‌اش برمی‌دارد که سریع‌تر باشد. پس نسخهٔ جدید `robot.py` اصلاً سوار نشده!

> 💡 **نکته:** قانونش را یک بار برای همیشه یاد بگیر: **بعد از هر تغییر در robot.py، اول Stop/Restart در Thonny (همان Ctrl+F2)، بعد اجرا.** برد از نو شروع می‌کند و import بعدی، فایلِ تازه را می‌خواند.

دوباره: ۰٫۹۵، ری‌استارت، اجرا... کمی به راست. ۰٫۹۴، ری‌استارت، اجرا... صاف مثل تیر! ضریب ربات نمونهٔ ما شد ۰٫۹۴.

✅ **چک کن:** ربات تمام طول خط را روی چسب می‌ماند. عدد ربات تو قطعاً فرق دارد — شاید اصلاً موتور چپت کندتر باشد و `FACTOR_RIGHT` را کم کنی. این عدد مالِ ربات توست، مثل شمارهٔ کفشت؛ در دفترچهٔ مهندسی یادداشتش کن.

## چالش: ضریب نصفه

اگر `FACTOR_LEFT` را `0.5` بگذاری، با `forward(700)` موتور چپ چه duty می‌گیرد و ربات چه شکلی حرکت می‌کند؟

---

**جواب:** موتور چپ `int(700 * 0.5)` یعنی ۳۵۰ می‌گیرد و راست ۷۰۰. چپ خیلی کندتر از راست می‌چرخد، پس ربات به‌جای خط راست، یک قوس تند به سمت چپ می‌زند — شاید هم چپ اصلاً راه نیفتد (آستانهٔ راه‌افتادن فصل ۲!) و ربات دور خودش بچرخد.

## ۴. حرکت زمان‌بندی‌شده و چرخش ۹۰ درجه

ربات حالا صاف می‌رود، ولی هنوز نمی‌داند «چقدر» برود. ربات ما نه متر دارد نه GPS؛ تنها چیزی که دارد **زمان** است. اگر بدانیم در یک ثانیه حدوداً نیم متر می‌رود، می‌توانیم بگوییم «یک و نیم ثانیه برو» و بدانیم کجا می‌ایستد. اسمش حرکت زمان‌بندی‌شده است. الگویش را بارها نوشته‌ایم: حرکت کن، `time.sleep`، بایست. به‌جای کپی کردن این سه خط — و می‌دانی که با کپی‌پیست دشمنیم! — یک تابع تمیز در `robot.py` می‌سازیم:

</div>

```python
def forward_time(speed, seconds):
    forward(speed)
    time.sleep(seconds)
    stop()
```

<div dir="rtl">

دو پارامتر: سرعت و مدت. دقت کن داخل ماژول، تابع‌های همان فایل را بدون `robot.` صدا می‌زنیم — چون خانهٔ خودشان است! سه‌قلوهای دیگرش را هم بساز: `backward_time` و `turn_left_time` و `turn_right_time` — دقیقاً همین شکل، فقط تابع حرکتشان فرق دارد. (بالای فایل هم `import time` لازم می‌شود — نسخهٔ کامل فایل را آخر همین بخش آورده‌ایم.) ذخیره، ری‌استارت — یادت که نرفته! — و در Shell با رباتِ روی جعبه امتحان کن... ولی بگذار یک غلط تایپی واقعی هم ببینیم:

</div>

```text
>>> import robot
>>> robot.forward_tim(700, 1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'forward_tim'
```

<div dir="rtl">

بخوان: `AttributeError` یعنی «چنین چیزی در این ماژول نیست». ماژول robot چیزی به اسم `forward_tim` ندارد — چون `e` آخر جا افتاده! این خطا را از این به بعد زیاد می‌بینی؛ معنی‌اش تقریباً همیشه یکی از این دو است: یا اسم را غلط تایپ کرده‌ای، یا نسخهٔ قدیمی ماژول هنوز روی برد است. `forward_time` کامل — و چرخ‌ها یک ثانیه می‌چرخند و می‌ایستند. تمیز!

حالا کالیبراسیون دوم و مهم: **چرخش ۹۰ درجه.** با `turn_right`، چرخ چپ جلو و چرخ راست عقب می‌چرخد و ربات سر جایش می‌چرخد. ولی چقدر طول بکشد تا دقیقاً یک‌چهارم دور باشد؟ هیچ فرمولی نیست — فقط آزمایش:

1. ربات را روی زمین بگذار و جهتش را یادت نگه دار (یا با چسب علامت بزن).
2. `robot.turn_right_time(700, 0.3)` را امتحان کن... کم چرخید؟ (ربات نمونه: حدود ۶۰ درجه.)
3. `0.6` را امتحان کن... زیادی؟ (حدود ۱۲۰ درجه.)
4. وسطش را بزن: `0.45`... تقریباً دقیق ۹۰ درجه!

✅ **چک کن:** عدد جادویی ربات نمونه `0.45` ثانیه شد. عدد ربات تو فرق دارد — و روی فرش و سرامیک هم فرق می‌کند، چون چرخ روی کف براق سُر می‌خورد. مثل ضریب تصحیح، یادداشتش کن.

نسخهٔ کامل `robot.py` تا اینجا این است. ضریب‌ها و عدد `0.94` مال ربات نمونه‌اند؛ عددهای ربات خودت را بگذار. فصل‌های بعد همین فایل را استفاده می‌کنند.

</div>

```python
# robot.py - Term 3 - Session 04
# module-e harekat-e robot + zarib-e tashih (calibration) + harekat-e zaman-bandi-shode
# L298N: ENA=32, IN1=26, IN2=27, IN3=14, IN4=25, ENB=33
# Motor-e chap: ENA + IN1/IN2   |   Motor-e rast: ENB + IN3/IN4

from machine import Pin, PWM
import time

ena = PWM(Pin(32), freq=1000)   # sorat-e motor-e chap
in1 = Pin(26, Pin.OUT)
in2 = Pin(27, Pin.OUT)
in3 = Pin(14, Pin.OUT)
in4 = Pin(25, Pin.OUT)
enb = PWM(Pin(33), freq=1000)   # sorat-e motor-e rast

# zarib-e tashih: motor-e tondtar ra kami aheste mikonim ta robot saf beravad
# in do adad ra ba "test-e khat-e rast" baraye robot-e KHODET tanzim kon
FACTOR_LEFT = 0.94
FACTOR_RIGHT = 1.0

def set_speed(speed):
    # duty faghat adad-e sahih ghabul mikonad -> int() lazem ast
    ena.duty(int(speed * FACTOR_LEFT))
    enb.duty(int(speed * FACTOR_RIGHT))

def forward(speed):
    in1.value(1)
    in2.value(0)
    in3.value(1)
    in4.value(0)
    set_speed(speed)

def backward(speed):
    in1.value(0)
    in2.value(1)
    in3.value(0)
    in4.value(1)
    set_speed(speed)

def turn_left(speed):
    # chap aghab, rast jelo -> charkhesh dar ja be samt-e chap
    in1.value(0)
    in2.value(1)
    in3.value(1)
    in4.value(0)
    set_speed(speed)

def turn_right(speed):
    # chap jelo, rast aghab -> charkhesh dar ja be samt-e rast
    in1.value(1)
    in2.value(0)
    in3.value(0)
    in4.value(1)
    set_speed(speed)

def stop():
    set_speed(0)
    in1.value(0)
    in2.value(0)
    in3.value(0)
    in4.value(0)

# --- harekat-haye zaman-bandi-shode (jadid dar jalase 4) ---

def forward_time(speed, seconds):
    forward(speed)
    time.sleep(seconds)
    stop()

def backward_time(speed, seconds):
    backward(speed)
    time.sleep(seconds)
    stop()

def turn_left_time(speed, seconds):
    turn_left(speed)
    time.sleep(seconds)
    stop()

def turn_right_time(speed, seconds):
    turn_right(speed)
    time.sleep(seconds)
    stop()

stop()                 # dar shoroo hame chiz khamoosh — imeni!
```

<div dir="rtl">

## چالش: نیم‌دور

با `TURN_90` برابر ۰٫۴۵، اگر بخواهی ربات دقیقاً نیم‌دور (۱۸۰ درجه) بچرخد چه عددی می‌دهی؟

---

**جواب:** دو برابرش: ۰٫۹ ثانیه. چرخش با زمان تقریباً خطی است — ۱۸۰ درجه یعنی دو تا ۹۰ درجه پشت سر هم.

## ۵. پروژهٔ ۱: مسیر مربعی

همهٔ قطعات پازل را داریم: ربات صاف می‌رود، سر وقت می‌ایستد و ۹۰ درجه می‌چرخد. مربع چیست؟ چهار بار «برو جلو، بپیچ ۹۰ درجه». چهار بار تکرار... این که شغل حلقهٔ `for` است! (فایل `02_square_path.py`):

</div>

```python
# Term 3 - Session 04 - masir-e morabbai: 4 zel + 4 charkhesh-e 90 daraje
import robot

SPEED = 700        # sorat-e harekat (duty az 0 ta 1023)
SIDE_TIME = 1.5    # zaman-e har zel (sanie)
TURN_90 = 0.45     # zaman-e charkhesh-e 90 daraje - ba azmayesh tanzim kon!

for i in range(4):
    print(f"zel-e {i}")
    robot.forward_time(SPEED, SIDE_TIME)
    robot.turn_right_time(SPEED, TURN_90)

print("morabba tamam shod!")
```

<div dir="rtl">

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

اجرا... ضلع یک... پیچ... ضلع دو... پیچ... ضلع سه... ضلع چهار... و ایست!

✅ **چک کن:** ببین ربات کجا ایستاد — نزدیک نقطهٔ شروع، ولی احتمالاً نه دقیقاً رویش؛ شاید یک وجب آن‌طرف‌تر:

![نقشهٔ مسیر مربعی از بالا: مربع ایدئال با خط‌چین سبز و چهار ضلع ۱٫۵ ثانیه‌ای و چهار پیچ ۹۰ درجه، و مسیر واقعی ربات با خط نارنجی که در هر گوشه کمی کم می‌پیچد و نقطهٔ پایانش با فاصلهٔ کوچکی از پرچم شروع، با براکت قرمز «فاصله!»، جا می‌ماند](/lesson-assets/t3-s04-calibration-choreography/prompt/03-image-square-path-plan.png)

بیا صادق باشیم: این طبیعی است و هیچ کد بهتری کاملش نمی‌کند. هر ضلع یک خطای کوچک دارد — یک ذره سُر خوردن چرخ، یک ذره افت باتری — و چهار ضلع یعنی چهار خطا که روی هم جمع می‌شوند. اسمش **خطای تجمعی** است. ربات ما با چشم بسته و فقط با زمان حرکت می‌کند؛ رانندهٔ چشم‌بسته هرچقدر هم دقیق، کم‌کم از مسیر خارج می‌شود. راه‌حل واقعی چیست؟ این‌که ربات محیط را **حس کند** — و این دقیقاً موضوع فصل بعد است!

## چالش: از مربع به مثلث

برای این‌که ربات مثلث برود، چه چیزهایی را باید عوض کنی؟ راهنمایی: مثلث سه ضلع دارد و هر پیچش تندتر از ۹۰ درجه است.

---

**جواب:** حلقه `range(3)` می‌شود، و زمان چرخش باید برای ۱۲۰ درجه باشد: ۱۲۰ تقسیم بر ۹۰ یعنی چهارسومِ `TURN_90` — حدود ۰٫۶ ثانیه برای ربات نمونه. عدد دقیق را با آزمایش تنظیم کن.

## ۶. پروژهٔ ۲: رقص ربات

و حالا قسمت خوش‌مزهٔ فصل! مربع قشنگ بود ولی همهٔ حرکت‌هایش یک‌جور بود. رقص یعنی توالی حرکت‌های مختلف: جلو، چرخ به راست، عقب، یک دور کامل... این «توالی» را کجا نگه داریم؟ در یک **لیست** — همان جعبهٔ چندخانه‌ای ترم ۲! هر عضو لیست اسم یک حرکت است، حلقه روی لیست راه می‌رود و هر حرکت را اجرا می‌کند. این ساختار اسم حرفه‌ای هم دارد: Choreography — طراحی رقص! (فایل `03_robot_dance.py`):

</div>

```python
# Term 3 - Session 04 - raghs-e robot: list-e harekat-ha + for + if/elif
import robot
import time

SPEED = 700
TURN_90 = 0.45   # haman adad-e calibre-shode-ye robot-e khodet

# harekat-haye raghs: har ozv-e list yek ghadam ast
dance = ["jelo", "rast", "jelo", "chap", "aghab", "charkh", "jelo"]

for move in dance:
    print(f"harekat: {move}")
    if move == "jelo":
        robot.forward_time(SPEED, 1.0)
    elif move == "aghab":
        robot.backward_time(SPEED, 1.0)
    elif move == "rast":
        robot.turn_right_time(SPEED, TURN_90)
    elif move == "chap":
        robot.turn_left_time(SPEED, TURN_90)
    elif move == "charkh":
        robot.turn_right_time(SPEED, TURN_90 * 4)   # yek dor-e kamel: 4 x 90 daraje
    time.sleep(0.3)   # yek nafas beyn-e harekat-ha

print("raghs tamam shod!")
```

<div dir="rtl">

خط‌به‌خط بخوانیم: لیست `dance` هفت حرکت دارد. حلقهٔ `for move in dance` مثل ترم ۲ روی لیست قدم می‌زند و هر بار اسم یک حرکت را در `move` می‌گذارد. زنجیرهٔ if/elif — رفیق قدیمی ترم ۱ — اسم را به تابع حرکت ترجمه می‌کند. حرکت `charkh` را ببین: یک دور کامل یعنی چهار تا ۹۰ درجه، پس `TURN_90 * 4` — ریاضیِ کالیبراسیون دارد کار می‌کند! و آن `time.sleep(0.3)` بین حرکت‌ها یک مکث کوتاه است که رقص، ریتم بگیرد.

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

✅ **چک کن:** اجرا! جلو... پیچ... جلو... چپ... عقب... و چرخِ کامل! ربات تو دارد می‌رقصد. این را حتماً فیلم بگیر و برای خانواده‌ات بفرست — اولین اجرای هنری ربات توست.

> 🧪 **آزمایشگاه:** مدار شش‌LEDی این فصل در آزمایشگاه آماده است و رقصِ ربات همان‌جا اجرا می‌شود — با `robot.py` به‌عنوان فایل جدا. آنچه می‌بینی رقصِ چراغ‌هاست، نه رقصِ ربات. [مدار را همین‌جا امتحان کن](/lab).

## ۷. با AI: گزارش سه‌قسمتی Debug

بخش همیار AI امروز مهم‌ترینِ کل ترم است، چون از امروز رباتت مدام رفتارهای عجیب خواهد داشت و AI می‌تواند کمک‌کار خوبی باشد — اگر بلد باشی درست ازش کمک بگیری. مهارت امروز: **گزارش سه‌قسمتی.** وقتی چیزی خراب است، به AI این سه چیز را بده:

![کارت دستور سه‌قسمتی Debug: قاب اول ربات کوچکی که با ذره‌بین از مسیر مستقیم منحرف شده (علائم)، قاب دوم برگهٔ کد رنگی (کد)، قاب سوم علامت سؤال بزرگ با نشانگر هدف (سؤال دقیق) — هر سه به حباب گفت‌وگوی یک ربات AI می‌ریزند و پایین، مهر «آزمایشش کن!»](/lesson-assets/t3-s04-calibration-choreography/prompt/04-image-ai-debug-recipe.png)

- **یک، علائم دقیق:** نه «کار نمی‌کند»، بلکه «چه کاری را چند بار امتحان کردی و دقیقاً چه دیدی».
- **دو، کد:** همان فایل واقعی، کامل.
- **سه، سؤال دقیق:** چه جوابی می‌خواهی؟

مقایسه کن. سؤال بد: «ربات من صاف نمی‌رود، چرا؟» — AI فقط می‌تواند حدس‌های کلی بزند. سؤال خوب، گزارش سه‌قسمتی: «ربات دوچرخ من با ESP32 و درایور L298N کار می‌کند. علائم: با forward(700) به‌جای خط راست، قوس باز به راست می‌رود. سه بار تست کردم، هر بار همان. باتری نو است، ضریب تصحیح ۰٫۹۲ هم گذاشته‌ام ولی قوس بدتر شد. کد ماژول حرکتم را کامل می‌فرستم: [کل robot.py]. سؤال: به نظرت مشکل کجاست و اول چه آزمایشی انجام بدهم؟»

و AI جواب می‌دهد — ولی ببین چه جوابی: «مشکل پیدا شد! در ESP32 مقدار duty فقط می‌تواند بین ۰ تا ۲۵۵ باشد. عدد ۷۰۰ خارج از محدوده است و باعث رفتار نامنظم موتور می‌شود. سرعت را به ۲۰۰ تغییر بده تا مشکل حل شود.»

قانع‌کننده به نظر می‌رسد، نه؟ با اعتماد به نفس کامل هم گفته! ولی صبر کن — قانون سوم: آزمایش. اولاً ما کل ترم ۲ با duty تا ۱۰۲۳ کار کردیم و LED با ۱۰۲۳ کاملاً درست fade می‌شد. ثانیاً همین حالا تست کن: `forward(200)`... ربات آرام‌تر می‌رود ولی هنوز همان قوس را می‌زند! پس ادعای AI **غلط** بود — آن عدد ۲۵۵ مال بردهای دیگری است که AI با ESP32 قاطی کرده. اگر کورکورانه قبول می‌کردیم، فقط رباتمان کند می‌شد و مشکل سر جایش می‌ماند.

حالا قانون اول و دوم: خودمان خط‌به‌خط `robot.py` را می‌خوانیم... و ایناهاش! در این سناریو `FACTOR_RIGHT = 0.92` نوشته شده بود — یعنی موتورِ راست که خودش کندتر بود، باز هم کندتر شده! ضریب باید روی موتورِ تندتر یعنی چپ می‌نشست. یک جابه‌جایی ساده و ربات صاف می‌رود.

> 🤖 **با AI:** جمع‌بندی در یک جمله: گزارش سه‌قسمتی بده — علائم دقیق، کد کامل، سؤال دقیق — ولی جواب AI فقط یک «حدس قابل آزمایش» است؛ آزمایشش کن. سه قانون همیشگی سر جایشان‌اند: «اول خودت، بعد AI»، «خط به خط» (کدی که نمی‌فهمی در پروژه‌ات نگذار)، «AI هم اشتباه می‌کند». و مثل همیشه: حساب کاربری فقط با اجازه و کمک والدین.

## قطعه نداری؟ مسیر شبیه‌ساز

آزمایشگاه ما موتور DC و درایور L298N ندارد، پس «حرکت» را نمی‌شود شبیه‌سازی کرد — ولی منطق کدهای این فصل را می‌شود، و مدارش هم از قبل چیده شده: [آزمایشگاه](/lab) را باز کن، ترم ۳ و بعد این فصل را انتخاب کن و «اجرا ▶» را بزن. روی هر شش پین موتور یک LED نشسته: LEDهای پین‌های IN جهت را نشان می‌دهند (کدام روشن است؟) و LEDهای ENA (پایهٔ ۳۲) و ENB (پایهٔ ۳۳) با روشنایی‌شان سرعت را — چون PWM هستند، درست مثل fade ترم ۲! موقع اجرای مربع یا رقص، الگوی روشن شدن LEDها همان «رقص» است، فقط بدون چرخ.

> 💡 **نکته:** `robot.py` هم آن‌جا یک فایل جداست، پس `import robot` بدون هیچ دستکاری کار می‌کند. LEDهای ENA و ENB واقعاً کم‌وزیاد نور می‌دهند، چون شبیه‌ساز جریانِ عبوری از هر LED را حساب می‌کند. ولی این «رقصِ چراغ‌ها»ست نه رقصِ ربات — و مهم‌تر از همه: **کالیبراسیون در شبیه‌ساز بی‌معناست.** آن‌جا هر دو موتور مجازی دقیقاً یکسان‌اند و اصلاً کجی‌ای وجود ندارد که جبرانش کنی؛ ضریب تصحیح و عدد `TURN_90` فقط روی رباتِ خودت، روی زمین واقعی، پیدا می‌شوند.

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Calibration | کالیبرِیشِن | تنظیم دقیق یک دستگاه با آزمایش و اندازه‌گیری |
| Factor | فَکتور | ضریب؛ عددی که در چیز دیگری ضرب می‌شود |
| Drift | دریفت | کج‌رفتن تدریجی از مسیر مستقیم |
| Timing | تایمینگ | زمان‌بندی؛ کنترل حرکت با مدت زمان |
| Choreography | کوریوگرافی | طراحی توالی حرکات — همان طراحی رقص |
| Symptom | سیمپتوم | علامت و نشانهٔ یک مشکل (در گزارش Debug) |
| Accumulate | اِکیومولِیت | جمع‌شدن کم‌کم — مثل خطای تجمعی مربع |

## تمرین‌ها

اول چک‌لیست پایان فصل: ربات بعد از کالیبراسیون، مسیر حدوداً دو متری را با انحراف کمتر از حدود یک وجب می‌رود و ضریب تصحیحش را از حفظی؛ چرخش ۹۰ درجه کالیبره شده و مربع تقریبی اجرا شده؛ رقص از روی لیست اجرا شده و می‌دانی برای تغییر رقص فقط لیست عوض می‌شود؛ و سه جزء گزارش Debug برای AI را نام می‌بری — و می‌دانی با جواب AI چه می‌کنیم: آزمایش! اگر هر چهار تا بله است، برو سراغ تمرین‌ها:

- **تمرین اجباری:** ربات خودت را کامل کالیبره کن: ضریب تصحیح و `TURN_90` مخصوص رباتت را با آزمایش پیدا کن و هر دو عدد را با تاریخ در دفترچهٔ مهندسی‌ات بنویس. بعد مسیر مربعی را اجرا کن و فاصلهٔ نقطهٔ پایان تا نقطهٔ شروع را اندازه بگیر و یادداشت کن. اسم فایلت را بگذار `my_square.py`.
- **تمرین ستاره‌دار ⭐:** یک رقص حداقل هشت‌حرکته با موسیقی دلخواهت طراحی کن (`my_dance.py`) که دست‌کم یک حرکت ابداعی جدید داشته باشد — مثلاً «تکان‌تکان»: سه عقب‌جلوی خیلی کوتاه با یک `for` داخل همان `elif`. از اجرایش فیلم بگیر — این ویدیو اولین «اجرای صحنه‌ای» ربات توست!

## در فصل بعد

مربع ما دقیقاً بسته نشد — و اگر وسط رقص، گربهٔ خانه جلوی ربات بنشیند چه؟ ربات ما کور است: می‌رود تو! فصل بعد سنسور فاصلهٔ HC-SR04 که از ترم ۲ می‌شناسی، می‌رود روی صورت ربات و می‌شود چشمش — رباتی می‌سازیم که با سرعت به سمت دیوار می‌رود و درست سر فاصلهٔ ایمن، خودش ترمز می‌کند.

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t3/s04-calibration-choreography (یادستان, Yaadestan)
