# فصل ۳ — توابع C++ و آزمون سرعت

<div dir="rtl">

# فصل ۳ — توابع C++ و آزمون سرعت

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

دو فصل است که در کشور C++ زندگی می‌کنیم: Blink را ترجمه کردی، type ها و Serial را یاد گرفتی. امروز دو اتفاق می‌افتد. اول، جعبه‌ابزارت کامل می‌شود: حلقه‌ی `for` به سبک C++، تابع‌های type دار و آرایه — بعد از امروز هر برنامه‌ای که در MicroPython بلدی، در C++ هم می‌توانی. و دوم، چیزی که از فصل اول قولش را داده‌ام: **مسابقه‌ی سرعت** بین دو زبان روی یک برد. آخر فصل هم برای اولین بار موتورهای ربات ترم ۳ با کد C++ می‌چرخند.

![سیم‌کشی ESP32 به درایور L298N و یک موتور زردِ گیربکسی: سیم GPIO 32 به ENA (با نشان PWM)، GPIO 26 به IN1 و GPIO 27 به IN2، باتری و یک سیم ضخیمِ GND مشترک؛ گوشه‌ی تصویر رباتِ دوچرخ روی جعبه با چرخ‌ها در هوا و برچسب «wheels up!»](/lesson-assets/t5-s03-cpp-functions-speed/prompt/05-image-l298n-cpp-wiring.png)

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

- حلقه‌ی `for` سه‌قسمتی و `while` را در C++ بنویسی و با `for i in range(...)` مقایسه کنی.
- تابع C++ با type بازگشتی و پارامترهای type دار تعریف کنی و بگویی `void` یعنی چه.
- آرایه‌ی ساده تعریف و با حلقه بخوانی و سه فرقش با لیست Python را بگویی.
- با کرنومتر میلی‌ثانیه‌ای (`millis`) آزمون سرعت زنده‌ی دو زبان را روی یک برد اجرا و تفسیر کنی.
- کنترل موتور ترم ۳ را با `ledcAttach`/`ledcWrite` به C++ ترجمه کنی و «پله‌های سرعت» بسازی.

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

- **از فصل ۱ و ۲:** Arduino IDE و upload، `setup`/`loop`، type ها، Serial، سمی‌کالن و آکولاد، و راه رفت‌وبرگشت فریمور. رفت‌وبرگشت فریمور امروز برای مسابقه لازم می‌شود.
- **از ترم ۲، فصل ۱:** تعریف تابع با `def`، پارامتر و `return`. امروز نسخه‌ی type دارش می‌آید.
- **از ترم ۲، فصل ۲:** PWM و duty (بازه‌ی `0` تا `1023`). معادل C++ اش امروز ساخته می‌شود.
- **از ترم ۲، فصل ۵:** لیست و index — برای مقایسه با آرایه.
- **از ترم ۳، فصل ۲ و ۳:** L298N (جهت با IN1/IN2، سرعت با PWM روی ENA)، ایمنی باتری و GND مشترک. مدار امروز همان است.

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

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ESP32 DevKit + کابل USB | ۱ | — |
| ربات ترم ۳ (L298N + موتورها + باتری) | ۱ | فقط L298N + یک موتور TT روی میز |
| پایه/جعبه برای بالا نگه‌داشتن ربات (چرخ‌ها در هوا) | ۱ | یک لیوان محکم یا جعبه‌ی کیت |
| کامپیوتر با Arduino IDE + Thonny | ۱ | — |

## ۱. حلقه‌ی for: دستور سه‌قسمتی

فصل اول دیدی که `loop` خودش یک «تکرارِ بی‌پایان» مجانی است. ولی تکرارِ شمرده چطور؟ در Python می‌گفتیم `for i in range(5)`. در C++ همان حرف را با جزئیات بیشتری می‌زنیم:

</div>

```cpp
for (int i = 1; i <= 5; i = i + 1) {
  Serial.println(i);
}
Serial.println("payan!");
```

<div dir="rtl">

داخل پرانتز سه قسمت هست که با سمی‌کالن جدا شده‌اند — مثل یک دستور تمرین ورزشی:

- **شروع** (`int i = 1`): یک شمارنده بساز و از ۱ شروع کن.
- **شرط ماندن** (`i <= 5`): تا وقتی این درست است، ادامه بده.
- **قدم** (`i = i + 1`): بعد از هر دور، یکی اضافه کن.

دقیقاً همان کاری که `range` برایت پنهانی می‌کرد، اینجا جلوی چشمت است — برای همین کنترلش هم بیشتر است: می‌توانی دوتا دوتا بپری، از بالا به پایین بشماری، از هر عددی شروع کنی. یک نکته‌ی صادقانه هم بگویم چون در کدهای دنیا زیاد می‌بینی‌اش: بیشترِ برنامه‌نویس‌ها به‌جای `i = i + 1` خلاصه‌اش را می‌نویسند: `i++` — بخوان «آی پلاس پلاس»، یعنی «یکی بینداز رویش». از حالا هر دو شکل را بشناس. راستی حالا می‌دانی اسم C++ از کجا آمده: «C به‌علاوه‌ی یک» — زبانی که یک قدم از زبان C جلوتر رفت!

`while` هم در C++ هست و چهره‌اش آشناست: `while (شرط) { }` — همان while خودمان، فقط شرطش داخل پرانتز و بدنه‌اش داخل آکولاد. چند دقیقه‌ی دیگر، `while` ستاره‌ی مسابقه‌ی ماست.

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

بدنه‌ی `for (int i = 0; i < 3; i++)` چند بار اجرا می‌شود؟ و اگر شرط را `i <= 3` کنی چطور؟

---

**جواب:** با `i < 3` سه بار (برای `i` برابر ۰، ۱، ۲). با `i <= 3` چهار بار (۰، ۱، ۲، ۳). به همین دلیل مرزِ شرط را همیشه با دقت انتخاب کن.

## ۲. تابع با type بازگشتی: کارخانه با برچسب محصول

توابع را از ترم ۲ می‌شناسی: کارخانه‌ی کوچکی که ورودی می‌گیرد و محصول تحویل می‌دهد. در C++ همان کارخانه است با یک قانون شفاف‌سازی: باید روی درِ کارخانه بنویسی **محصولت چه جنسی است**. بیا یک تابع به‌دردبخور بسازیم — مترجم درصد به duty. در ترم ۲ سرعت PWM را با duty بین `0` تا `1023` می‌دادیم، ولی آدم با «درصد» راحت‌تر فکر می‌کند:

</div>

```cpp
// darsad (0..100) -> duty (0..1023)
int percentToDuty(int percent) {
  return percent * 1023 / 100;
}
```

<div dir="rtl">

بخوانیمش: آن `int` اولی می‌گوید محصول این کارخانه از جنس `int` است. `percentToDuty` اسمش است. داخل پرانتز، ورودی هم type خودش را دارد: `int percent`. و `return` همان return عزیز ترم ۲. در Python می‌نوشتیم `def percent_to_duty(percent):` و type ها را نمی‌نوشتیم، چون مترجمِ همزمان سرِ اجرا خودش می‌فهمید. کامپایلر ولی قبل از اجرا می‌خواهد همه‌چیز را بداند — همین سخت‌گیری هم سرعت می‌دهد هم خیلی از باگ‌ها را قبل از upload می‌گیرد.

![کارخانه‌ی کوچکی که یک تابع C++ را نشان می‌دهد: نوار ورودی یک جعبه‌ی «int percent» با عدد ۵۰ می‌آورد، تابلوی درِ کارخانه «int percentToDuty» است و نوار خروجی جعبه‌ی «۵۱۱» تحویل می‌دهد؛ کنارش کارخانه‌ی دومی با برچسب void که خروجی‌اش خالی است](/lesson-assets/t5-s03-cpp-functions-speed/prompt/02-image-typed-function-machine.png)

یک نگاه دوم به داخل فرمول بینداز — دام فصل قبل همین‌جا کمین کرده! نوشتیم `percent * 1023 / 100`: اول ضرب، بعد تقسیم. اگر برعکس می‌نوشتیم — `percent / 100 * 1023` — چون `percent` و `100` هر دو `int` اند، برای هر درصد زیر ۱۰۰ حاصل تقسیم می‌شد **صفر**، و کل تابع همیشه صفر می‌داد! تقسیم صحیح، بی‌صدا و بی‌خطا.

و راز فصل اول هم حل شد: تابعی که محصولی تحویل نمی‌دهد — فقط کاری انجام می‌دهد — روی درش می‌نویسند `void` یعنی «هیچ». `setup` و `loop` از روز اول توابع void بودند! حالا یک خرابکاری عمدی: type بازگشتی را از `percentToDuty` بردار و compile بزن:

</div>

```text
error: ISO C++ forbids declaration of 'percentToDuty' with no type
    4 | percentToDuty(int percent) {
      | ^~~~~~~~~~~~~
```

<div dir="rtl">

پیام رک و راست است: «C++ اجازه‌ی تعریف بدون type نمی‌دهد.» هر تابعی برچسب می‌خواهد: یا جنس محصول، یا `void`. برچسب را برگردان — سبز. تست هم بکن: `Serial.println(percentToDuty(50));` باید بشود ۵۱۱ — نصف ۱۰۲۳، گرد شده به پایین.

## چالش: کدام type بازگشتی؟

تابعی که دمای اعشاری می‌گیرد و فقط پیامی چاپ می‌کند، چه type بازگشتی‌ای دارد؟ و تابعی که میانگین دو عدد را با اعشار برمی‌گرداند چطور؟

---

**جواب:** اولی `void` است (کاری می‌کند ولی محصولی برنمی‌گرداند). دومی `float` است (چون جوابش اعشاری است). یادت باشد اگر داخلش دو `int` را تقسیم کنی، باید یک طرف را اعشاری کنی وگرنه جواب گرد می‌شود!

## ۳. آرایه: قفسه‌ی بتنی

لیست Python یادت هست؟ قفسه‌ای که هر وقت می‌خواستی با `append` خانه‌ی جدید می‌ساختی و هر جنسی هم تویش جا می‌شد. نسخه‌ی C++ اش **آرایه** (Array) است — همان قفسه، ولی از بتن: تعداد خانه‌ها را موقع ساختن اعلام می‌کنی و دیگر تغییری در کار نیست، و همه‌ی خانه‌ها هم باید یک جنس باشند:

</div>

```cpp
int steps[4] = {25, 50, 75, 100};    // ghafase-ye 4 khane az jens-e int

for (int i = 0; i < 4; i++) {
  Serial.println(steps[i]);
}
```

<div dir="rtl">

شکل خواندنش عین Python است: `steps[0]` می‌شود ۲۵، `steps[3]` می‌شود ۱۰۰ — شماره‌گذاری از صفر، همان قانون قدیمی. حلقه‌ی `for` هم که تازه یاد گرفتی، جفتِ همیشگی آرایه است. تا اینجا آشناست. ولی حالا مهم‌ترین فرقش — و این یکی را باید با چشم ببینی. در Python اگر از قفسه‌ی چهارخانه‌ای خانه‌ی هشتم را می‌خواستی، چه می‌شد؟ `IndexError` — یک راهنمای مهربان که می‌گفت «چنین خانه‌ای نیست». حالا همین را از C++ بخواه:

</div>

```cpp
Serial.println(steps[7]);    // khane-i ke vojood nadarad!
```

<div dir="rtl">

compile می‌زنی... **ساخته می‌شود.** اجرا... و Serial Monitor یک عدد چاپ می‌کند — یک عدد بی‌معنی، شاید صفر و شاید خیلی بزرگ، که با هر تغییر برنامه هم می‌تواند فرق کند! چه خبر است؟ C++ بدون هیچ سؤالی رفت سراغ جایی از حافظه که «اگر خانه‌ی هشتم وجود داشت آنجا بود» و هر آشغالی آنجا بود را برایت آورد. هیچ‌چیز جلویش را نگرفت و برنامه لحظه‌ی اجرا حتی مکث هم نکرد — **سکوت**. این خطرناک‌ترین عادت C++ است و اسم رسمی هم دارد: خواندنِ خارج از محدوده. در بدترین حالت حتی می‌تواند برنامه را ریست کند.

یک نکته‌ی صادقانه هم بگویم: چون اینجا شماره‌ی خانه یک عددِ ثابت (`7`) است و کامپایلر اندازه‌ی آرایه را می‌داند، اگر warnings را فصل قبل روی All گذاشته باشی ممکن است یک **هشدار** هم بگیری — چیزی شبیه `array subscript 7 is above array bounds`. هشدار، نه خطا: برنامه باز هم ساخته و اجرا می‌شود. و مهم‌تر: کافی است شماره‌ی خانه از یک متغیر بیاید (`int j = 7; steps[j];`) تا کامپایلر هم دیگر نتواند حدس بزند و سکوت **کامل** شود. باگ‌های واقعی هم دقیقاً از همین شکل دوم می‌آیند، نه از عدد ثابت.

![دو قفسه در مقایسه: قفسه‌ی بالا «Python list» کش‌دار و مهربان با ربات نگهبانی که با تابلوی IndexError جلوی دست را می‌گیرد؛ قفسه‌ی پایین «C++ array» بتنی با چهار خانه‌ی شماره‌دار، و پشت لبه‌اش منطقه‌ی مه‌آلودِ حافظه با عددهای آشغال که دست به خانه‌ی خیالیِ هفتمِ ناموجود می‌رسد](/lesson-assets/t5-s03-cpp-functions-speed/prompt/03-image-array-fixed-shelf.png)

> ⚠️ **مواظب باش:** قانونِ آهنیِ آرایه از امروز: **شرط حلقه و اندازه‌ی آرایه، همیشه با هم و همیشه هم‌قد.** هر وقت اندازه‌ی آرایه را عوض کردی، همان لحظه شرط `for` را هم عوض کن.

حالا کد کامل نیمه‌ی اول این فصل (حلقه، تابع، آرایه) در فایل `cpp_toolbox.ino` این است:

</div>

```cpp
// Term 5 - Session 03 - jabe-abzar-e C++: for, tabe ba type, araye
// darsad (0..100) -> duty (0..1023)
int percentToDuty(int percent) {
  return percent * 1023 / 100;    // zarb aval, taghsim bad! (dam-e taghsim-e sahih)
}

int steps[4] = {25, 50, 75, 100};    // ghafase-ye 4 khane az jens-e int

void setup() {
  Serial.begin(115200);
  delay(2000);

  // 1) for-e se ghesmati
  for (int i = 1; i <= 5; i = i + 1) {
    Serial.println(i);
  }
  Serial.println("payan!");

  // 2) tabe ba type-e bazgashti
  Serial.println(percentToDuty(50));    // 511

  // 3) araye + for (joft-e hamishegi)
  for (int i = 0; i < 4; i++) {
    Serial.println(steps[i]);
  }
}

void loop() {
}
```

<div dir="rtl">

> 🧪 **آزمایشگاه:** نیمه‌ی اول این فصل — حلقه، تابع و آرایه — در [آزمایشگاه خودمان](/lab) هم کاملاً قابل تمرین است؛ همین کد را آن‌جا اجرا کن و خروجی را در کنسول Serial ببین. دموی `steps[7]` را هم همان‌جا امتحان کن. اگر برد و کابل جلوی دستت است، همین کار را در Arduino IDE هم بکن — یک بار دیدنِ عددِ آشغال روی سخت‌افزار واقعی می‌ارزد.

## چالش: سه فرق آرایه با لیست

سه فرق آرایه‌ی C++ با لیست Python چه بود؟ کدامش از همه خطرناک‌تر است و چرا؟

---

**جواب:** ۱) اندازه‌اش ثابت است (نمی‌شود مثل `append` بزرگش کرد)؛ ۲) همه‌ی خانه‌ها باید یک جنس باشند؛ ۳) اگر خانه‌ی خارج از محدوده را بخوانی، برنامه نمی‌ایستد و عددِ آشغال برمی‌گرداند. سومی از همه خطرناک‌تر است، چون **بی‌صدا** است — به‌خصوص وقتی شماره‌ی خانه از یک متغیر بیاید، که آن‌وقت حتی هشدار کامپایلر هم در کار نیست و پیدا کردنش سخت می‌شود.

## ۴. مسابقه‌ی بزرگ: یک برد، دو زبان، یک ثانیه

رسیدیم به لحظه‌ی موعود. قانون مسابقه ساده و عادلانه است: هر زبان **یک ثانیه** وقت دارد و در این یک ثانیه فقط دو کار می‌کند — به کرنومتر نگاه می‌کند و می‌شمارد. هر که بیشتر شمرد، سریع‌تر است. برای این کار یک کرنومتر میلی‌ثانیه‌ای در هر دو زبان لازم داریم:

- در MicroPython: `time.ticks_ms()` می‌گوید «الان چند میلی‌ثانیه از روشن شدن برد گذشته»، و `time.ticks_diff(a, b)` فاصله‌ی دو لحظه را حساب می‌کند.
- در C++: `millis()` — همان حرف، یک کلمه.

برد از فصل قبل آردوینویی است، ولی احترام قهرمان فعلی واجب است: اول MicroPython می‌دود. Thonny را باز کن و مثل ترم ۱، فصل ۴ فریمور MicroPython را فلش کن. حالا دونده‌ی اول (فایل `speed_test.py`):

</div>

```python
# Term 5 - Session 03 - mosabeghe-ye sorat: davande-ye MicroPython
import time

count = 0
start = time.ticks_ms()      # kornometr ra bezan!
while time.ticks_diff(time.ticks_ms(), start) < 1000:
    count = count + 1        # yek dor-e dige

print(f"MicroPython: {count} dor dar 1 sanie")
```

<div dir="rtl">

اجرا کن — و عدد می‌آید. عدد دقیق را عمداً نمی‌نویسم، چون نسخه به نسخه فرق می‌کند؛ ولی همین‌قدر بگویم: چند صد هزار دور. روی کاغذ یادداشتش کن. حالا دونده‌ی دوم — همان دو کار، همان یک ثانیه، فقط به C++. برگرد به Arduino IDE و این را upload کن (فایل `speed_test.ino`):

</div>

```cpp
// Term 5 - Session 03 - mosabeghe-ye sorat: davande-ye C++
void setup() {
  Serial.begin(115200);
  delay(2000);                       // forsat bede Serial Monitor baz shavad

  long count = 0;                    // jabe-ye int-e bozorg - in adad ja mikhahad!
  unsigned long start = millis();    // kornometr ra bezan!
  while (millis() - start < 1000) {
    count = count + 1;               // yek dor-e dige
  }

  Serial.print("C++: ");
  Serial.print(count);
  Serial.println(" dor dar 1 sanie");
}

void loop() {
  // mosabeghe yekbar bas ast
}
```

<div dir="rtl">

دو نکته‌ی ریز کد. یک: مسابقه را در `setup` گذاشتیم چون می‌خواهیم فقط یک بار بدود — بالاخره یک جا `setup` قهرمان شد! دو: برای شمارنده به‌جای `int` نوشتیم `long`. `long` جعبه‌ای است که قانوناً هیچ‌وقت از `int` کوچک‌تر نیست، و روی بردهای کوچک‌ترِ خانواده‌ی Arduino واقعاً بزرگ‌تر هم هست. ولی صادق باشیم: **روی ESP32 این دو جعبه هم‌اندازه‌اند** و شمارشِ امروز در هر دو جا می‌شود. پس `long` اینجا یک عادتِ امن است، نه یک ضرورت — عادتی که همین کد را روی بردهای دیگر هم سالم نگه می‌دارد.

upload، Serial Monitor... و عدد را ببین. کنار عدد قبلی یادداشتش کن و نسبت را حساب کن: عدد C++ **چند ده برابرِ** عدد MicroPython درمی‌آید. عددِ تو دقیقاً عددِ من نمی‌شود — نسخه‌ی فریمور و هسته و حتی تنظیم‌های برد رویش اثر می‌گذارند؛ چیزی که مهم است بزرگیِ فاصله است، نه رقمِ دقیق. همان برد، همان سیم، همان یک ثانیه — فقط زبان عوض شد.

چرا؟ جواب را از فصل اول می‌دانی: دونده‌ی اول وسط دویدن، هر قدمش را اول برای مترجمِ همزمان تعریف می‌کرد؛ دونده‌ی دوم کتابِ ترجمه‌شده بود — فقط دوید. حالا سؤال مهندسی: این سرعت به چه دردی می‌خورد؟ همه‌جا؟ نه! ساعت اینترنتی ترم ۴ دقیقه‌ای یک درخواست می‌فرستاد — آنجا سرعتِ حلقه هیچ اهمیتی نداشت و MicroPython انتخابِ کاملاً درستی بود. ولی جایی که مغز ربات باید ده‌ها یا صدها بار در ثانیه بخواند-حساب‌کند-فرمان‌بدهد — مثل دنبال‌کننده‌ی خطی که فصل بعد با PID می‌سازیم — آنجا هر دورِ اضافه‌ی حلقه یعنی واکنش نرم‌تر. زبان، ابزار است؛ مهندس ابزارِ درستِ هر کار را برمی‌دارد.

> 💡 **نکته:** این مسابقه فقط روی برد واقعی معنا دارد. در شبیه‌ساز، سرعت به کامپیوتر تو بستگی دارد نه به تراشه — پس عددهای شبیه‌ساز معتبر نیستند.

## چالش: چرا مسابقه عادلانه بود؟

هر دو دونده در هر دور دقیقاً چه دو کاری می‌کردند؟

---

**جواب:** هر دو فقط دو کار می‌کردند: به کرنومتر نگاه می‌کردند (شرطِ «هنوز یک ثانیه نشده؟») و یکی به شمارنده اضافه می‌کردند. کارِ هر دور دقیقاً یکی بود، پس تنها چیزی که فرق داشت زبان بود — برای همین مسابقه عادلانه است.

## ۵. موتورها به C++ می‌رسند: ledc

حالا که می‌دانیم C++ برای کنترلِ تند و تیز ساخته شده، بیا مهم‌ترین مهارت ربات — چرخاندن موتور — را ترجمه کنیم. سیم‌کشی همان ترم ۳ است و دست نمی‌خورد (تصویر ابتدای فصل را جلوی چشمت بگذار): موتور روی درایور L298N، جهتش با IN1 روی GPIO 26 و IN2 روی GPIO 27، سرعتش با ENA روی GPIO 32؛ باتری سر جایش، GND مشترک وصل، ربات روی پایه. اول یادمان بیاید در MicroPython چه می‌کردیم:

</div>

```python
# yadavari-ye term 3 (MicroPython)
from machine import Pin, PWM

in1 = Pin(26, Pin.OUT)
in2 = Pin(27, Pin.OUT)
ena = PWM(Pin(32), freq=1000)

in1.value(1)      # jahat: jolo
in2.value(0)
ena.duty(700)     # sorat: 700 az 1023
```

<div dir="rtl">

جهت که ترجمه‌اش را بلدی: `pinMode` و `digitalWrite`. اما PWM چطور؟ در دنیای Arduino روی ESP32، سیستم PWM اسمش **ledc** است — «اِل‌ای‌دی-سی» — اسمش از LED آمده چون اول برای نور ساخته شده بود، ولی همان PWM همیشگی است و برای موتور هم همان کار را می‌کند. دو قدم دارد، درست مثل MicroPython:

</div>

```cpp
const int ENA = 32;    // sorat (PWM)
const int IN1 = 26;    // jahat
const int IN2 = 27;

void setup() {
  pinMode(IN1, OUTPUT);
  pinMode(IN2, OUTPUT);
  ledcAttach(ENA, 1000, 10);   // pin, frekans 1000Hz, deghat 10 bit -> 0..1023

  digitalWrite(IN1, HIGH);     // jahat: jolo (mesle in1.value(1))
  digitalWrite(IN2, LOW);
  ledcWrite(ENA, 700);         // sorat: 700 az 1023 - hamun duty-e term 3!
}

void loop() {
}
```

<div dir="rtl">

خط `ledcAttach(ENA, 1000, 10)` معادل `PWM(Pin(32), freq=1000)` است: به پایه‌ی ENA یک موتورِ PWM با فرکانس ۱۰۰۰ هرتز بچسبان. آن عدد `10` هم یعنی «دقت ۱۰ بیتی» — ترجمه‌اش به زبان ما: بازه‌ی سرعت از `0` تا `1023` باشد، **دقیقاً همان بازه‌ی duty که از ترم ۲ با آن فکر می‌کنی**. و `ledcWrite(ENA, 700)` همان `ena.duty(700)` است.

> ⚠️ **مواظب باش:** قوانین ایمنی ترم ۳ سر جایشان‌اند: ربات روی پایه و چرخ‌ها در هوا؛ GND باتری و برد و درایور همه یکی (GND مشترک)؛ باتری سالم و پر.

و یک نکته درباره‌ی جایی که این کد را می‌زنی:

> 🧪 **آزمایشگاه:** خبر خوب — همین برنامهٔ C++ را می‌توانی در [آزمایشگاه خودمان](/lab) اجرا کنی و پله‌های سرعت را روی LEDِ جای موتور ببینی (روشنایی‌اش از جریان واقعی محاسبه می‌شود). برای رباتِ واقعی، همین کد را در Arduino IDE بزن و روی رباتِ روی پایه upload کن. (اگر کامپایلر گفت `ledcAttach` را نمی‌شناسد، نسخه‌ی هسته‌ی ESP32 قدیمی است — از Boards Manager به‌روزش کن.)

## چالش: سه عددِ ledcAttach

در `ledcAttach(ENA, 1000, 10)` هر کدام از سه عدد چه‌کاره‌اند؟

---

**جواب:** `ENA` پایه‌ای است که موتورِ PWM به آن می‌چسبد (GPIO 32)؛ `1000` فرکانس است (۱۰۰۰ هرتز)؛ `10` دقتِ ۱۰ بیتی است که بازه‌ی سرعت را `0` تا `1023` می‌کند — همان بازه‌ی duty ترم ۳.

## ۶. پروژه‌ی اصلی: پله‌های سرعت

حالا همه‌ی ابزار امروز — تابع، آرایه، حلقه، ledc — را در یک برنامه‌ی تمیز سوار هم کنیم: موتوری که مثل تعویض دنده‌ی ماشین، پله‌پله سرعت می‌گیرد. کد کامل، فایل `motor_stairs.ino`:

</div>

```cpp
// Term 5 - Session 03 - pelle-haye sorat: tabe + araye + for + ledc
// sim-keshi-e term 3: ENA=GPIO 32, IN1=GPIO 26, IN2=GPIO 27 (motor-e chap)
// robot rooye paye - charkh-ha dar hava! battery + GND-e moshtarak (ghavanin-e term 3)
const int ENA = 32;    // sorat (PWM)
const int IN1 = 26;    // jahat
const int IN2 = 27;

// darsad (0..100) -> duty (0..1023)
int percentToDuty(int percent) {
  return percent * 1023 / 100;
}

void motorForward(int percent) {
  digitalWrite(IN1, HIGH);
  digitalWrite(IN2, LOW);
  ledcWrite(ENA, percentToDuty(percent));
}

void motorStop() {
  ledcWrite(ENA, 0);
}

int steps[4] = {30, 50, 75, 100};    // pelle-haye sorat (darsad) - zir-e astane, motor rah nemioftad

void setup() {
  pinMode(IN1, OUTPUT);
  pinMode(IN2, OUTPUT);
  ledcAttach(ENA, 1000, 10);   // pin, frekans 1000Hz, deghat 10 bit -> 0..1023
  Serial.begin(115200);
}

void loop() {
  for (int i = 0; i < 4; i++) {
    Serial.println(steps[i]);
    motorForward(steps[i]);
    delay(2000);
  }
  motorStop();
  delay(3000);
}
```

<div dir="rtl">

ببین چقدر شبیه `robot.py` خودمان شده: تابع‌های تمیز با اسم‌های آشنا — فقط این بار هر کدام برچسب type دارند. `motorForward` تابع `void` است (کاری می‌کند، محصولی نمی‌دهد) ولی درونش از کارخانه‌ی `int` دارِ `percentToDuty` جنس می‌گیرد. آرایه‌ی پله‌ها را از ۳۰ شروع کردیم نه ۲۵ — یادگاری ترم ۳: زیر یک آستانه، موتور فقط ویزویز می‌کند و راه نمی‌افتد.

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

> 🔧 **اگر کار نکرد:** موتور ویزویز می‌کند ولی نمی‌چرخد؟ duty زیر آستانه‌ی راه‌افتادن است یا باتری ضعیف — پله‌ی اول را ۳۰ درصد یا بالاتر بگذار و باتری‌ها را چک کن. موتور اصلاً کار نمی‌کند ولی Serial پیام می‌دهد؟ GND مشترک وصل نیست یا جامپر ENA سر جایش مانده: GND باتری و برد و درایور را یکی کن و جامپر ENA را بردار تا سیم PWM جای آن بنشیند.

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| for | فور | حلقه‌ی سه‌قسمتی C++: شروع؛ شرط ماندن؛ قدم |
| Array | اِرِی | قفسه‌ی بتنی: اندازه‌ی ثابت، یک جنس، شماره از صفر |
| Return type | ریتِرن تایپ | برچسب روی درِ کارخانه‌ی تابع: جنس محصول چیست |
| void | وُید | «هیچ» — تابعی که کاری می‌کند ولی محصولی برنمی‌گرداند |
| long | لانگ | جعبه‌ی عدد صحیحی که هیچ‌وقت از `int` کوچک‌تر نیست، برای عددهایی که خیلی بالا می‌روند |
| millis | میلیس | کرنومتر C++: چند میلی‌ثانیه از روشن شدن برد گذشته |
| ledc | اِل‌ای‌دی-سی | سیستم PWM در دنیای Arduino روی ESP32 |
| Benchmark | بِنچ‌مارک | آزمون اندازه‌گیری سرعت — همان مسابقه‌ی امروز |

## تمرین‌ها

اول چک‌لیست پایان فصل: حلقه‌ی `for` و تابع type دار و آرایه را می‌نویسی؛ آزمون سرعت را روی برد خودت اجرا و دو عدد را ثبت کرده‌ای؛ و پله‌های سرعت با موتور کار می‌کند. اگر همه بله است:

- **تمرین اجباری:** آزمون سرعت را خودت اجرا کن و در دفترچه‌ی مهندسی هر دو عدد و نسبتشان را ثبت کن. بعد تابع `int dutyToPercent(int duty)` — معکوس کارخانه‌ی امروز — را بنویس و با سه مقدار آزمایش کن (`toolbox_homework.ino`). حواست به ترتیب ضرب و تقسیم باشد؛ اگر جواب‌ها صفر شدند، خودت می‌دانی مقصر کیست!
- **تمرین ستاره‌دار ⭐:** «دنده‌ی معکوس»: تابع `motorBack(int percent)` را خودت بنویس (فقط جای HIGH و LOW در IN1 و IN2 عوض می‌شود) و یک «رقص» سه‌مرحله‌ای بساز: دو ثانیه جلو، توقف کوتاه، دو ثانیه عقب. توقف بین تغییر جهت را جدی بگیر — به موتور و درایور استراحت بده، همان ادب ترم ۳. اگر به آرایه‌ی پله‌ها خانه‌ی جدید اضافه کردی، یادت نرود **دو جا** باید عدد عوض شود (اندازه‌ی آرایه و شرط `for`)، وگرنه با «سکوت خطرناک» روبه‌رو می‌شوی!

## در فصل بعد

جعبه‌ابزار C++ ات کامل شد و مسابقه‌ی بزرگ را هم با چشم دیدی. حالا بگذار بگویم این سرعت را کجا خرج می‌کنیم. یادت هست دنبال‌کننده‌ی خط ترم ۳ با کنترل P چطور بود؟ خوب بود، ولی روی پیچ‌های تند لبه‌ی خط می‌لرزید و گاهی از دستش می‌داد. فصل بعد دو حرف جدید به P اضافه می‌کنیم: **I** و **D** — و اسم کاملش را همه‌جای دنیای مهندسی می‌شناسند: **PID**. با مغز C++ ای که حالا صدها بار در ثانیه فکر می‌کند، ربات تو قرار است خط را مثل قطار روی ریل بگیرد. باتری‌ها را شارژ کن و زمینِ بازی ترم ۳ را پیدا کن — فصل بعد رباتت حرفه‌ای می‌شود.

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t5/s03-cpp-functions-speed (یادستان, Yaadestan)
