# فصل ۹ — پروژهٔ نهایی، بخش دوم: قابلیت‌ها

<div dir="rtl">

# فصل ۹ — پروژهٔ نهایی، بخش دوم: قابلیت‌ها

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

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

مثل فصل ۸، این فصل هم سه مسیر موازی دارد و تو **فقط بخش مسیر خودت** را دنبال می‌کنی:

- **مسیر A — ربات پیشخدمت:** PID نرم برای حمل لیوان + چرخهٔ تحویل در ایستگاه.
- **مسیر B — دستیار اتاق:** داشبورد زندهٔ سنسورها + هشدار گرما + گزارش هوش مصنوعی.
- **مسیر C — ربات مسابقه‌ای:** راندن با گوشی + خودرانِ PID + آلارم تعادل.

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

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

- توضیح بدهی «قابلیت» چیست و چرا قانون «یکی‌یکی» قانونِ بقای امروز است.
- توابع TODO اسکلت مسیرت را با منطق واقعی پر کنی و دو تا سه قابلیت اصلی را جداجدا نمایش بدهی.
- یک خطای مکانیکی/سیم‌کشی و یک خطای منطقیِ واقعیِ مسیرت را تشخیص بدهی و رفع کنی.
- صفحهٔ M2 دفترچهٔ مهندسی را ببندی و هر قابلیت را در سی ثانیه نشان بدهی.

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

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

- **از فصل ۸:** اسکلت مسیرت باید کامل و تپنده باشد. امروز فقط بدنهٔ توابع TODO پر می‌شود؛ اگر M1 عقب است، اول آن را ببند.

و بسته به مسیرت، این‌ها را از قبل باید بلد باشی:

- **مسیر A:** PID فصل ۴، حرکت نرم Servo از ترم ۲، فصل ۸، ماشین حالت ترم ۳، فصل ۶، و درسِ «جشن زودرس» ترم ۳، فصل ۱۱.
- **مسیر B:** سنسورهای ترم ۲ (فصل‌های ۳، ۴، ۶، ۹)، hysteresis ترم ۲، فصل ۴، داشبورد و f-string ترم ۴، فصل ۴، و الگوی Gemini ترم ۴، فصل ۹.
- **مسیر C:** پروتکل فرمان فصل ۶، PID فصل ۴، MPU فصل ۵، آرایه و while فصل ۳، و ماشین حالت ترم ۳، فصل ۶.

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

| قطعه / ابزار | تعداد | جایگزین ارزان یا در دسترس |
|---|---|---|
| ساختهٔ فصل ۸ مسیر خودت (ربات+بازو / ایستگاه / ربات+MPU) | ۱ | — |
| مسیر A و C: زمین بازی ترم ۳ (خط + نوار عرضی) | ۱ | نوار چسب برق روی کف روشن، همان دستور ترم ۳ |
| مسیر A: لیوان کاغذی + چند پاستیل برای بار | ۱ | لیوان خالی هم قبول؛ آب فعلاً ممنوع! |
| مسیر A و C: باتری پر + دست ذخیره | ۲ دست | تنظیم PID با باتری ضعیف بی‌معناست |
| مسیر B: اینترنت خانه + secrets.py آمادهٔ روی برد | — | فصل ۸ ساختی |
| کامپیوتر + گوشی + دفترچهٔ مهندسی و سند طراحی | ۱ | — |

## ۱. قابلیت یعنی چه؟ و قانون طلایی «یکی‌یکی»

قبل از کد، دو تعریف کوتاه.

**قابلیت** یعنی کاری که در دموی نمایش، جلوی داور نشانش می‌دهی و برایش امتیاز می‌گیری — نه هر خط کد. «سروو تکان می‌خورد» قابلیت نیست؛ «ربات در ایستگاه، لیوان را تحویل می‌دهد» قابلیت است. سند طراحی‌ات را باز کن: milestone دو تو همین فهرست دو-سه قابلیته است.

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

> 💡 **نکته:** قبل از نوشتن کدِ هر قابلیت، در دفترچه یک خط بنویس: این قابلیت روی شانهٔ کدام فصل‌ها سوار است؟ همین یک خط، بعداً موقع رفعِ اشکال نصف راه را برایت کوتاه می‌کند.

## چالش: قابلیت است یا قطعه‌ای از قابلیت؟

قبل از باز کردن جواب، خودت جواب بده: «LED قرمز روشن می‌شود» قابلیت است یا قطعه‌ای از یک قابلیت؟ و یک قابلیتِ کاملِ مسیر B چه شکلی است؟

---

**جواب:** «LED قرمز روشن می‌شود» فقط قطعه‌ای از یک قابلیت است — یک عملِ ریز. قابلیت، کارِ کاملی است که کاربر می‌بیند و می‌فهمد؛ مثلاً در مسیر B: «وقتی اتاق داغ می‌شود، دستگاه با آژیر هشدار می‌دهد و روی داشبورد ALERT نشان می‌دهد». روشن‌شدنِ LED فقط بخشی از همین قابلیت است.

حالا بپر سراغ بخش مسیر خودت. بقیهٔ فصل سه بخشِ موازی است — فقط مالِ خودت را بخوان.

## مسیر A — پیشخدمتی که لیوان نمی‌ریزد

سه TODO داری: موتورها، مغزِ PID، و چرخهٔ تحویل. به ترتیب و یکی‌یکی.

### قابلیت اول: موتورها و مغزِ PID (این بار با مسافر!)

بلوک `tank` و `clampF` و ضریب‌های کالیبراسیون `FACTOR` را کلمه‌به‌کلمه از فصل ۴ می‌آوری، به‌علاوهٔ `turnLeft` و `turnRight` برای جست‌وجوی خطِ گم‌شده. بعد مغز: `errorFrom` و `pidStep` — باز هم کپیِ وفادار فصل ۴ با خطای ‎−۲ تا ‎+۲، کیسهٔ integral با گیرهٔ ضدwindup، ترمز D، و رفتار «گم‌شدن خط».

فقط اعداد فرق می‌کنند: `BASE` را از مسابقه‌ایِ فصل ۴ پایین‌تر می‌آوری و `KP` را نرم‌تر — چون امروز مسافر داریم و لیوان‌پران ممنوع!

1. چرخ‌ها را بالا نگه دار، اجرا کن، دستت را جلوی سنسورها ببر و ببین جهت چرخش‌ها منطقی است.
2. حالا روی زمین، اول **بدون لیوان**: اگر می‌لرزد `KD` را کمی بالا ببر، اگر پیچ‌ها را نمی‌گیرد `KP` را — همان آیینِ تنظیم فصل ۴.
3. حالا لیوان و چند پاستیل را بگذار و دوباره تست کن.

و همین‌جا اولین مهمان ناخوانده: `armCarry` می‌گوید ۹۰ درجه، ولی سینی حدود سی درجه **کج** می‌ایستد و پاستیل‌ها سر می‌خورند.

> 🔧 **اگر کار نکرد (سینیِ کج):** کد درست است — مشکل مکانیکی است. وقتی هورن را روی سروو فشار دادی، محورِ سروو روی ۹۰ نبود و هورن روی دنده‌های شفت کج سوار شده. راه‌حل حرفه‌ای: اول `armCarry()` را صدا بزن تا محور واقعاً روی ۹۰ بایستد، بعد پیچ هورن را باز کن، بازو را در حالتِ تراز روی دنده‌ها جا بزن و ببند. قانونش را در دفترچه بنویس: **اول محور را سر جایش ببر، بعد بازو را ببند.**

### قابلیت دوم: چرخهٔ تحویل

`armServe` را پله‌پله می‌نویسیم — حلقهٔ for با گام ۲ درجه و مکث کوتاه؛ حرکت نرم، چون سرووی عجول لیوان‌پران است. و ماشین حالت: FOLLOW با دیدنِ امضای ۱-۱-۱ می‌رود به STATION. نسخهٔ اولت را ساده بنویس:

</div>

```cpp
  else if (state == "STATION") {
    stopMotors();
    armServe();
    state = "FOLLOW";   // bargard be donbal kardan
  }
```

<div dir="rtl">

اجرا: ربات به ایستگاه می‌رسد، می‌ایستد، تحویل می‌دهد... و دوباره تحویل می‌دهد. و دوباره! پیشخدمت گیر کرده — مؤدب‌ترین باگِ دوره. خودت بگو چرا... آفرین: بعد از `armServe`، ربات هنوز **روی نوار عرضی** است؛ به FOLLOW برمی‌گردد، همان لحظه دوباره ۱-۱-۱ می‌بیند و باز STATION. این دقیقاً همان «جشن زودرس» ترم ۳، فصل ۱۱ است — و همان دارو: بعد از تحویل، `BLIND_MS` میلی‌ثانیه **کور** جلو برو تا از نوار رد شوی. شمارندهٔ `stationsDone` هم اضافه می‌کنی که بعد از ایستگاه آخر، حالت DONE پایان شیفت را اعلام کند. و متغیرهای PID را موقع برگشت صفر می‌کنی که انتگرالِ ماندهٔ قبلی، استارت را کج نکند.

برنامهٔ کامل — اسکلت فصل ۸ به‌علاوهٔ همین دو قابلیت (فایل `path-a/waiter_features.ino`):

</div>

```cpp
// Term 5 - Session 09 - Path A: Milestone 2 - ghabeliat-ha
// F1: PID-e narm baraye haml-e livan (block-e jalase 4)   F2: charkhe-ye tahvil dar istgah
// dars-e bozorg-e emrooz: bad az tahvil, KOOR az navar rad sho (dars-e term 3 j11!)

// ---------- pin-ha ----------
const int ENA = 32;       // sorat-e motor-e chap (PWM)
const int IN1 = 26;       // motor-e chap - jolo
const int IN2 = 27;       // motor-e chap - aghab
const int IN3 = 14;       // motor-e rast - jolo
const int IN4 = 25;       // motor-e rast - aghab
const int ENB = 33;       // sorat-e motor-e rast (PWM)
const int S_LEFT = 34;    // sensor-e khat - chap
const int S_MID = 35;     // sensor-e khat - vasat
const int S_RIGHT = 36;   // sensor-e khat - rast
const int SERVO_PIN = 13; // bazoo-ye servo SG90

const int BLACK = 1;      // gharardad-e term 3

// ---------- pich-haye tanzim ----------
float KP = 120.0;             // az adad-haye jalase 4 shoroo kon, baraye livan kamtar
float KD = 500.0;             // tormoz-e larzesh (j4)
float KI = 0.3;               // faghat agar robot yek-vari mimanad (j4)
const float MAX_I = 150.0;    // gire-ye kise-ye integral - zedd-e windup (j4)
const int BASE = 420;         // sorat-e paye: ba livan aramtar az hamishe!
const int SEARCH_SPEED = 400; // charkhesh-e aram hangam-e gom shodan-e khat (j4)
const int STATIONS = 2;       // tedad-e istgah-haye tahvil dar masir
const int BLIND_MS = 450;     // bad az tahvil: in-ghadr koor jolo boro ta az navar rad shi
const int LOOP_MS = 10;       // zarban-e sabet-e halghe (j4)

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

int stationsDone = 0;      // chand istgah service shod?
float integral = 0.0;
float lastError = 0.0;
String state = "FOLLOW";   // mashin-e halat (term 3 j6): FOLLOW / STATION / DONE

// ---------- servo / bazoo ----------
void servoWrite(int angle) {
  // 0..180 daraje -> duty-e 16-bit: 1638 (0.5ms) ta 7864 (2.4ms), hamun baze-ye T2 j8
  int duty = 1638 + angle * (7864 - 1638) / 180;
  ledcWrite(SERVO_PIN, duty);
}

void armCarry() {
  servoWrite(90);   // halat-e haml: sini terazoo
}

void armServe() {
  // harekat-e NARAM: pele-pele, livan nariz! (halghe-ye for - T5 j3)
  for (int a = 90; a >= 25; a = a - 2) {
    servoWrite(a);
    delay(25);
  }
  delay(1500);   // "befarmaid!" - mekas baraye bardashtan
  for (int a = 26; a <= 90; a = a + 2) {
    servoWrite(a);
    delay(25);
  }
}

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

void tank(float left, float right) {
  // har do charkh be jolo, har kodam ba sorat-e khodash (j4)
  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);
}

// ---------- maghz-e khat (PID - block-e jalase 4) ----------
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;
}

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

  if (!l && !m && !r) {
    // khat gom shod: kise-ye integral khali + charkhesh be samt-e akharin khata (j4)
    integral = 0.0;
    if (lastError > 0) {
      turnRight(SEARCH_SPEED);
    } else {
      turnLeft(SEARCH_SPEED);
    }
    return;
  }

  float error = errorFrom(l, m, r);
  integral = clampF(integral + error, -MAX_I, MAX_I);  // I: kise ba gire (j4)
  float derivative = error - lastError;                // D (j4)
  lastError = error;
  float diff = KP * error + KI * integral + KD * derivative;
  tank(BASE + diff, BASE - diff);
}

bool atStation() {
  // emzaye 1-1-1-e term 3: har se sensor siah = istgah (navar-e arzi)
  bool l = digitalRead(S_LEFT) == BLACK;
  bool m = digitalRead(S_MID) == BLACK;
  bool r = digitalRead(S_RIGHT) == BLACK;
  return l && m && r;
}

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

  pinMode(IN1, OUTPUT);
  pinMode(IN2, OUTPUT);
  pinMode(IN3, OUTPUT);
  pinMode(IN4, OUTPUT);
  ledcAttach(ENA, 1000, 10);      // PWM-e sorat: 0..1023 (meghyas-e term 3)
  ledcAttach(ENB, 1000, 10);
  ledcAttach(SERVO_PIN, 50, 16);  // servo: 50Hz, 16-bit (T2 j8)

  pinMode(S_LEFT, INPUT);
  pinMode(S_MID, INPUT);
  pinMode(S_RIGHT, INPUT);

  stopMotors();
  armCarry();

  Serial.println("livan ra rooye sini bogzar; robot ra sar-e khat...");
  for (int n = 5; n >= 1; n = n - 1) {   // shomaresh-e makoos (term 3)
    Serial.println(n);
    delay(1000);
  }
  Serial.println("GO! pishkhedmat dar khedmat ast");
}

void loop() {
  if (state == "FOLLOW") {
    if (atStation()) {
      state = "STATION";
    } else {
      pidStep();
    }
  }
  else if (state == "STATION") {
    stopMotors();
    stationsDone = stationsDone + 1;
    Serial.print("istgah-e ");
    Serial.print(stationsDone);
    Serial.println(" -> tahvil-e livan");
    armServe();
    if (stationsDone >= STATIONS) {
      state = "DONE";
    } else {
      tank(BASE, BASE);        // KOOR az navar rad sho - jashn-e zoodras mamnu!
      delay(BLIND_MS);
      integral = 0.0;          // PID ra tamiz shoroo kon
      lastError = 0.0;
      state = "FOLLOW";
    }
  }
  else if (state == "DONE") {
    stopMotors();
    Serial.println("shift tamam! hame-ye istgah-ha service shodand");
    while (true) {
      delay(1000);   // payan - ta reset-e badi
    }
  }
  delay(LOOP_MS);
}
```

<div dir="rtl">

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

> 🔧 **اگر کار نکرد:** ربات در ایستگاه بی‌وقفه تحویل می‌دهد؟ حرکت کورِ `BLIND_MS` بعد از تحویل جا افتاده — یا اگر باز تکرار شد، مقدارش را کمی زیاد کن. با لیوان پر پیچ‌ها را گم می‌کند؟ وزن، رفتار ربات را عوض کرده و KP/KD قدیمی‌اند: با بار واقعی دوباره تنظیم کن، اول `BASE` را کم کن بعد `KD`، و اعداد نهایی را در دفترچه بنویس.

> 💡 **نکته:** منطقِ چرخهٔ تحویل را می‌توانی بدون ربات هم بیازمایی: به‌جای سه سنسورِ خط، سه سیم را دستی به GND و 3V3 بزن تا امضای ۱-۱-۱ بسازی و چرخهٔ STATION و شمارنده را در Serial Monitor ببین. فقط صادق باش: لرزش و سُرخوردنِ واقعیِ لیوان فقط روی زمین واقعی معنا دارد.

> 🧪 **آزمایشگاه:** مسیر A در [آزمایشگاه](/lab) زنده است — سه سنسور خط، سروو و شش LEDِ موتور روی صفحه‌اند. با کلیدهای سنسور امضای ۱-۱-۱ بساز و چرخهٔ STATION و شمارندهٔ ایستگاه‌ها را در کنسول ببین؛ باگِ «پیشخدمتِ گیرکرده» را هم می‌توانی همان‌جا بازتولید کنی و اثرِ `BLIND_MS` را با چشم ببینی. **مسیر C و مسیر B اجرا نمی‌شوند** — MPU6050، رادیوی BLE، شبکه و تماس AI هیچ‌کدام در شبیه‌ساز نیستند و باید روی سخت‌افزار واقعی تست شوند.

### چالش مسیر A: چرا `integral` را صفر می‌کنیم؟

چرا بعد از STATION، درست قبل از برگشت به FOLLOW، متغیر `integral` را صفر می‌کنیم؟ اگر نکنیم، لحظهٔ استارت دوباره چه رفتاری می‌بینی؟

---

**جواب:** کیسهٔ `integral` خطاهای پیش از رسیدن به ایستگاه را در خودش نگه داشته است. موقعی که ربات ایستاده، `pidStep` اصلاً صدا زده نمی‌شود و این عددِ مانده هم خالی نمی‌شود. اگر صفرش نکنیم، لحظهٔ راه‌افتادنِ دوباره همان انتگرالِ کهنه یک هُلِ ناگهانی به موتورها می‌دهد و ربات کج و لرزان استارت می‌زند — درست وقتی که لیوان روی سینی است. صفر کردنِ `integral` یعنی هر بار از یک شروعِ تمیز و آرام.

## مسیر B — اتاقی که گزارش می‌دهد

چهار TODO داری: سه سنسور و AI؛ به‌علاوهٔ داشبورد و هشدار.

### قابلیت اول: سنسورها

`read_temp_hum` را اول بدونِ محافظ بنویس — `sensor_dht.measure()` و برگرداندنِ دما و رطوبت — و اجرا کن. بی‌مقدمه، اولین مهمان ناخوانده:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 37, in read_temp_hum
OSError: [Errno 110] ETIMEDOUT
```

<div dir="rtl">

`ETIMEDOUT` یعنی «منتظر جواب ماندم و نیامد». سنسور خراب است؟ صبر کن — **اول سیم‌ها، بعد شک به قطعه.** نگاه کن: سیمِ دیتای DHT11 روی Breadboard یک سوراخ آن‌طرف‌تر نشسته و به هیچ‌جا وصل نیست! جایش می‌اندازی و اجرا می‌کنی: دما می‌آید. ولی try/except ترم ۲ را هم برمی‌گردانیم، چون DHT11 حتی با سیمِ درست هم گاهی قهر می‌کند — قراردادِ ‎−۱ یعنی «این بار نشد».

بعد LDR (روی پایهٔ ۳۵) و HC-SR04 را از ترم ۲ کپی می‌کنیم و یک شمارندهٔ رفت‌وآمدِ بامزه با متغیر وضعیتِ ترم ۱ می‌سازیم: هر بار کسی نزدیک‌تر از `VISIT_CM` بیاید، یک ملاقات شمرده می‌شود.

### قابلیت دوم: داشبورد و هشدار

`build_page` حالا f-stringِ واقعیِ ترم ۴ می‌شود، با refresh پنج‌ثانیه‌ای.

![ماکاپ دو گوشی کنار هم با قاب فیروزه‌ای: گوشی چپ صفحهٔ وبِ داشبوردِ تیره با چهار ردیف داده (TEMP، HUM، LIGHT، VISITORS)، یک چراغ قرمز ALERT و دکمهٔ AI REPORT؛ گوشی راست صفحهٔ گزارش با متن حبابیِ فارسیِ راست‌چین و یک فلش بازگشت؛ وسطشان یک برد ESP32 روی Breadboard که خط‌های داده به گوشیِ چپ می‌فرستد](/lesson-assets/t5-s09-capstone-features/prompt/02-image-path-b-dashboard.png)

حالا هشدارِ گرما. نسخهٔ اولت را ساده بنویس:

</div>

```python
    if temp >= 30:
        alarm_on = True
    else:
        alarm_on = False
```

<div dir="rtl">

می‌شنوی؟ دما روی مرزِ ۳۰ بین ۲۹ و ۳۰ پت‌پت می‌کند و آژیر دیوانه می‌شود. این را ترم ۲، فصل ۴ یک بار شکار کردیم — و همان دارو: **hysteresis، دو آستانه.** روشن در `TEMP_ON`، خاموش فقط وقتی به `TEMP_OFF` پایین‌تر برگردد؛ بین دو آستانه، هشدار حالتِ قبلش را نگه می‌دارد. یک شرطِ `temp >= 0` هم می‌گذاری که ‎−۱ِ «این بار نشد» آژیر را خاموش نکند.

![نمودار مقایسهٔ یک آستانه با دو آستانه: بالا، خط دمای موج‌دار یک خط‌چینِ «۳۰» را بارها قطع می‌کند و بازر تند روشن‌وخاموش می‌شود؛ پایین، همان خط با دو خط‌چینِ «ON 31» قرمز و «OFF 29» سبز که یک نوارِ آرام می‌سازند و بازر فقط یک بار بالای قرمز روشن و یک بار زیر سبز خاموش می‌شود؛ محورها TIME و TEMP](/lesson-assets/t5-s09-capstone-features/prompt/03-image-hysteresis-two-thresholds.png)

در کدِ کامل، خطِ اولِ تابع `check_alerts` یک واژهٔ تازه هم دارد: `global`. یادت هست فصل ۴ دیدیم متغیری که داخل تابع ساخته شود محلی است و ته تابع می‌میرد؟ Python هم همین قانون را دارد؛ چون این تابع می‌خواهد مقدارِ متغیرهای بالای فایل (`alarm_on` و دوستانش) را **عوض کند**، باید اول اعلام کند `global alarm_on`، وگرنه Python یک متغیر محلیِ نو می‌سازد و اصلِ ماجرا دست‌نخورده می‌ماند.

> 💡 **نکته:** قلبِ هشدار ما فعلاً با هر درخواستِ مرورگر می‌تپد — یعنی تا وقتی داشبورد با refresh باز است، هر پنج ثانیه یک بار. این یک محدودیت است؛ در دفترچه بنویسش. فصل بعد پایدارش می‌کنیم تا حتی با مرورگرِ بسته هم بیدار بماند.

### قابلیت سوم (ستارهٔ مسیر B): گزارش AI

تابع `ask_ai` همان الگوی ترم ۴، فصل ۹ است — `gc.collect`، ‏POST با urequests، و پارسِ JSONِ جواب. کلیدِ Gemini در هدرِ `x-goog-api-key` می‌رود (نه در آدرس!). تابع `build_report_prompt` دادهٔ زندهٔ سنسورها را در یک پرامپتِ انگلیسی می‌چیند و جوابِ **فارسی** می‌خواهد (پرامپت را انگلیسی نوشتیم که در کدِ LTR تمیز بماند). مسیرِ `/report` با عملگرِ `in` ترم ۴ تشخیص داده می‌شود. اسمِ مدل در ثابتِ `AI_MODEL` نشسته و مقدارِ روزآمدش در جدولِ جزوه است («در زمان ضبط چک شود»).

> ⚠️ **مواظب باش:** قانونِ همیشگیِ کلید — کلیدِ API فقط در `secrets.py`، هرگز در کدِ اصلی، و هرگز در اسکرین‌شات یا جلوی دوربین. `secrets.py` را جلوی هیچ‌کس باز نکن.

برنامهٔ کامل — اسکلت فصل ۸ به‌علاوهٔ این سه قابلیت (فایل `path-b/assistant_features.py`):

</div>

```python
# Term 5 - Session 09 - Path B: Milestone 2 - ghabeliat-ha
# F1: dashboard-e zende   F2: hoshdar-e garma ba hysteresis (term 2 j4!)   F3: gozaresh-e AI
import network
import socket
import time
import dht
import machine
import urequests
import json
import gc
from machine import Pin, ADC

from secrets import WIFI_SSID, WIFI_PASS, GEMINI_API_KEY

# ---------- pin-ha (pin-map-e sabet) ----------
sensor_dht = dht.DHT11(Pin(16))
ldr = ADC(Pin(35))
ldr.atten(ADC.ATTN_11DB)   # hamun tanzim-e term 2: kol-e baze 0..4095
trig = Pin(5, Pin.OUT)
echo = Pin(18, Pin.IN)
buzzer = machine.PWM(Pin(4), freq=1000, duty=0)   # saket ta vaghti lazem shavad
led_alert = Pin(25, Pin.OUT)

# ---------- pich-haye tanzim ----------
AI_MODEL = "gemini-flash-latest"   # esm-e model dar jadval-e jozve: dar zaman-e zabt check shavad
TEMP_ON = 31    # hoshdar roshan (do astane = hysteresis, term 2 j4)
TEMP_OFF = 29   # hoshdar khamush
VISIT_CM = 40   # nazdiktar az in = yek nafar jelo-ye miz ast

alarm_on = False
visitors = 0
someone_there = False

# ---------- sensor-ha (term 2) ----------
def read_temp_hum():
    # DHT11 gahi ghahr mikonad - try/except (term 2 j6)
    try:
        sensor_dht.measure()
        return (sensor_dht.temperature(), sensor_dht.humidity())
    except OSError:
        return (-1, -1)   # gharardad: -1 yani "in bar nashod"

def read_light():
    return ldr.read()   # 0..4095 (term 2 j3)

def read_distance_cm():
    trig.value(0)
    time.sleep_us(2)
    trig.value(1)
    time.sleep_us(10)
    trig.value(0)
    t = machine.time_pulse_us(echo, 1, 30000)
    if t < 0:
        return -1
    return t // 58

def beep(times):
    for i in range(times):
        buzzer.duty(512)
        time.sleep(0.12)
        buzzer.duty(0)
        time.sleep(0.08)

def check_alerts(temp, dist):
    # hoshdar-e garma ba DO astane - bedun-e pet-pet! (term 2 j4)
    global alarm_on, visitors, someone_there
    if alarm_on == False and temp >= TEMP_ON:
        alarm_on = True
        beep(3)
        print("HOSHDAR: otagh kheyli garm ast!")
    if alarm_on == True and temp >= 0 and temp <= TEMP_OFF:
        alarm_on = False
        print("hoshdar tamam: dama bargasht be mahdude-ye khoob")
    if alarm_on:
        led_alert.value(1)
    else:
        led_alert.value(0)

    # shomarande-ye raft-o-amad ba motaghayer-e vaziat (term 1 j9)
    if dist > 0 and dist < VISIT_CM and someone_there == False:
        someone_there = True
        visitors = visitors + 1
    if (dist < 0 or dist >= VISIT_CM) and someone_there == True:
        someone_there = False

# ---------- AI (olgu-ye term 4 j9) ----------
def ask_ai(question):
    gc.collect()   # ghabl az POST hafeze ra tamiz kon (term 4 j9)
    url = "https://generativelanguage.googleapis.com/v1beta/models/" + AI_MODEL + ":generateContent"
    body = {"contents": [{"parts": [{"text": question}]}]}
    headers = {"Content-Type": "application/json", "x-goog-api-key": GEMINI_API_KEY}
    r = urequests.post(url, headers=headers, data=json.dumps(body))
    data = r.json()
    r.close()
    answer = data["candidates"][0]["content"]["parts"][0]["text"]
    return answer

def build_report_prompt(temp, hum, light, dist):
    p = "You are a friendly room assistant for a teenager."
    p = p + " Room data: temperature=" + str(temp) + " C, humidity=" + str(hum) + " %,"
    p = p + " light=" + str(light) + " (0=dark, 4095=bright),"
    p = p + " visitors so far=" + str(visitors) + "."
    p = p + " Write a short warm report in PERSIAN (2-3 sentences) with one tip."
    return p

# ---------- safhe-ha (term 4 j4 + j5) ----------
def build_page(temp, hum, light, dist):
    html = f"""<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>AIRO</title>
<meta http-equiv="refresh" content="5"></head>
<body style="font-family:sans-serif;text-align:center;background:#111;color:#eee">
<h1>Dastyar-e otagh</h1>
<p>Dama: {temp} C | Rotubat: {hum} %</p>
<p>Noor: {light} / 4095</p>
<p>Fasele: {dist} cm | Raft-o-amad: {visitors}</p>
<p>Hoshdar-e garma: {alarm_on}</p>
<p><a href="/report">gozaresh-e AI begir</a></p>
</body></html>"""
    return html

def report_page(text):
    html = f"""<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>AIRO report</title></head>
<body style="font-family:sans-serif;text-align:center;background:#111;color:#eee">
<h1>Gozaresh-e AI</h1>
<p dir="rtl" style="font-size:1.2em;max-width:600px;margin:auto">{text}</p>
<p><a href="/">bargasht be dashboard</a></p>
</body></html>"""
    return html

# ---------- WiFi + server (mesl-e eskelet-e jalase 8) ----------
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(WIFI_SSID, WIFI_PASS)
print("dar hal-e vasl shodan be WiFi...")
while not wlan.isconnected():
    time.sleep(0.5)
print("vasl shod! IP:", wlan.ifconfig()[0])

addr = socket.getaddrinfo("0.0.0.0", 80)[0][-1]
server = socket.socket()
server.bind(addr)
server.listen(1)
print("dastyar amade ast - dashboard ra dar gooshi baz kon")

while True:
    conn, client = server.accept()
    request = str(conn.recv(1024))

    temp, hum = read_temp_hum()
    light = read_light()
    dist = read_distance_cm()
    check_alerts(temp, dist)   # ta dashboard baz ast, ghalb-e hoshdar ham mizanad

    if "GET /report" in request:
        answer = ask_ai(build_report_prompt(temp, hum, light, dist))
        page = report_page(answer)
    else:
        page = build_page(temp, hum, light, dist)

    conn.send("HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\n\r\n")
    conn.send(page)
    conn.close()
    gc.collect()
```

<div dir="rtl">

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

> 🔧 **اگر کار نکرد:** خطای `ETIMEDOUT` در `measure()`؟ اول سیم‌ها (سوراخِ درستِ Breadboard!)، بعد try/except با قراردادِ ‎−۱. بازر نزدیکِ آستانه مدام روشن/خاموش می‌شود؟ یک آستانه به‌جای دو گذاشته‌ای — `TEMP_ON` و `TEMP_OFF` را جدا و با فاصلهٔ حداقل دو درجه بگذار. صفحهٔ `/report` دیر می‌آید یا خطا می‌دهد؟ طبیعی است که چند ثانیه بماند؛ اگر خطا داد، کلید و اینترنت را چک کن — پایدارسازیِ کامل در فصل ۱۰.

> 💡 **نکته:** مسیر B را نمی‌شود کامل در شبیه‌ساز جلو برد: تماسِ واقعیِ AI و سنسورِ DHT فقط روی سخت‌افزارِ واقعی جواب می‌دهند. اگر ترم ۴ مسیرِ WiFiِ شبیه‌ساز را رفته‌ای، خودِ داشبورد همان‌جا هم بالا می‌آید، ولی گزارشِ فارسی را با برد واقعی تست کن.

### چالش مسیر B: اگر هر دو آستانه ۳۰ باشند؟

اگر به‌جای دو آستانهٔ ۳۱ و ۲۹، هر دو را ۳۰ بگذاری، دوباره چه اتفاقی می‌افتد و چرا؟

---

**جواب:** پت‌پت برمی‌گردد! وقتی هر دو آستانه ۳۰ باشند، دیگر «نوارِ آرام» بین دو خط وجود ندارد و درست مثلِ نسخهٔ یک‌آستانه‌ای عمل می‌کند: دما روی مرزِ ۳۰ کمی که بلرزد — یک لحظه ۳۰، یک لحظه ۲۹ — آژیر بی‌وقفه روشن و خاموش می‌شود. hysteresis فقط وقتی کار می‌کند که بین «روشن‌شدن» و «خاموش‌شدن» یک فاصلهٔ واقعی باشد.

## مسیر C — فرمان، خودران، و حسِ تعادل

سه قابلیت: راندن با گوشی، خودرانِ PID، و آلارمِ تعادل.

### قابلیت اول: راندن با گوشی

بلوکِ `tank` و `clampF` فصل ۴ با ضریب‌های کالیبراسیون، به‌علاوهٔ `back` و چرخش‌های فصل ۶ — این بار با سرعتِ دلخواه. و جدولِ فرمان در `handleCommand`: حرف‌های F/B/L/R/S (حرفِ کوچک هم قبول است — همان پیشنهادِ درستِ code review فصل ۶!)، و ۱/۲/۳ برای سه دندهٔ سرعت که در یک آرایهٔ فصل ۳ نشسته‌اند. گوشی می‌شود دستهٔ فرمانِ واقعی، و جوابِ هر فرمان با `bleSend` به گوشی برمی‌گردد — راننده باید بداند ربات شنید.

![کارت مرجعِ پروتکل فرمانِ تک‌حرفیِ مسیر C با قاب بنفش: گوشی‌ای که تک‌حرف‌ها را با بلوتوث می‌فرستد و شبکه‌ای از دکمه‌های کلاهک‌کلیدی — F فلش بالا، B فلش پایین، L و R چرخش، S دستِ توقف، ۱ و ۲ و ۳ دنده‌های سرعت، A با آیکونِ رباتِ خط‌رو و برچسبِ AUTO، M با آیکونِ دستهٔ بازی و برچسبِ MANUAL، و نشانِ هشدارِ TILT که فقط S را می‌پذیرد](/lesson-assets/t5-s09-capstone-features/prompt/05-image-path-c-command-protocol.png)

تستِ اول با چرخ‌های بالا، بعد روی زمین.

### قابلیت دوم: خودران

فرمانِ `A` باید PID فصل ۴ را روشن کند. ساده‌ترین فکرِ دنیا را بنویس:

</div>

```cpp
  else if (c == 'A') {
    while (true) {
      pidStep();   // khodran... ta abad!
    }
  }
```

<div dir="rtl">

خودران شد و قشنگ خط را می‌گیرد — ولی دیگر خودمان اختیار نداریم! ‏M بی‌اثر، S بی‌اثر؛ آخرش باید ربات را با دست از روی خط برداری. چرا؟ به کد نگاه کن: وقتی وارد `while (true)` شدیم، دیگر هیچ‌وقت به `loop` برنمی‌گردیم — یعنی `bleRead` دیگر هرگز صدا زده نمی‌شود؛ فرمان‌های تو می‌رسند ولی هیچ‌کس در خانه نیست که در را باز کند. اسمش را بگذار **حلقهٔ زندانی**.

درمانش را از ترم ۳، فصل ۶ بلدی: ماشین حالت. فرمانِ A فقط `mode` را به AUTO عوض می‌کند؛ خودِ `loop` در هر دور، اگر AUTO بود **فقط یک قدمِ** `pidStep` برمی‌دارد و بعد باز به `bleRead` سر می‌زند. هیچ حلقه‌ای هیچ‌کس را زندانی نمی‌کند و M و S همیشه شنیده می‌شوند. این جمله را قاب کن: **در برنامهٔ رباتی، هیچ کاری حق ندارد حلقهٔ اصلی را گروگان بگیرد.**

### قابلیت سوم: آلارمِ تعادل

هر صد میلی‌ثانیه زاویه‌های X و Y را از همان کتابخانهٔ فصل ۵ می‌پرسی (و `mpu.update()` طبق قانونِ فصل ۵ هر دورِ حلقه می‌تپد). اگر قدرِ زاویه از `TILT_LIMIT` گذشت: موتورها قطع، سه بوق، پیامِ «kaj shodam!» به گوشی، و حالتِ TILT که تا صاف‌کردنِ ربات و زدنِ S، هیچ فرمانِ حرکتی را قبول نمی‌کند — ایمنی اول.

تستش بامزه‌ترین تستِ دوره است: ربات را روی سراشیبیِ مقوایی بفرست. و همین‌جا مهمانِ ناخواندهٔ دوم: در تست‌های زمینِ صاف هم گاهی آلارم می‌زند! ربات که کج نیست... دقت کن: MPU با یک تکه چسبِ شل نصب شده و روی زمینِ زبر، **خودِ سنسور می‌لرزد** — لرزش یعنی شتاب‌های تیز، یعنی زاویه‌های لحظه‌ایِ دروغ.

سه‌قدمِ درمان:

1. نصبِ محکم و صاف (چسبِ دوطرفهٔ تازه یا پیچ).
2. صفرگیریِ `calcOffsets` روی زمینِ صاف قبل از هر مسابقه.
3. آستانه‌ای که خیلی حساس نباشد — ۲۵ درجهٔ نگهبانِ ساکنِ فصل ۵ را برای رباتِ در حال حرکت به ۳۵ می‌بریم.

برنامهٔ کامل — اسکلت فصل ۸ به‌علاوهٔ این سه قابلیت (فایل `path-c/racer_features.ino`):

</div>

```cpp
// Term 5 - Session 09 - Path C: Milestone 2 - ghabeliat-ha
// F1: randan ba gooshi (protocol-e tak-harfi j6)   F2: halat-e khodran PID (block-e j4)
// F3: alarm-e taadol ba MPU6050 (block-e j5)
// dars-e bozorg-e emrooz: hich WHILE-e block-konande! har door-e loop faghat YEK ghadam

#include <BLEDevice.h>
#include <BLEServer.h>
#include <BLE2902.h>
#include <Wire.h>
#include <MPU6050_light.h>

// --- UUID-haye standard-e "Nordic UART" (jalase 6) ---
#define SERVICE_UUID "6E400001-B5A3-F393-E0A9-E50E24DCCA9E"
#define RX_UUID      "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"
#define TX_UUID      "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"

BLECharacteristic *rxChar;   // keshoo-ye farman-haye gooshi (jalase 6)
BLECharacteristic *txChar;   // keshoo-ye javab-haye ma

MPU6050 mpu(Wire);           // ketabkhane-ye MPU6050_light (jalase 5)

// ---------- pin-ha (pin-map-e sabet) ----------
const int ENA = 32;     // sorat-e motor-e chap (PWM)
const int IN1 = 26;     // motor-e chap - jolo
const int IN2 = 27;     // motor-e chap - aghab
const int IN3 = 14;     // motor-e rast - jolo
const int IN4 = 25;     // motor-e rast - aghab
const int ENB = 33;     // sorat-e motor-e rast (PWM)
const int S_LEFT = 34;  // sensor-e khat - chap
const int S_MID = 35;   // sensor-e khat - vasat
const int S_RIGHT = 36; // sensor-e khat - rast
const int BUZZER = 4;   // boogh-e hoshdar (tanzim-e jalase 5)

const int BLACK = 1;    // gharardad-e term 3

// ---------- pich-haye tanzim ----------
int speeds[] = {400, 600, 850};   // araye (T5 j3): dande-haye 1 / 2 / 3
int gear = 1;                     // index-e dande (0..2) -> shoroo ba dande 2
float KP = 150.0;                 // adad-haye khodet az jalase 4!
float KD = 600.0;
float KI = 0.4;
const float MAX_I = 150.0;        // gire-ye kise-ye integral (j4)
const int BASE = 550;             // sorat-e paye-ye khodran (j4)
const int SEARCH_SPEED = 450;     // jostojoo-ye khat-e gomshode (j4)
const float TILT_LIMIT = 35.0;    // daraje: robot-e motaharrek larzesh darad (j5: 25 bood)

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

String mode = "MANUAL";           // MANUAL / AUTO / TILT (mashin-e halat - term 3 j6)
float integral = 0.0;
float lastError = 0.0;
unsigned long lastTiltCheck = 0;  // type-e kernometr-e millis (jalase 3)

// ---------- block-e BLE (copy az jalase 6) ----------
void bleSetup() {
  BLEDevice::init("AIRO-RACER");
  BLEServer *server = BLEDevice::createServer();
  BLEService *service = server->createService(SERVICE_UUID);
  rxChar = service->createCharacteristic(RX_UUID, BLECharacteristic::PROPERTY_WRITE);
  txChar = service->createCharacteristic(TX_UUID, BLECharacteristic::PROPERTY_NOTIFY);
  txChar->addDescriptor(new BLE2902());
  service->start();
  server->getAdvertising()->start();
}

char bleRead() {
  // sar zadan be keshoo-ye RX (jalase 6): akharin harf ya 0
  String v = rxChar->getValue();
  if (v.length() > 0) {
    rxChar->setValue("");
    return v.charAt(0);
  }
  return 0;
}

void bleSend(String msg) {
  txChar->setValue(msg);
  txChar->notify();
}

// ---------- block-e MPU6050 (copy az jalase 5) ----------
void mpuSetup() {
  Wire.begin();   // SDA=21 SCL=22
  int status = mpu.begin();
  Serial.print("vaziat-e MPU (0 yani OK): ");
  Serial.println(status);
  while (status != 0) {
  }
  Serial.println("tekan nade... sefr-giri (robot SAF bashad!)");
  delay(1000);
  mpu.calcOffsets();
}

// ---------- motor-ha (block-e jalase 4 + aghab az jalase 6) ----------
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) {
  // har do charkh be jolo, har kodam ba sorat-e khodash (j4)
  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 back(int speed) {
  // hamun back-e jalase 6, in bar ba sorat-e dande
  digitalWrite(IN1, LOW);
  digitalWrite(IN2, HIGH);
  digitalWrite(IN3, LOW);
  digitalWrite(IN4, HIGH);
  ledcWrite(ENA, clampF(speed * FACTOR_LEFT, 0, 1023));
  ledcWrite(ENB, clampF(speed * 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);
}

// ---------- maghz-e khat (PID - block-e jalase 4) ----------
int errorFrom(bool l, bool m, bool r) {
  // manfi = chap, mosbat = rast (j4)
  if (l && m) {
    return -1;
  }
  if (r && m) {
    return 1;
  }
  if (l) {
    return -2;
  }
  if (r) {
    return 2;
  }
  return 0;
}

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

  if (!l && !m && !r) {
    // khat gom shod: kise-ye integral khali + charkhesh be samt-e akharin khata (j4)
    integral = 0.0;
    if (lastError > 0) {
      turnRight(SEARCH_SPEED);
    } else {
      turnLeft(SEARCH_SPEED);
    }
    return;
  }

  float error = errorFrom(l, m, r);
  integral = clampF(integral + error, -MAX_I, MAX_I);
  float derivative = error - lastError;
  lastError = error;
  float diff = KP * error + KI * integral + KD * derivative;
  tank(BASE + diff, BASE - diff);
}

// ---------- boogh (tanzim-e jalase 5) ----------
void beep(int times) {
  for (int i = 0; i < times; i = i + 1) {
    ledcWriteTone(BUZZER, 988);
    delay(120);
    ledcWriteTone(BUZZER, 0);
    delay(80);
  }
}

// ---------- protocol-e farman (jalase 6) - horuf-e kuchak ham OK ----------
void handleCommand(char c) {
  if (mode == "TILT" && c != 'S' && c != 's') {
    bleSend("aval robot ra saf kon, bad S bezan!\n");
    return;
  }
  int spd = speeds[gear];
  if (c == 'F' || c == 'f') { mode = "MANUAL"; tank(spd, spd); }
  else if (c == 'B' || c == 'b') { mode = "MANUAL"; back(spd); }
  else if (c == 'L' || c == 'l') { mode = "MANUAL"; turnLeft(spd); }
  else if (c == 'R' || c == 'r') { mode = "MANUAL"; turnRight(spd); }
  else if (c == 'S' || c == 's') { stopMotors(); mode = "MANUAL"; bleSend("stop\n"); }
  else if (c == '1') { gear = 0; bleSend("dande 1\n"); }
  else if (c == '2') { gear = 1; bleSend("dande 2\n"); }
  else if (c == '3') { gear = 2; bleSend("dande 3\n"); }
  else if (c == 'A' || c == 'a') {
    integral = 0.0;
    lastError = 0.0;
    mode = "AUTO";
    bleSend("khodran ON - PID donbal-e khat\n");
  }
  else if (c == 'M' || c == 'm') {
    stopMotors();
    mode = "MANUAL";
    bleSend("dasti ON\n");
  }
}

// ---------- alarm-e taadol (block-e jalase 5) ----------
void checkTilt() {
  float ax = mpu.getAngleX();
  float ay = mpu.getAngleY();
  if (abs(ax) > TILT_LIMIT || abs(ay) > TILT_LIMIT) {
    stopMotors();
    mode = "TILT";
    Serial.println("KHATAR! kaj shodam");
    bleSend("KHATAR: kaj shodam! saf kon va S bezan\n");
    beep(3);
  }
}

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

  pinMode(IN1, OUTPUT);
  pinMode(IN2, OUTPUT);
  pinMode(IN3, OUTPUT);
  pinMode(IN4, OUTPUT);
  ledcAttach(ENA, 1000, 10);
  ledcAttach(ENB, 1000, 10);
  ledcAttach(BUZZER, 880, 10);
  ledcWriteTone(BUZZER, 0);

  pinMode(S_LEFT, INPUT);
  pinMode(S_MID, INPUT);
  pinMode(S_RIGHT, INPUT);

  stopMotors();
  mpuSetup();
  bleSetup();
  beep(2);
  Serial.println("Path C features: amade! F/B/L/R/S + 1/2/3 + A/M");
}

void loop() {
  mpu.update();   // ghalb-e ketabkhane-ye MPU: har door (jalase 5)

  if (Serial.available() > 0) {
    handleCommand(Serial.read());   // rah-e test-e bi-gooshi (jalase 6 + Wokwi)
  }
  char c = bleRead();
  if (c != 0) {
    handleCommand(c);   // farman hamin lahze - loop hich vaght gir nemikonad
  }

  if (mode == "AUTO") {
    pidStep();          // faghat YEK ghadam PID dar har door-e loop
  }

  if (millis() - lastTiltCheck > 100) {
    lastTiltCheck = millis();
    checkTilt();
  }

  delay(10);
}
```

<div dir="rtl">

✅ **چک کن:** سه قابلیت، هر کدام جدا و در سی ثانیه: با گوشی راندنِ سه‌دنده، بعد فرمانِ A و خودران روی خط، بعد کج‌کردنِ ربات و آژیرِ تعادل.

> 🔧 **اگر کار نکرد:** بعد از فرمانِ A هیچ فرمانی اثر ندارد؟ `while (true)` داخلِ `handleCommand` مانده — حلقهٔ زندانی؛ حالتِ AUTO با متغیرِ `mode` و فقط یک `pidStep` در هر دور. آلارمِ تعادل روی زمینِ صاف الکی می‌زند؟ MPU لق است و می‌لرزد، یا آستانه خیلی حساس است: نصبِ محکم و تراز، `calcOffsets` روی زمینِ صاف، و `TILT_LIMIT` حدود ۳۵ درجه.

> 💡 **نکته:** منطقِ مسیر C را می‌توانی بدون رادیو تست کنی: `handleCommand` را موقتاً از Serial Monitor صدا بزن (همان ترفندِ فصل ۶) و فرمان‌ها را دستی بفرست. برای حالتِ TILT هم کافی است بردِ روی میز را با دست کج کنی و خروجی را ببینی — BLE و شتاب‌سنج در شبیه‌ساز اجرا نمی‌شوند.

### چالش مسیر C: چرا در TILT فقط S پذیرفته می‌شود؟

چرا در حالتِ TILT فقط فرمانِ S پذیرفته می‌شود و مثلاً F نه؟ چه سناریوی خطرناکی را می‌بندد؟

---

**جواب:** چون ربات همین حالا کج شده و در وضعیتِ نااَمن است. اگر در TILT فرمانِ F (جلو) را قبول می‌کردیم، ربات ممکن بود از لبهٔ میز یا سطحِ شیب‌دار پرت شود یا بدتر کج شود. تنها کارِ امن، ایستادن و صاف‌شدن است؛ برای همین فقط S (توقف) قبول می‌شود. راننده اول باید ربات را با دست صاف کند و S بزند تا از حالتِ خطر بیرون بیاید — بعد دوباره اختیارِ حرکت را می‌گیرد.

## تحویل milestone دو

هر مسیری که بودی، حالا نوبتِ تحویل است:

1. قابلیت‌هایت را یکی‌یکی به خانواده نشان بده — هر کدام سی ثانیه.
2. در دفترچه صفحهٔ **M2** را بنویس: کدام قابلیت‌ها تمام شدند، و دو مهمانِ ناخواندهٔ امروزت با راه‌حلشان — هورنِ کج و پیشخدمتِ گیرکرده، یا سیمِ لغزیده و آژیرِ پت‌پتی، یا حلقهٔ زندانی و سنسورِ لرزان. این‌ها ستاره‌های بخشِ «مشکلات و راه‌حل‌ها»ی مستنداتِ نهایی‌اند.
3. مسیر A و C: اعدادِ نهاییِ پیچ‌های تنظیم (`KP`، `KD`، `BASE` و بقیه) را با ستونِ «چرا این عدد» ثبت کن.

> 💡 **نکته:** اگر قابلیتِ سومت نصفه ماند، طبقِ قانونِ فصل ۷ کوچکش کن، نه اینکه بی‌پایان کِشش بدهی. یک قابلیتِ کوچکِ تمام‌شده، از یک قابلیتِ بزرگِ نصفه بهتر است.

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Feature | فیچِر | قابلیت؛ کاری که پروژه برای کاربر انجام می‌دهد و برایش امتیاز می‌گیری |
| Blocking | بلاکینگ | مسدودکننده؛ کدی که بقیهٔ برنامه را منتظر نگه می‌دارد (مثل حلقهٔ زندانی) |
| Command | کامَند | فرمان؛ پیامِ کوتاهی که به دستگاه می‌گوید چه کند |
| Dashboard | دَشبورد | داشبورد؛ صفحهٔ یک‌نگاهیِ همهٔ داده‌های زنده |
| Alert | اَلِرت | هشدار؛ اعلامِ خودکارِ یک وضعیتِ غیرعادی |
| Payload | پِی‌لود | محموله؛ باری که ربات حمل می‌کند |

## تمرین‌ها

اول چک‌لیستِ پایانِ فصل: همهٔ TODOهای اسکلت پر شده و برنامه بدون خطا اجرا می‌شود؛ قابلیت‌های milestone دو هر کدام جدا و در سی ثانیه قابلِ نمایش‌اند؛ هر دو خطای عمدیِ فصل را می‌توانی بازگو کنی (علامتش، علتش، درمانش)؛ و صفحهٔ M2 دفترچه کامل است. اگر همه بله است، برو سراغ تمرین‌ها:

- **تمرین اجباری:** milestone دو مسیرت را کامل تحویل بده — هر قابلیت را جدا (هر کدام حداکثر سی ثانیه) برای خانواده نمایش بده، و صفحهٔ M2 دفترچه را بنویس: فهرستِ قابلیت‌های تمام‌شده + دو خطای امروز (یکی سخت‌افزاری، یکی منطقی) با علت و راه‌حل. مسیر A و C: اعدادِ نهاییِ پیچ‌های تنظیم را با ستونِ «چرا این عدد» ثبت کن.
- **تمرین ستاره‌دار ⭐:** پروژه‌ات را عمداً اذیت کن و مشاهده‌ها را یادداشت کن — مسیر A لیوان را پرتر کن، مسیر B سیمِ DHT را وسطِ کار بکش (چه می‌بینی؟ چرا برنامه نمی‌میرد؟)، مسیر C وسطِ خودران ربات را بلند کن. برای هر آزار یک جمله بنویس: «سیستم چه کرد و چه باید بکند؟» این فهرست، خوراکِ مستقیمِ فصل ۱۰ است.

## در فصل بعد

پروژه‌ات حالا «کار می‌کند» — ولی هنوز نه همیشه. فصل بعد سخت‌ترین و مهندسی‌ترین فصلِ دوره است: رفعِ اشکالِ سیستماتیک با روشی که اسمش را می‌گذاریم «نصفش کن!»، و یک چک‌لیستِ پایداری که پروژهٔ تو را از «کار می‌کند» به «همیشه کار می‌کند» می‌رساند. همان دو مهمانِ ناخوانده‌ای که امروز شکار کردی، تمرینِ گرم‌کردنِ فصل بعد بودند. می‌بینمت!

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t5/s09-capstone-features (یادستان, Yaadestan)
