# فصل ۴ — کنترل PID برای دنبال‌کننده خط

<div dir="rtl">

# فصل ۴ — کنترل PID برای دنبال‌کننده خط

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

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

![دو پنل از یک ربات دنبال‌کننده‌ی خط روی پیچ سنجاقی از نمای بالا: پنل «ضریب کم» که ربات پیچ را گم می‌کند و مستقیم پرت می‌شود بیرون، و پنل «ضریب زیاد» که روی مستقیم زیگزاگِ بزرگ می‌زند؛ وسط دو پنل یک ولومِ بزرگ که یعنی یک ولوم نمی‌تواند هر دو مشکل را حل کند](/lesson-assets/t5-s04-pid-line-follower/prompt/01-image-p-limit-hairpin.png)

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

- توضیح بدهی چرا کنترل P تنها در پیچ تند کم می‌آورد: یک ضریب، دو مشکل مخالف.
- نقش **I** (جبران خطای انباشته‌ی گذشته) و **D** (ترمز پیش‌بینانه بر اساس سرعت تغییر) را با مثال ملموس توضیح بدهی و هر دو را در C++ پیاده کنی.
- **پروتکل تنظیم گام‌به‌گام** را اجرا کنی: اول `KP`، بعد `KD` کوچک، بعد `KI` خیلی کوچک.
- علائم زیاده‌روی هر حرف را تشخیص بدهی: تابِ بزرگ، رعشه‌ی ریز، تابِ آهسته‌ی کش‌دار.
- بگویی چرا حافظه‌ای که باید بین ضربان‌های `loop` زنده بماند، باید بیرون از `loop` تعریف شود.

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

- **از فصل‌های ۱ تا ۳:** جعبه‌ابزار C++ — نصب Arduino IDE و upload، `setup`/`loop`، type ها و سمی‌کالن و آکولاد، `Serial.println`، تعریف تابع با type، آرایه، کرنومترِ `millis` و PWM با `ledcAttach`/`ledcWrite`.
- **از ترم ۳، فصل ۹:** کنترل P، جدول error (از ۲- تا ۲+)، تابع `tank` و `clamp`. امروز همه به C++ مهاجرت می‌کنند.
- **از ترم ۳، فصل ۸:** پیست خانگی، نوار عرضیِ پایان، منطق خط گم‌شده.
- **از ترم ۳، فصل ۷:** سه سنسور خط کالیبره روی پایه‌های 34/35/36 و ثابت `BLACK`.
- **از ترم ۳، فصل ۴:** ضریب‌های تصحیح `FACTOR` — در فرمول‌های امروز هم حضور دارند.

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

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ربات کامل ترم ۳ (شاسی + L298N + سه سنسور خط) | ۱ | — |
| پیست فصل ۸ ترم ۳ + نوار چسب برای یک پیچ سنجاقی جدید | ۱ | هر کف روشن + نوار برق مشکی |
| باتری پر | ۱ دست | تنظیم PID با باتری ضعیف بی‌معنی است |
| کامپیوتر با Arduino IDE (فصل ۱) + کابل USB | ۱ | — |
| کرنومتر (گوشی) و دفترچه مهندسی | ۱ | ساعت + هر دفتری |

## ۱. اسکلت C++: ماژول ترم ۳ مهاجرت می‌کند

سه فصل است C++ می‌نویسیم، ولی همیشه روی Breadboard. امروز اولین بار است که C++ سوار ربات می‌شود. چیزی را که لازم داریم از قبل داریم — فقط به زبان دیگر: `robot.py` ترم ۳ با `tank` و `clamp`. بیا ترجمه‌اش کنیم؛ به تفاوت‌ها دقت کن:

</div>

```cpp
const int ENA = 32;
const int IN1 = 26;
const int IN2 = 27;
const int IN3 = 14;
const int IN4 = 25;
const int ENB = 33;

const float FACTOR_LEFT = 0.94;
const float FACTOR_RIGHT = 1.0;

float clampF(float value, float low, float high) {
  if (value < low) {
    return low;
  }
  if (value > high) {
    return high;
  }
  return value;
}

void tank(float left, float right) {
  digitalWrite(IN1, HIGH);
  digitalWrite(IN2, LOW);
  digitalWrite(IN3, HIGH);
  digitalWrite(IN4, LOW);
  ledcWrite(ENA, clampF(left * FACTOR_LEFT, 0, 1023));
  ledcWrite(ENB, clampF(right * FACTOR_RIGHT, 0, 1023));
}
```

<div dir="rtl">

همان پین‌مپ همیشگی: ENA=32، IN1=26، IN2=27، IN3=14، IN4=25، ENB=33. کلمه‌ی `const` جلوی متغیر یعنی «قول می‌دهم عوضش نکنم» — برای پین‌ها و عددهای تنظیم عالی است. در `setup` هم دو خط `ledcAttach(ENA, 1000, 10)` و `ledcAttach(ENB, 1000, 10)` می‌گذاریم — همان PWM آشنای فصل قبل، و دقت کن: رزولوشن را ۱۰ بیت گرفتیم، یعنی duty از `0` تا `1023` — **دقیقاً همان بازه‌ی ترم ۳!** همه‌ی عددهای قدیمی‌ات — `BASE = 550`، ضریب‌ها — بدون تغییر معتبرند.

یک نکته‌ی شیرین هم همین‌جاست: ترم ۳ یادت هست `duty` با عدد اعشاری چه خطایی می‌داد؟ `TypeError: can't convert float to int`. C++ اینجا اصلاً غر نمی‌زند — `float` را بی‌سروصدا به عدد صحیح تبدیل می‌کند و رد می‌شود. راحت است، ولی حواس‌جمعی می‌خواهد: خطایی که گرفته نشود، بی‌صدا هم می‌تواند نیش بزند. تابع `errorFrom` را هم عین جدول ترم ۳ می‌نویسیم — پنج حالت، از ۲- تا ۲+. فقط دو واژه‌ی ترجمه‌ایِ جدید لازم دارد: `and`ِ پایتون در C++ می‌شود `&&` و `not` می‌شود `!` — همان منطق ترم ۱، با لباس جدید.

## چالش: رزولوشن ۱۰ بیت چه می‌دهد؟

`ledcAttach` با رزولوشن ۱۰ بیت چه بازه‌ای به ما می‌دهد و چرا این انتخاب، عددهای ترم ۳ را نجات داد؟

---

**جواب:** بازه‌ی `0` تا `1023`. چون این دقیقاً همان بازه‌ی duty ترم ۳ است، همه‌ی عددهای قدیمی‌ات (BASE، ضریب‌ها، سرعت‌ها) بدون هیچ تبدیلی معتبر می‌مانند — لازم نیست جدول تبدیل تازه‌ای در ذهنت بسازی.

## ۲. بن‌بست P: یک ولوم، دو مشکل مخالف

حلقه‌ی P را مثل ترم ۳ سر هم می‌کنیم — `diff = KP * error` و `tank(BASE + diff, BASE - diff)` — و با `KP = 60` که عدد خوبِ ترم ۳ بود، روی پیست جدید اجرا می‌کنیم: مستقیم عالی... پیچ سنجاقی: بیرون! خب، نسخه‌ی قدیمی درس را بلدیم: `KP` را زیاد کن. با `KP = 150` این بار پیچ سنجاقی را می‌گیرد! جشن؟ نه — به مستقیم که می‌رسد نگاه کن: چپ‌راست، چپ‌راست، تابِ بزرگ... همان نوسانِ آشنا (تصویر ابتدای فصل را ببین).

این را در دفترچه‌ات بنویس چون قلب امروز است: **یک ولوم داریم و دو مشکلِ مخالف.** ولوم کم: پیچ تند گم می‌شود. ولوم زیاد: مستقیم می‌لرزد. هرچه بچرخانی، فقط جای درد را عوض می‌کنی. چرا؟ چون P فقط **الان** را می‌بیند: همین لحظه error چند است، ضربدر ضریب، تمام. نه یادش هست چند ثانیه است که یک‌وری می‌رود (**گذشته**)، نه می‌فهمد error با چه سرعتی دارد عوض می‌شود (**آینده‌ی نزدیک**). دو دستیار جدید دقیقاً همین دو تکه‌ی زمان را به تیم می‌آورند: **D** نگهبانِ آینده است و **I** حسابدارِ گذشته. اول سراغ D می‌رویم، چون دردِ فوری‌مان — نوسان — را او درمان می‌کند.

## چالش: چرا هیچ‌کدام کافی نبود؟

چرا «`KP` را بیشتر کن» و «`KP` را کمتر کن» هیچ‌کدام به تنهایی پیست سنجاقی را حل نکردند؟

---

**جواب:** چون یک ولوم دو مشکلِ مخالف دارد: `KP` کم پیچ تند را گم می‌کند و `KP` زیاد مستقیم را می‌لرزاند. هر طرف که بچرخانی یکی بهتر و آن یکی بدتر می‌شود؛ P فقط «الان» را می‌بیند و به گذشته و آینده کاری ندارد.

## ۳. D: ترمز پیش‌بینانه

تصور کن با دوچرخه در جاده‌ای — چشمت کجاست؟ به جلوی جاده، نه به زیر چرخ! وقتی می‌بینی داری «سریع» به سمت لبه‌ی جاده می‌روی، قبل از رسیدن فرمان را برمی‌گردانی؛ و وقتی داری به وسط برمی‌گردی، فرمان را **شل می‌کنی** که از آن‌طرف نزنی بیرون. تو به «جای فعلی» واکنش نشان نمی‌دهی — به «**سرعتِ تغییر**» واکنش نشان می‌دهی. این دقیقاً حرف D است — Derivative، یعنی مشتق، و نترس: برای ما فقط یک تفریق است!

</div>

```cpp
float derivative = error - lastError;
```

<div dir="rtl">

errorِ الان منهای errorِ ضربانِ قبل. اگر error دارد بزرگ می‌شود (داریم فرار می‌کنیم)، derivative مثبت است و D به فرمانِ P اضافه می‌کند — واکنشِ زودتر. اگر error دارد کوچک می‌شود (داریم به خط برمی‌گردیم)، derivative منفی است و D از فرمان **کم** می‌کند — ترمز، قبل از ردشدن از خط! و اگر error ثابت است؟ derivative صفر — D ساکت. به همین دلیل بهش می‌گوییم «ترمز پیش‌بینانه».

![دو پنل از دوچرخه‌سواری روی جاده‌ی پیچ‌دار: پنل «نگاه به پایین» که سوار به چرخ خیره شده و رد زیگزاگِ قرمز پشتش است و در پیچ غافلگیر می‌شود؛ پنل «نگاه به جلو» که سوار مخروط دیدش را به پیچِ پیشِ رو دوخته، زودتر ترمز می‌گیرد و ردِ سبزِ نرمی از پیچ می‌گذرد](/lesson-assets/t5-s04-pid-line-follower/prompt/04-image-d-lookahead-brake.png)

فرمول کامل این می‌شود: `float diff = KP * error + KD * derivative;` و بعد `tank(BASE + diff, BASE - diff);`. تایپ می‌کنی، دکمه‌ی تیکِ کامپایل... و اوپس:

</div>

```text
error: expected ';' before 'float'
   57 |   lastError = error
      |                    ^
      |                    ;
   58 |   float diff = KP * error + KD * derivative;
      |   ~~~~~
```

<div dir="rtl">

آشنای این ترم: `expected ';'` یعنی یک سمی‌کالن جا مانده — و نکته‌ی طلایی: کلمه‌ای که پیام می‌گوید (`float` در خط ۵۸) مال خط **بعد از** جرم است، چون کامپایلر تازه آنجا می‌فهمد جمله تمام نشده. کامپایلر با علامت `^` جای خالی را هم نشان می‌دهد: خط ۵۷، `lastError = error` بدون سمی‌کالن. اضافه می‌کنی، کامپایل سبز. و خوبیِ C++: همه‌ی این خطاها **قبل از اجرا** گرفته می‌شوند، نه وسط پیست!

حالا `lastError` را کجا تعریف کنیم؟ مغزِ پایتونی‌ات می‌گوید همان نزدیکی، داخل `loop`: `float lastError = 0.0;` و بعدش تفریق. upload، اجرا با `KD = 600`... و هیچ آرامشی در کار نیست — انگار D اصلاً استخدام نشده، حتی عصبی‌تر! خطایی هم در کار نیست: یک **باگ بی‌صدا**، از همان‌ها که ترم ۳ یاد گرفتیم با چاپ‌کردن شکارشان کنیم. `Serial.println(derivative)` می‌گذاری و نگاه می‌کنی: derivative هر بار **دقیقاً مساوی خود error** است، انگار lastError همیشه صفر است... و واقعاً هم همیشه صفر است!

متغیری که **داخل** `loop` تعریف شود، با هر ضربان از نو متولد می‌شود و ته همان ضربان می‌میرد — مثل تخته‌سیاهی که آخر هر کلاس پاک می‌شود. `loop` هم یک تابع است و متغیرِ داخلِ تابع همین سرنوشت را دارد! حافظه‌ای که باید بین ضربان‌ها زنده بماند، باید **بیرون از `loop`** — بالای فایل — زندگی کند. `float lastError = 0.0;` را می‌بری بالا، کنار ثابت‌ها. اجرا: حالا تابِ بزرگِ مستقیم... آرام شد. `KP = 150` مانده و لرزش رفته — یعنی پیچ سنجاقی **و** مستقیمِ آرام، با هم!

## چالش: derivative چند است؟

error از ۲+ به ۱+ برگشته. derivative چند است؟ D فرمان را سفت‌تر می‌کند یا شل‌تر — و چه ربطی به دوچرخه‌سواری دارد؟

---

**جواب:** derivative = ۱ منهای ۲ = **۱-** (منفی). یعنی error دارد کوچک می‌شود (به خط برمی‌گردیم)، پس D فرمان را **شل** می‌کند — مثل شل کردن فرمان دوچرخه وقتی داری به وسط جاده برمی‌گردی، که از آن‌طرف نزنی بیرون.

## ۴. I: ماشینِ گیرکرده در گل

یک آزمایش شیطانی: فرض کن یکی از موتورها خسته شده — شبیه‌سازی‌اش ساده است، `FACTOR_RIGHT` را عمداً از ۱٫۰ به ۰٫۸۵ خراب کن. اجرا: ربات نمی‌افتد، P هوایش را دارد... ولی زوم کن: دیگر وسط خط نیست — همیشه **کمی یک‌وری** می‌راند و داشبورد `error` بیشتر وقت‌ها ۱- نشان می‌دهد. چرا P درستش نمی‌کند؟ چون P فقط وقتی زور می‌زند که error هست: اگر error صفر شود، فرمانِ اصلاح هم صفر می‌شود و موتورِ ضعیف دوباره ربات را کج می‌کند. سیستم در یک «کجیِ پایدار» به تعادل رسیده — اسم مهندسی‌اش را هم یاد بگیر: **steady-state error**، خطای ماندگار.

حالا تشبیهی که این را برای همیشه در ذهنت حک می‌کند: ماشینی در گل گیر کرده. راننده گاز می‌دهد — زورِ ثابت — چرخ می‌چرخد و ماشین همان‌جا می‌ماند: این P است. دوستانش چه می‌کنند؟ هل می‌دهند، و هر ثانیه که ماشین درنیامده، **محکم‌تر** هل می‌دهند؛ زورشان جمع می‌شود و جمع می‌شود تا بالاخره — هوپ! — ماشین در می‌آید. این I است — Integral، یعنی جمعِ خطاهای گذشته:

</div>

```cpp
integral = integral + error;
float diff = KP * error + KI * integral + KD * derivative;
```

<div dir="rtl">

![نوار سه‌مرحله‌ای از ماشینی که در گل گیر کرده: مرحله‌ی t=1 دو نوجوان آرام هل می‌دهند، مرحله‌ی t=2 محکم‌تر هل می‌دهند و نوارِ «PUSH++» پر می‌شود، مرحله‌ی t=3 ماشین با برچسب «FREE!» بیرون می‌پرد؛ گوشه‌ی تصویر هشدارِ کوچکِ پرت‌شدنِ ماشین اگر بعد از آزاد شدن هنوز هل بدهند](/lesson-assets/t5-s04-pid-line-follower/prompt/03-image-i-stuck-car.png)

هر ضربان، error به «کیسه‌ی خاطره» اضافه می‌شود. تا وقتی کجیِ کوچک ادامه دارد، کیسه سنگین‌تر و فرمانِ اصلاح قوی‌تر می‌شود — و وقتی error صفر شد، کیسه دیگر سنگین نمی‌شود و همان زورِ ذخیره‌شده، موتورِ ضعیف را جبران می‌کند. البته `integral` هم مثل `lastError` باید بیرون از `loop` زندگی کند — دیگر می‌دانیم چرا!

ولی صبر کن — تشبیه را تا ته برو: ماشین که از گل درآمد، اگر دوستانت هنوز با همان زورِ جمع‌شده هل بدهند چه می‌شود؟ ماشین پرت می‌شود جلو! این خطر واقعی I است و اسم دارد: **windup** — کیسه آن‌قدر پر شود که تخلیه‌اش کلی طول بکشد و ربات را به آن‌ورِ خط پرت کند. دو محافظ می‌گذاریم:

1. همان `clamp` خودمان روی کیسه: `integral = clampF(integral + error, -MAX_I, MAX_I)` — گیره که بیش از حد پر نشود.
2. هر وقت خط گم شد، کیسه را خالی می‌کنیم — `integral = 0.0` — چون خاطره‌های وضعیتِ قبلی برای وضعیت «گم‌شده» بی‌معنی‌اند.

حالا `KI` چقدر؟ خیلی کم — من ۰٫۴ می‌گذارم. اجرا با همان موتورِ «خسته»: چند لحظه اول همان کجی... و بعد، آرام‌آرام، ربات می‌خزد وسط خط و همان‌جا می‌ماند. error صفر، با موتور ناسالم! بعد `FACTOR_RIGHT` را به مقدار درستش برمی‌گردانم — I برای جبرانِ خرابی‌های پیش‌بینی‌نشده است، نه جایگزینِ کالیبراسیون.

## چالش: چرا کیسه را خالی می‌کنیم؟

چرا وقتی خط گم می‌شود `integral` را صفر می‌کنیم؟ و گیره‌ی `clamp` جلوی کدام خطر را می‌گیرد؟

---

**جواب:** وقتی خط گم می‌شود، خاطره‌های کجیِ قبلی دیگر به درد نمی‌خورند و اگر بمانند ربات را بعد از پیدا کردن خط کج پرت می‌کنند؛ پس کیسه را خالی می‌کنیم. گیره‌ی `clamp` جلوی **windup** را می‌گیرد: نمی‌گذارد کیسه آن‌قدر پر شود که تخلیه‌اش طول بکشد و ربات را به آن‌ورِ خط بیندازد.

## ۵. پروتکل تنظیم: اول P، بعد D کوچک، بعد I خیلی کوچک

سه ولوم داریم و بی‌نهایت ترکیب — اگر شانسی بچرخانی، تا آخر هفته اینجایی! مهندس‌ها پروتکل دارند و پروتکلِ ما سه گام دارد؛ در دفترچه‌ی مهندسی‌ات بنویس:

1. **فقط P:** با `KD = 0` و `KI = 0` شروع کن. `KP` را پله‌پله بالا ببر (هر بار حدود ۵۰٪) تا تندترین پیچِ پیستت را بگیرد — نوسانِ روی مستقیم را فعلاً تحمل کن؛ فقط اگر آن‌قدر شدید شد که ربات پرت شد، یک پله برگرد.
2. **D کوچک:** `KD` را از صفر پله‌پله بالا ببر تا نوسانِ مستقیم آرام شود. علامتِ زیاده‌روی: **رعشه‌ی ریزِ عصبی** — لرز تند و کوچک، فرقش با نوسانِ P (تابِ بزرگ) را با چشم می‌بینی.
3. **I خیلی کوچک:** فقط اگر ربات روی مستقیم یا قوس بلند «یک‌وری» می‌ماند، `KI` را با عددهای خیلی کوچک اضافه کن. علامت زیاده‌روی: تابِ **آهسته و کش‌دار** که کم‌کم بدتر می‌شود.

قانون طلایی که بالای جدولت بنویس: **هر بار فقط یک عدد را عوض کن، یک بار اجرا کن، یک ردیف ثبت کن.** اگر دو عدد را با هم عوض کنی و بهتر شود، هیچ‌وقت نمی‌فهمی کدام نجاتت داد. جدول علائم هم کنارش:

| حرف | خیلی کم | خیلی زیاد |
|---|---|---|
| `KP` | پیچ تند را گم می‌کند | تابِ بزرگ روی مستقیم |
| `KD` | نوسان P می‌ماند | رعشه‌ی ریز و عصبی |
| `KI` | کجیِ ماندگار می‌ماند | تابِ آهسته‌ی کش‌دار |

![فلوچارت عمودی با سه کارتِ شماره‌دار برای تنظیم کنترل‌کننده: کارت «گام ۱ - P» با ولوم بالا و آیکون پیچ سنجاقی و تیک، کارت «گام ۲ - D کوچک» با موجی که زیگزاگ را صاف می‌کند، کارت «گام ۳ - I خیلی کوچک» با رباتی که به مرکز کشیده می‌شود؛ هر کارت یک نشانِ قرمزِ «زیادی» با علامتِ زیاده‌رویِ خودش دارد، و نوارِ پایینی «یک تغییر در هر اجرا»](/lesson-assets/t5-s04-pid-line-follower/prompt/05-image-tuning-protocol-steps.png)

عددهای نهایی من: `KP = 150`، `KD = 600`، `KI = 0.4`. عددهای تو قطعاً فرق می‌کنند — موتور، باتری، پیست و حتی کف اتاقت در آن‌ها سهم دارند. عدد مقدس نیست؛ **پروتکل** مقدس است.

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

ربات روی مستقیم لرزِ تند و ریز دارد. کدام ولوم را و در کدام جهت می‌چرخانی؟

---

**جواب:** لرزِ تند و ریز علامتِ **زیاد بودنِ `KD`** است. پس `KD` را **کم** کن (نصفش کن و دوباره امتحان کن). اگر لرز، تابِ بزرگ بود نه ریز، آن‌وقت مشکل از `KP` زیاد بود.

## ۶. مسابقه: دیروز در برابر امروز، و دو زبان در برابر هم

وقت داوری است — با کرنومتر، نه با احساس! سه دورِ کامل با بهترین P تنها (که مجبوری برای نیفتادن در سنجاقی سرعت را کم کنی)، سه دور با PID کامل. زمان‌ها را در دفترچه بنویس. نتیجه: PID هم در هر دور سریع‌تر است، هم مسیرش تمیزتر — سنجاقی را با قوسِ نرم رد می‌کند و مستقیم را مثل تیر.

✅ **چک کن:** با PID کامل، ربات باید پیچ سنجاقی را با یک قوس نرم رد کند و روی مستقیم دیگر تابِ بزرگ نزند؛ و داشبورد در Serial Monitor باید «loop dar sanie» را نزدیک ۱۰۰ نشان بدهد.

> 🔧 **اگر کار نکرد:** چهار مشکلِ پرتکرار این فصل، به‌ترتیبِ شیوع:
> **۱) ربات با اولین انحراف فرار می‌کند** (به‌جای برگشتن، بدتر کج می‌شود): جای `+` و `-` در `tank(BASE + diff, BASE - diff)` برعکس شده. همان تست دستی ترم ۳ را بکن — خط زیر سنسور راست، چرخ چپ باید تندتر شود.
> **۲) D انگار اصلاً کار نمی‌کند:** `lastError` یا `integral` داخل `loop` تعریف شده. یک `Serial.println(derivative)` بگذار؛ اگر همیشه مساویِ خودِ error بود، تعریف‌ها را ببر بالای فایل.
> **۳) بعد از پیدا کردن دوباره‌ی خط، ربات شیرجه‌ی محکم می‌رود:** windup — گیره‌ی `MAX_I` و خطِ `integral = 0.0` در شاخه‌ی گم‌شدنِ خط را چک کن.
> **۴) وسط حرکت برد ریست می‌شود و پیام `Brownout detector was triggered` می‌آید:** باتری ضعیف است. PID با duty بالا جریان بیشتری می‌کشد؛ باتری پر بگذار، تغذیه را از مسیر L298N بگیر و زنجیره‌ی GND مشترک را سفت کن. با باتری ضعیف اصلاً تنظیم نکن — عددهایی که به دست می‌آوری فردا بی‌معنی‌اند.

و حالا سؤالی که از فصل اول این ترم منتظرش بودی: «همه‌ی این‌ها با MicroPython هم می‌شد؟» جواب صادقانه: منطقش صددرصد — و برای اثبات، همین PID را در فایل `pid_follower.py` به MicroPython هم نوشته‌ایم؛ خط‌به‌خط همین است، با `robot.py` ترم ۳. فرق کجاست؟ در هر دو نسخه یک «داشبورد ضربان» گذاشته‌ایم که هر ثانیه چاپ می‌کند `loop` چند بار زده — یادگارِ کرنومترِ فصل ۳. C++ ثابت و خونسرد نزدیک ۱۰۰ ضربان در ثانیه می‌زند (سقفش را خودمان با `delay(10)` گذاشته‌ایم و ریاضیِ PID تقریباً هیچ‌چیزی از بودجه‌ی ۱۰ میلی‌ثانیه‌ای نمی‌خورد). MicroPython همین منطق را با ضربانِ کمتر و ناهماهنگ‌تر می‌زند — خواندن سنسورها و حساب اعشاری، تکه‌ی محسوسی از بودجه را می‌جوَد. برای پیست ساده‌ی ترم ۳، هر دو زبان قهرمان‌اند؛ ولی سنجاقی + سرعت بالا + سه ولومِ حساس، یعنی هر میلی‌ثانیه می‌ارزد. درسِ مهندسی امروز: **زبان را پروژه انتخاب می‌کند، نه مُد.**

> ⚠️ **مواظب باش:** هر لحظه فقط یکی از Arduino IDE یا Thonny به برد وصل باشد — پورت USB یک صندلی دارد؛ اگر upload گیر کرد، اول چک کن برنامه‌ی دیگر پورت را نگه نداشته باشد.

کد کامل C++ این فصل، فایل `pid_follower.ino`:

</div>

```cpp
// Term 5 - Session 04 - donbal-konande-ye khat ba PID-e kamel
// P: javab be ALAN | I: jobran-e GOZASHTE | D: tormoz baraye AYANDE
// tartib-e tanzim: avval KP, bad KD-e kuchak, bad KI-e KHEYLI kuchak
// adad-ha male robot-e MAN hastand - adad-haye khodet ra ba protocol peyda kon!

// --- pin-ha: faghat az pin-map-e sabet-e dore ---
const int ENA = 32;   // sorat-e motor-e chap (PWM)
const int IN1 = 26;
const int IN2 = 27;
const int IN3 = 14;
const int IN4 = 25;
const int ENB = 33;   // sorat-e motor-e rast (PWM)

const int S_LEFT = 34;
const int S_MID = 35;
const int S_RIGHT = 36;

const int BLACK = 1;          // kalibrasion-e term 3: agar module-at barax bud 0 kon

// --- se voloom-e control ---
float KP = 150.0;             // ghadam-e 1: anghadr bala ke pich-e sanjaghi ra begirad
float KD = 600.0;             // ghadam-e 2: anghadr ke navasan-e mostaghim aram shavad
float KI = 0.4;               // ghadam-e 3: faghat agar robot yek-vari mimanad
const float MAX_I = 150.0;    // gire-ye kise-ye integral (zedd-e windup)

const int BASE = 550;         // sorat-e paye (0 ta 1023 - hamun range-ye term 3)
const int SEARCH_SPEED = 450; // charkhesh hangam-e jostojoo-ye khat-e gomshode
const int LOOP_MS = 10;       // zarban-e sabet: 100 bar dar sanie

// --- kalibrasion-e motor-ha (adad-haye term 3 jalase 4-e khodet) ---
const float FACTOR_LEFT = 0.94;
const float FACTOR_RIGHT = 1.0;

// --- hafeze-ye PID: bayad beyn-e zarban-haye loop zende bemanad -> birun az loop! ---
float integral = 0.0;
float lastError = 0.0;
bool finished = false;

// --- dashboard ---
long loopCount = 0;
unsigned long lastReport = 0;

void setup() {
  Serial.begin(115200);
  pinMode(IN1, OUTPUT);
  pinMode(IN2, OUTPUT);
  pinMode(IN3, OUTPUT);
  pinMode(IN4, OUTPUT);
  ledcAttach(ENA, 1000, 10);   // 10 bit -> duty az 0 ta 1023, mesl-e term 3
  ledcAttach(ENB, 1000, 10);
  pinMode(S_LEFT, INPUT);      // pin-haye 34/35/36 faghat-vorudi hastand
  pinMode(S_MID, INPUT);
  pinMode(S_RIGHT, INPUT);
  stopMotors();
  delay(2000);                 // 2 sanie vaght ke robot ra rooye khat bogzari
}

void loop() {
  if (finished) {
    return;                    // masir tamam shode - kari nadarim
  }

  bool l = (digitalRead(S_LEFT) == BLACK);
  bool m = (digitalRead(S_MID) == BLACK);
  bool r = (digitalRead(S_RIGHT) == BLACK);

  if (l && m && r) {
    // navar-e arzi-ye payan (term 3 jalase 8): halat-e khas avval!
    stopMotors();
    Serial.println("payan-e khat! zaman ra sabt kon.");
    finished = true;
    return;
  }

  if (!l && !m && !r) {
    // khat gom shod: kise-ye integral ra khali kon (windup!) va donbalash begard
    integral = 0.0;
    if (lastError > 0) {
      turnRight(SEARCH_SPEED);
    } else {
      turnLeft(SEARCH_SPEED);
    }
    delay(LOOP_MS);
    return;
  }

  float error = errorFrom(l, m, r);

  // --- ghalb-e PID: se harf, se hokm ---
  integral = clampF(integral + error, -MAX_I, MAX_I);  // I: kise-ye khatereh (ba gire)
  float derivative = error - lastError;                // D: sorat-e taghir-e khata
  lastError = error;

  float diff = KP * error + KI * integral + KD * derivative;
  tank(BASE + diff, BASE - diff);

  // --- dashboard: har sanie yek gozaresh ---
  loopCount = loopCount + 1;
  if (millis() - lastReport >= 1000) {
    Serial.print("error: ");
    Serial.print(error);
    Serial.print(" | loop dar sanie: ");
    Serial.println(loopCount);
    loopCount = 0;
    lastReport = millis();
  }

  delay(LOOP_MS);
}

int errorFrom(bool l, bool m, bool r) {
  // hamun jadval-e term 3 jalase 9: manfi = chap, mosbat = rast
  if (l && m) {
    return -1;
  }
  if (r && m) {
    return 1;
  }
  if (l) {
    return -2;
  }
  if (r) {
    return 2;
  }
  return 0;
}

float clampF(float value, float low, float high) {
  // hamun clamp-e term 3 - in bar ba type-haye C++
  if (value < low) {
    return low;
  }
  if (value > high) {
    return high;
  }
  return value;
}

void tank(float left, float right) {
  // har do charkh be jelo, har kodam ba sorat-e khodash
  digitalWrite(IN1, HIGH);
  digitalWrite(IN2, LOW);
  digitalWrite(IN3, HIGH);
  digitalWrite(IN4, LOW);
  ledcWrite(ENA, clampF(left * FACTOR_LEFT, 0, 1023));
  ledcWrite(ENB, clampF(right * FACTOR_RIGHT, 0, 1023));
}

void turnLeft(int speed) {
  digitalWrite(IN1, LOW);    // chap aghab
  digitalWrite(IN2, HIGH);
  digitalWrite(IN3, HIGH);   // rast jelo
  digitalWrite(IN4, LOW);
  ledcWrite(ENA, clampF(speed * FACTOR_LEFT, 0, 1023));
  ledcWrite(ENB, clampF(speed * FACTOR_RIGHT, 0, 1023));
}

void turnRight(int speed) {
  digitalWrite(IN1, HIGH);   // chap jelo
  digitalWrite(IN2, LOW);
  digitalWrite(IN3, LOW);    // rast aghab
  digitalWrite(IN4, HIGH);
  ledcWrite(ENA, clampF(speed * FACTOR_LEFT, 0, 1023));
  ledcWrite(ENB, clampF(speed * FACTOR_RIGHT, 0, 1023));
}

void stopMotors() {
  ledcWrite(ENA, 0);
  ledcWrite(ENB, 0);
  digitalWrite(IN1, LOW);
  digitalWrite(IN2, LOW);
  digitalWrite(IN3, LOW);
  digitalWrite(IN4, LOW);
}
```

<div dir="rtl">

و همان منطق در MicroPython — فایل `pid_follower.py` — برای مقایسه‌ی زنده‌ی دو زبان (نسخه‌ی `robot.py` ترم ۳، فصل ۹ با `tank` و `clamp` باید روی برد باشد. برد الان آردوینویی است، پس اول فریمور MicroPython را مثل فصل ۱ برگردان و `robot.py` را دوباره روی برد ذخیره کن، چون فلش‌کردن فایل‌های قبلی را پاک می‌کند):

</div>

```python
# Term 5 - Session 04 - hamun PID dar MicroPython (baraye moghayese-ye do zaban)
# mantegh khat-be-khat hamun pid_follower.ino ast
# robot.py-e term 3 jalase 9 (ba tank va clamp) bayad rooye board bashad!
from machine import Pin
import robot
import time

s_left = Pin(34, Pin.IN)
s_mid = Pin(35, Pin.IN)
s_right = Pin(36, Pin.IN)

BLACK = 1          # kalibrasion-e term 3: agar module-at barax bud 0 kon

# --- se voloom-e control (adad-haye robot-e MAN) ---
KP = 150
KD = 600
KI = 0.4
MAX_I = 150        # gire-ye kise-ye integral (zedd-e windup)

BASE = 550         # sorat-e paye (0 ta 1023)
SEARCH_SPEED = 450
LOOP_MS = 10       # zarban-e hadaf: 100 bar dar sanie


def error_from(l, m, r):
    # hamun jadval-e term 3 jalase 9: manfi = chap, mosbat = rast
    if l and m:
        return -1
    if r and m:
        return 1
    if l:
        return -2
    if r:
        return 2
    return 0


def clamp(value, low, high):
    if value < low:
        return low
    if value > high:
        return high
    return value


# hafeze-ye PID: beyn-e zarban-ha zende mimanad
integral = 0
last_error = 0
running = True

# dashboard
loop_count = 0
last_report = time.ticks_ms()

while running:
    l = s_left.value() == BLACK
    m = s_mid.value() == BLACK
    r = s_right.value() == BLACK

    if l and m and r:
        # navar-e arzi-ye payan: halat-e khas avval!
        robot.stop()
        print("payan-e khat! zaman ra sabt kon.")
        running = False
    elif not l and not m and not r:
        # khat gom shod: kise-ye integral ra khali kon va donbalash begard
        integral = 0
        if last_error > 0:
            robot.turn_right(SEARCH_SPEED)
        else:
            robot.turn_left(SEARCH_SPEED)
    else:
        error = error_from(l, m, r)

        # ghalb-e PID: se harf, se hokm
        integral = clamp(integral + error, -MAX_I, MAX_I)
        derivative = error - last_error
        last_error = error

        diff = KP * error + KI * integral + KD * derivative
        robot.tank(BASE + diff, BASE - diff)

    # dashboard: har sanie yek gozaresh
    loop_count = loop_count + 1
    if time.ticks_diff(time.ticks_ms(), last_report) >= 1000:
        print("loop dar sanie:", loop_count)
        loop_count = 0
        last_report = time.ticks_ms()

    time.sleep_ms(LOOP_MS)

print("barname tamam shod.")
```

<div dir="rtl">

> 🧪 **آزمایشگاه:** همین کد PID در [آزمایشگاه خودمان](/lab) هم اجرا می‌شود — مثل فصل ۹ ترم ۳، ولی این بار با Arduino C++: سه کلیدِ سنسور خط روی GPIO 34/35/36 و شش LED به‌جای موتورها. روشناییِ دو LED آبیِ ENA و ENB همان سرعتِ دو چرخ است، پس اثرِ هر سه حرف را با چشم می‌بینی: کلید را ناگهانی عوض کن — پرشِ لحظه‌ایِ اختلافِ نور همان ضربه‌ی D است؛ یک error کوچک را طولانی نگه دار — اختلافِ نوری که آرام‌آرام بیشتر می‌شود، پرشدنِ کیسه‌ی I است. کنسول Serial هم داشبورد error و ضربان را نشان می‌دهد.
>
> ولی یک صداقتِ لازم: **تنظیم PID را نمی‌شود در شبیه‌ساز انجام داد.** عددهای `KP` و `KD` و `KI` از وزنِ ربات، اصطکاکِ کف، سلامتِ باتری و پهنای خط می‌آیند — چیزهایی که فقط روی زمینِ واقعی وجود دارند. آزمایشگاه برای **فهمیدنِ** سه حرف است؛ پروتکل سه‌گام را روی ربات خودت اجرا کن.

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| PID | پی‌آی‌دی | کنترل سه‌جزئی: Proportional + Integral + Derivative |
| Derivative | دِریوِیتیو | مشتق؛ سرعتِ تغییر error — نگهبانِ آینده و ترمز پیش‌بینانه |
| Integral | اینتِگرال | جمعِ خطاهای گذشته — کیسه‌ی خاطره برای جبران کجیِ ماندگار |
| Steady-state error | استِدی استِیت اِرور | خطای ماندگار؛ کجیِ پایداری که P تنها نمی‌تواند صفرش کند |
| Windup | وایندآپ | پرشدنِ بیش از حد کیسه‌ی integral و پرت‌شدن ربات — با گیره و تخلیه مهار می‌شود |
| Damping | دَمپینگ | میرا کردن؛ آرام‌کردن نوسان — کار اصلی D |
| Overshoot | اُوِرشوت | ردشدن از هدف و زدن به آن‌طرف خط |
| Tuning protocol | تیونینگ پروتُکُل | دستورِ گام‌به‌گام تنظیم: اول P، بعد D کوچک، بعد I خیلی کوچک |

## تمرین‌ها

اول چک‌لیست پایان فصل: اسکلت C++ ربات با `tank` و `clamp` کار می‌کند؛ D و I را پیاده کرده‌ای و باگ بی‌صدای `lastError` را می‌شناسی؛ پروتکل سه‌گام را اجرا کرده‌ای؛ و رباتت پیچ سنجاقی را با PID رد می‌کند. اگر همه بله است:

- **تمرین اجباری:** پروتکل سه‌گام را کامل روی ربات خودت اجرا کن (`my_pid_follower`). جدول آزمایش با حداقل شش ردیف: `KP`، `KD`، `KI`، رفتار (پیچ گم شد / تاب بزرگ / رعشه‌ی ریز / کجی / نرم)، زمان سه دور. بهترین زمانِ PID را با بهترین P تنها مقایسه کن و بنویس چند درصد سریع‌تر شدی.
- **تمرین ستاره‌دار ⭐:** «حالت توربو»: بعد از تنظیم، `BASE` را پله‌پله بالا ببر و هر بار پروتکل را از گام ۲ تکرار کن. بیشترین `BASE`ای که رباتت هنوز سه دورِ تمیز می‌رود چند است؟ نمودار `BASE` در برابر زمانِ دور را در دفترچه رسم کن — درست مثل تیم‌های مسابقات واقعی.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t5/s04-pid-line-follower (یادستان, Yaadestan)
