# فصل ۸ — پروژهٔ نهایی ۱: اسکلت

<div dir="rtl">

# فصل ۸ — پروژهٔ نهایی ۱: اسکلت

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

فصل قبل سند نوشتی؛ امروز دست‌ها کثیف می‌شوند. خروجیِ امروز چیزی است که شاید اولش عجیب به نظر برسد: برنامه‌ای که تقریباً **هیچ کاری نمی‌کند**! ولی همین «هیچِ» ارزشمند، اولین تپشِ قلبِ پروژهٔ توست — کوچک‌ترین نشانهٔ حیات که ثابت می‌کند پایه سالم است.

و یک قانونِ بزرگ برای چهار فصلِ پایانی که باید یک بار برای همیشه روشنش کنیم: از اینجا به بعد این فصل سه بخشِ موازی دارد — مسیر A، مسیر B و مسیر C — و تو **فقط بخشِ مسیرِ خودت را می‌خوانی**. لازم نیست هر سه را بخوانی؛ وقتِ تو باید صرفِ ساختن شود. بخش‌های اول و آخرِ فصل مشترک‌اند؛ وسط، مستقیم بپر سرِ مسیرِ خودت.

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

- سیم‌کشی و مونتاژِ پایهٔ مسیرت را کامل کنی (A: بازوی سروو روی ربات؛ B: ایستگاه سنسوری روی میز؛ C: نصب MPU6050 و بازر روی ربات).
- «اسکلت» پروژه‌ات را بنویسی: برنامه‌ای با ساختارِ کامل و توابعِ placeholder که اجرا می‌شود ولی هنوز کارِ اصلی را نمی‌کند — و بگویی چرا این قدم ارزشمند است.
- اولین تستِ کوچکِ موفق (تپشِ قلب) مسیرت را اجرا کنی و به‌عنوان milestoneِ یک در دفترچه ثبت کنی.
- خطای مخصوصِ مسیرت را بخوانی و رفع کنی (کامپایلِ C++، ImportErrorِ مقصدِ فایل، یا سیم‌کشیِ I2C).

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

- **از فصل ۷ (همین ترم):** سندِ طراحیِ پرشده با سه milestone — امروز M1 را تحویل می‌دهیم. سند باید جلوی دستت باشد.
- **مسیر A:** ربات ترم ۳ + Servo (ترم ۲، فصل ۸) + `ledcWrite` (فصل ۳ همین ترم) + امضای ۱-۱-۱ (ترم ۳، فصل ۸).
- **مسیر B:** WiFi و وب‌سرور (ترم ۴، فصل‌های ۱ و ۳) + `secrets.py` (ترم ۴، فصل ۶) + سنسورهای ترم ۲.
- **مسیر C:** بلوک BLE (فصل ۶) + بلوک MPU6050 (فصل ۵) + `millis` (فصل ۳ همین ترم).
- **همهٔ مسیرها:** قوانینِ ایمنیِ باتری (ترم ۳، فصل ۱) — کلیدِ خاموش هنگام سیم‌کشی.

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

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| مسیر A: ربات ترم ۳ + Servo SG90 + چوب بستنی/مقوا + کش یا چسب + لیوان کاغذی | ۱ دست | سینیِ کوچکِ مقوایی به جای بازو |
| مسیر B: ESP32 + Breadboard + DHT11 + LDR + مقاومت 10k ×۳ + HC-SR04 + Buzzer + LED قرمز + 220Ω | ۱ دست | همه از کیت ترم ۱ و ۲ |
| مسیر C: ربات ترم ۳ + MPU6050 (GY-521) + Buzzer + سیمِ بلندترِ جامپر | ۱ دست | بدون MPU: نقشهٔ B سند — `mpuSetup();` و `mpu.update();` را از اسکلت بردار (وگرنه برنامه در قفلِ `while (status != 0)` می‌ماند) و آلارم را فصل ۱۰ اضافه کن |
| باتریِ پر (A و C) + یک دستِ ذخیره | ۲ دست | اجرای تست با باتریِ ضعیف بی‌معناست |
| کامپیوتر: Arduino IDE (A و C) یا Thonny (B) + کابل USB | ۱ | — |
| سندِ طراحیِ فصل ۷ + دفترچهٔ مهندسی | ۱ | — |

> 💡 **نکته:** روشِ اجرا به مسیرت بستگی دارد. **مسیر A و C** کدشان C++ است — در Arduino IDE آپلود کن (اسکلت‌ها بی‌موتور هم اجرا می‌شوند؛ فقط BLEِ مسیر C در هیچ شبیه‌سازی نیست، به جایش `handleCommand` را از Serial Monitor صدا بزن). **مسیر B** کدش MicroPython است — با Thonny روی برد اجرا کن؛ چون سرورِ واقعی WiFi می‌خواهد، تستِ واقعی با گوشی از همه‌چیز ساده‌تر است.

> 🧪 **آزمایشگاه:** اسکلت‌ها بهترین دوستِ شبیه‌سازند، چون هنوز موتورِ واقعی لازم ندارند — ولی صادقانه بگویم فقط **یکی** از سه مسیر واقعاً در [آزمایشگاه](/lab) اجرا می‌شود.
> **مسیر A — اجرا می‌شود:** سه سنسور خط، یک سروو روی GPIO 13 و شش LED به‌جای موتورها از قبل چیده شده‌اند؛ هم سلامِ بازو و هم امضای ۱-۱-۱ همان‌جا تست‌شدنی‌اند.
> **مسیر C — اجرا نمی‌شود:** نه BLE شبیه‌سازی شده نه کتابخانهٔ MPU6050 (همان صداقتِ فصل‌های ۵ و ۶). اسکلتش را روی برد واقعی تست کن.
> **مسیر B — اجرا نمی‌شود:** شبکه در شبیه‌ساز وجود ندارد؛ تستِ واقعی با گوشی از هر چیزی ساده‌تر است.

## ۱. اسکلت: ساختمانی که اول ستون‌هایش بالا می‌رود

![تشبیهِ سه‌پنلیِ اسکلت: پنل چپ ساختمانی نیمه‌کاره با اسکلتِ فلزیِ کامل و فقط دیوارهای طبقهٔ اول؛ پنل وسط اسکلتِ کارتونیِ بدنِ انسان؛ پنل راست پنجرهٔ ویرایشگرِ کد با چند تابعِ خالیِ TODO و یک تابعِ پرشدهٔ سبز](/lesson-assets/t5-s08-capstone-skeleton/prompt/01-image-skeleton-metaphor.png)

به ساختمان‌سازها نگاه کن: اول کل اسکلتِ فلزی را بالا می‌برند — همه ستون‌ها و سقف‌ها — بعد سراغِ دیوار و پنجره می‌روند. هیچ سازندهٔ عاقلی طبقهٔ اول را کامل با کاغذدیواری تمام نمی‌کند تا بعد برود سراغِ ستون‌های طبقهٔ دوم! برنامه‌نویس‌ها هم همین کار را می‌کنند و اسمش را گذاشته‌اند **اسکلتِ کد**: همهٔ توابعی را که پروژه لازم دارد از همین امروز تعریف می‌کنیم — با اسمِ درست و ورودی/خروجیِ درست — ولی بدنهٔ بیشترشان فعلاً خالی است؛ فقط یک کامنتِ `TODO` تویش نشسته که می‌گوید «اینجا فصل ۹ پر می‌شود». تابعِ خالی چیز جدیدی نیست — تعریفِ تابع را از ترم ۲ و نسخهٔ C++اش را از فصل ۳ بلدی.

چرا این کار طلاست؟ سه دلیل:

1. **کامپایل‌شدن و اجراشدن، خودش اولین تست است** — اگر اسکلت بالا آمد، یعنی سیم‌کشی، برد، زبان و ساختار همه سالم‌اند؛ هر مشکلی بعداً پیدا شود، می‌دانیم مالِ دیوارهاست نه ستون‌ها.
2. نقشهٔ سندِ طراحی‌ات به کدِ واقعی تبدیل می‌شود — هر تابعِ خالی، یک قولِ مشخص برای فصل ۹.
3. از همین امروز چیزِ قابلِ نمایشی داری — همان قانونِ طلاییِ فصل قبل.

> ⚠️ **مواظب باش:** یک قانونِ ایمنی مخصوصِ مسیرهای ربات‌دار (A و C): در اسکلت، تابعِ حرکتِ موتورها را **عمداً خالی** می‌گذاریم و اولِ کار `stopMotors` صدا می‌زنیم — رباتی که هنوز مغزش کامل نیست، حقِ حرکت ندارد. اسم این عادت را بگذار «قانونِ موتورهای ساکت».

## چالش: چرا اسکلت را رد نکنیم؟

اگر اسکلت را رد کنیم و مستقیم قابلیتِ اصلی را بنویسیم و کار نکند، چرا پیداکردنِ مقصر سخت‌تر است؟

---

**جواب:** چون چند مظنون داریم — شاید سیم‌کشی خراب است، شاید ساختار، شاید خودِ قابلیت. با اسکلت اول همهٔ این مظنون‌ها را (سیم، برد، زبان، ساختار) یک‌بار تأیید می‌کنیم؛ بعد اگر قابلیتی خراب شود، فقط یک مظنون می‌ماند: خودِ همان قابلیت.

حالا بپر سرِ بخشِ مسیرِ خودت: A از بخشِ ۲، B از بخشِ ۳، C از بخشِ ۴.

## ۲. مسیر A: بازویی که سلام می‌دهد

اول مکانیک. بازوی پیشخدمتِ ما ساده و مؤدب است: یک چوب بستنی (یا تکه‌مقوای سفت) را عمود به هورنِ سروو ببند — با پیچِ هورن یا کش و چسب — و سرِ دیگرش یک سینیِ کوچکِ مقوایی بچسبان که لیوان کاغذی رویش جا شود. سروو را با کش یا چسبِ دوطرفه جلوی ربات محکم کن؛ لق نباشد، چون بازوی لرزان یعنی لیوانِ پرنده! سیم‌کشیِ سروو سه سیم بیشتر نیست، ولی یک نکتهٔ حیاتی دارد: تغذیهٔ سروو از خروجیِ +5V ماژولِ L298N، **نه** از پایهٔ 3V3 برد — سروو موقعِ حرکت جریانِ زیادی می‌کشد و اگر از برد تغذیه شود، ESP32 را به ریست می‌اندازد (همان Brownoutِ آشنای ترم ۳). و طبقِ قانونِ همیشگی: GND مشترک.

![سیم‌کشیِ بازوی مسیر A در قابِ سبز نئونی: شاسیِ دوچرخ با سروو SG90 جلوی ربات، بازوی چوب‌بستنی با سینیِ مقوایی و لیوان کاغذی؛ سیمِ نارنجیِ سیگنال به GPIO 13، سیمِ قرمز به خروجیِ +5V ماژولِ L298N با هشدارِ «NOT 3V3!»، و سیمِ قهوه‌ای به ریلِ GND مشترک](/lesson-assets/t5-s08-capstone-skeleton/prompt/02-image-path-a-arm-wiring.png)

</div>

| Servo wire | Connects to | Note |
|---|---|---|
| Orange (signal) | ESP32 GPIO 13 | PWM 50Hz — standard pin map |
| Red (VCC) | L298N +5V output | NOT the ESP32 3V3 pin! |
| Brown (GND) | Common GND rail | shared with ESP32 and L298N |

<div dir="rtl">

حالا کد. Arduino IDE را باز کن، sketch جدید با اسمِ `waiter_skeleton` بساز و اسکلت را تایپ کن. موقع تایپ به سه چیز دقت کن: اول، بالای فایل همهٔ پین‌ها با `const int` — همان پین‌مپِ ترم ۳ به‌علاوهٔ سروو روی ۱۳. دوم، تابعِ `servoWrite`: سروو همان PWM پنجاه‌هرتزیِ ترم ۲ است، فقط این بار با `ledcWrite` فصل ۳ می‌نویسیمش. سوم، توابعِ خالی با TODO: `tank`، `errorFrom`، `pidStep` و `armServe` — قول‌های فصل ۹. تنها توابعِ واقعیِ امروز: `stopMotors`، `armCarry` و `atStation` که همان امضای ۱-۱-۱ ترم ۳ است.

تایپ که تمام شد کامپایل بزن — و عمداً در تلهٔ همیشگیِ C++ می‌افتیم؛ بعد از `armCarry()` در setup سمی‌کالن نگذاشته‌ایم:

</div>

```text
waiter_skeleton:86:13: error: expected ';' before 'delay'
```

<div dir="rtl">

خطِ ۸۶، «قبل از delay یک `;` کم است». دقت کن که کامپایلر اسمِ `delay` را از خطِ *بعد* می‌آورد — چون تازه آنجا فهمیده جملهٔ قبلی تمام نشده. (اگر توضیح‌های بالای فایلت کمتر یا بیشتر باشد، شمارهٔ خط کمی فرق می‌کند.) این را از فصل ۲ می‌شناسی: خطای کامپایل یعنی برنامه هنوز اجرا نشده؛ خطر ندارد، فقط ترجمه نشده. سمی‌کالن را می‌گذاری، کامپایل سبز، Upload... و لحظهٔ تپشِ قلب: بازو آرام به ۹۰ می‌رود، بعد یک سلامِ کوتاه به ۶۰ و برگشت؛ و در Serial Monitor پیامِ `Path A skeleton: zende-am!` و بعد رگبارِ گزارشِ سنسورهای خط.

کد کامل در `path-a/waiter_skeleton.ino` است:

</div>

```cpp
// Term 5 - Session 08 - Path A: eskelet-e "robat-e pishkhedmat-e khanegi" (C++)
// Milestone 1: compile + upload + tapesh-e ghalb (bazoo salam midahad, motor-ha sakat)
// pin-ha az pin-map-e sabet-e dore: L298N-e term 3 + servo rooye GPIO 13

// ---------- 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 (T2 j8)

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

// ---------- servo ba PWM 50Hz (T2 j8 + ledc-e T5 j3) ----------
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, livan amn
}

void armServe() {
  // TODO (jalase 9): harekat-e NARAM be halat-e tahvil va bargasht
  Serial.println("TODO: armServe");
}

// ---------- motor-ha (block-e jalase 4 - jalase 9 por mishavad) ----------
void tank(float left, float right) {
  // TODO (jalase 9): har do charkh be jolo, har kodam ba sorat-e khodash (j4)
  // dar eskelet AMDAN khali ast: robot bi-barname harekat nakonad!
}

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

// ---------- maghz-e khat (PID-e jalase 4 - jalase 9 por mishavad) ----------
int errorFrom(bool l, bool m, bool r) {
  // TODO (jalase 9): hamun jadval-e jalase 4 (-2..+2)
  return 0;
}

void pidStep() {
  // TODO (jalase 9): P + I + D -> tank (block-e jalase 4)
}

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();   // ghanun-e aval: harekat faghat ba dastur!

  Serial.println("Path A skeleton: zende-am!");
  armCarry();
  delay(600);
  servoWrite(60);   // salam!
  delay(600);
  armCarry();
  Serial.println("test-e bazoo OK - Milestone 1 pass shod");
}

void loop() {
  // eskelet: faghat gozaresh, bedun-e harekat
  Serial.print("sensor-haye khat: ");
  Serial.print(digitalRead(S_LEFT));
  Serial.print(digitalRead(S_MID));
  Serial.print(digitalRead(S_RIGHT));
  if (atStation()) {
    Serial.print("  <- istgah! (1-1-1)");
  }
  Serial.println("");
  delay(500);
}
```

<div dir="rtl">

ربات را با دست روی نوارِ عرضیِ ایستگاه بگذار — پیامِ `istgah! (1-1-1)` باید ظاهر شود. موتورها؟ ساکتِ ساکت، همان‌طور که قانون گفت.

✅ **چک کن:** بازو سلام می‌دهد، Serial Monitor هر نیم‌ثانیه سه سنسور خط را گزارش می‌دهد، و روی نوارِ ایستگاه پیامِ ۱-۱-۱ می‌آید. این milestoneِ یکِ توست — با سند مقایسه کن و تیک بزن، بعد بپر به بخشِ پایانی (بخشِ ۵).

> 🔧 **اگر کار نکرد:** اگر با اولین حرکتِ سروو برد ریست شد و پیامِ `Brownout detector was triggered` آمد، سروو از 3V3 تغذیه شده — سیمِ قرمز را به +5V ماژولِ L298N ببر و GND مشترک را چک کن. اگر سروو در ۹۰ درجه صاف نمی‌ایستد یا می‌لرزد، اول `armCarry` را صدا بزن، بعد هورن را باز کن و در حالتِ تراز دوباره ببند.

## چالش (مسیر A): سرووِ روی 3V3

اگر سروو را از 3V3 برد تغذیه کنی، اولین باری که بازو حرکت کند احتمالاً چه اتفاقی برای ESP32 می‌افتد و اسمِ آن پیامِ آشنا چیست؟

---

**جواب:** سروو موقعِ حرکت جریانِ زیادی می‌کشد و ولتاژِ برد یک لحظه افت می‌کند؛ ESP32 ریست می‌شود و پیامِ آشنای `Brownout detector was triggered` می‌آید — همان چیزی که ترم ۳ دیدیم. راه‌حل: تغذیهٔ سروو از +5V ماژولِ L298N.

## ۳. مسیر B: ایستگاهی که در گوشی می‌گوید «زنده‌ام»

مسیر B امروز روی میز ساخته می‌شود — بدون ربات، بدون باتریِ موتور؛ تغذیه فقط USB. Breadboard بزرگ را بگذار و چهار محله برایش بساز: DHT11 (دیتا به GPIO 16)، مقسمِ LDR با مقاومتِ 10k (وسطش به GPIO 35 — همان مدارِ ترم ۲، فصل ۴)، HC-SR04 (TRIG به ۵، ECHO با مقسمِ ولتاژ به ۱۸ — یا ماژولِ HC-SR04P مستقیم)، و محلهٔ اعلامِ خطر: Buzzer روی GPIO 4 و LED قرمز با مقاومتِ 220 روی GPIO 25.

![سیم‌کشیِ ایستگاهِ مسیر B در قابِ فیروزه‌ای: ESP32 روی Breadboardِ بزرگ با چهار محله — DHT11 به GPIO 16، مقسمِ LDR با مقاومتِ 10k به پایهٔ آنالوگ ۳۵، HC-SR04 با TRIG به ۵ و ECHO از مقسم به ۱۸، و گوشهٔ هشدار با Buzzer روی ۴ و LED قرمز روی ۲۵؛ یک ریلِ GND مشترک و گوشی‌ای که صفحهٔ وب را نشان می‌دهد](/lesson-assets/t5-s08-capstone-skeleton/prompt/03-image-path-b-station-wiring.png)

</div>

| Part | Part pin | ESP32 | Note |
|---|---|---|---|
| DHT11 module | DATA | GPIO 16 | 3-pin module from Term 2 kit |
| LDR + 10k divider | middle node | GPIO 35 | input-only ADC pin (works with WiFi) |
| HC-SR04 | TRIG | GPIO 5 | — |
| HC-SR04 | ECHO | GPIO 18 | through the Term-2 voltage divider (or HC-SR04P) |
| Passive buzzer | + | GPIO 4 | alert sound (next session) |
| Red LED | anode | 220 ohm -> GPIO 25 | alert light |
| All parts | GND / VCC | GND / as in Term 2 | common GND rail |

<div dir="rtl">

امشب فقط DHT و LDR و HC-SR04 را سیم‌کشی می‌کنیم ولی هنوز نمی‌خوانیمشان — در اسکلت، توابعشان placeholder است و اعدادِ قلابی برمی‌گردانند. و یک قدمِ مخصوصِ مسیر B قبل از هر چیز: از فصل ۱ تا ۶ این ترم روی برد تو فریمورِ C++ نشسته و Thonny آن را نمی‌شناسد؛ اول مثل فصل ۱ همین ترم — همان فلشِ آشنای ترم ۱، فصل ۴ — فریمورِ MicroPython را برگردان تا REPL دوباره سلام کند. مسیر B از اینجا تا آخرِ دوره تماماً MicroPython است.

تمرکزِ milestoneِ یک روی پرریسک‌ترین ستون است: **سرور**. Thonny را باز کن و دو فایل بساز. اول `secrets.py` — همان قانونِ آهنینِ ترم ۴: اسمِ WiFi، رمز و کلیدِ Gemini فقط اینجا، و این فایل هیچ‌وقت و هیچ‌جا فرستاده نمی‌شود؛ قالبش در `path-b/secrets_template.py` است. دوم فایلِ اصلی — کد کامل در `path-b/assistant_skeleton.py`. ساختارش را ببین: چهار تابعِ سنسور و AI با TODO، تابعِ `build_page` که فعلاً یک HTML ساده می‌سازد، بلوکِ اتصالِ WiFi ترم ۴، و حلقهٔ سرورِ socket که هر درخواست را جواب می‌دهد و موقعِ هر بازدید LED قرمز را یک لحظه روشن می‌کند — چشمکِ ملاقات!

اجرا می‌کنی و... خطای قرمز:

</div>

```text
Traceback (most recent call last):
  File "<stdin>", line 9, in <module>
ImportError: no module named 'secrets'
```

<div dir="rtl">

آشناست؟ همان `ImportError` معروفِ ترم ۳ که سراغِ `robot.py` آمده بود، این بار سراغِ `secrets`. من secrets.py را ساختم ولی روی **کامپیوتر** ذخیره کردم، نه روی **برد** — و MicroPython فقط حافظهٔ خودِ برد را می‌گردد. Save as، مقصد MicroPython device، اسم دقیقاً `secrets.py`. دوباره اجرا: چاپ می‌شود «dar hal-e vasl shodan...»، بعد IP می‌آید. همین IP را در مرورگرِ گوشی بزن (گوشی روی همان WiFi خانه) — صفحهٔ «Dastyar-e otagh: zende-am!» بالا می‌آید و هم‌زمان LED قرمز چشمکِ ملاقات می‌زند.

کد کامل در `path-b/assistant_skeleton.py` است:

</div>

```python
# Term 5 - Session 08 - Path B: eskelet-e "dastyar-e hooshmand-e otagh" (MicroPython)
# Milestone 1: WiFi vasl + web server-e zende + safhe-ye "zende-am" dar gooshi
# chera MicroPython? kol-e jabe-abzar-e web/AI ra term 4 ba hamin zaban sakhti!
import network
import socket
import time
from machine import Pin

from secrets import WIFI_SSID, WIFI_PASS   # secrets.py joda - term 4 j6

led_alert = Pin(25, Pin.OUT)   # LED-e ghermez: felan cheragh-e "darkhast resid"

# ---------- sensor-ha: placeholder (jalase 9 vaghei mishavand) ----------
def read_temp_hum():
    # TODO (jalase 9): DHT11 rooye GPIO 16
    return (0, 0)

def read_light():
    # TODO (jalase 9): LDR rooye GPIO 35 (0..4095)
    return 0

def read_distance_cm():
    # TODO (jalase 9): HC-SR04 (TRIG=5, ECHO=18)
    return -1

def ask_ai(question):
    # TODO (jalase 9): olgu-ye Gemini-e term 4 j9
    return "AI dar Milestone 2 vasl mishavad"

def build_page():
    # felan faghat yek safhe-ye sade - dashboard-e vaghei dar jalase 9
    html = """<!DOCTYPE html>
<html><head><meta charset="utf-8"><title>AIRO</title></head>
<body style="font-family:sans-serif;text-align:center">
<h1>Dastyar-e otagh: zende-am!</h1>
<p>Milestone 1 pass shod - Path B</p>
</body></html>"""
    return html

# ---------- WiFi (term 4 j1) ----------
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])
print("in IP ra dar morurgar-e gooshi bezan (gooshi rooye HAMIN shabake bashad)")

# ---------- web server (term 4 j3) ----------
addr = socket.getaddrinfo("0.0.0.0", 80)[0][-1]
server = socket.socket()
server.bind(addr)
server.listen(1)
print("server amade ast - Milestone 1: tapesh-e ghalb!")

while True:
    conn, client = server.accept()
    request = conn.recv(1024)
    led_alert.value(1)   # cheshmak: yek nafar safhe ra did
    conn.send("HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\n\r\n")
    conn.send(build_page())
    conn.close()
    led_alert.value(0)
```

<div dir="rtl">

و قالبِ `secrets.py` در `path-b/secrets_template.py`:

</div>

```python
# Term 5 - Session 08 - Path B - secrets_template.py
# 1) in file ra ba esm-e "secrets.py" rooye board zakhire kon (term 4 j6)
# 2) meghdar-ha ra ba male KHODET avaz kon
# 3) HICH VAGHT in file ra be kasi nade, jayi post nakon, dar video neshan nade!
WIFI_SSID = "esm-e-wifi-khane"
WIFI_PASS = "ramz-e-wifi"
GEMINI_API_KEY = "kelid-e-API-e-khodet"
```

<div dir="rtl">

✅ **چک کن:** هر رفرشِ گوشی، دست‌کم یک چشمکِ کوتاهِ LED — یعنی مسیرِ کاملِ گوشی ← WiFi ← ESP32 ← جواب دارد کار می‌کند. این milestoneِ یکِ توست: سیم‌کشیِ کامل، secretsِ امن روی برد، سرورِ تپنده. تیک بزن و بپر به بخشِ پایانی (بخشِ ۵).

> 🔧 **اگر کار نکرد:** اگر Thonny برد را نمی‌بیند یا REPL نمی‌آید، هنوز فریمورِ C++ روی برد است — MicroPython را دوباره فلش کن (فصل ۱ همین ترم / ترم ۱، فصل ۴)، و Arduino IDE و Serial Monitorش را ببند چون پورت یک صندلی دارد. اگر صفحه در گوشی باز نمی‌شود، گوشی و ESP32 را روی یک شبکه بگذار و IP را حرف‌به‌حرف از Shell بردار.

## چالش (مسیر B): چرا اول سرور؟

چرا milestoneِ یک را «سرورِ زنده» گذاشتیم و نه «خواندنِ سنسورها»؟ کدام‌یک ریسکِ ناشناختهٔ بیشتری داشت؟

---

**جواب:** سرور و WiFi ریسکِ ناشناختهٔ بیشتری دارند (اتصال به شبکه، IP، socket) در حالی که خواندنِ سنسورها را از ترم ۲ بلدیم و مطمئن‌تریم. مهندس اول سراغِ پرریسک‌ترین قسمت می‌رود تا اگر قرار است جایی بترکد، زودتر و روی اسکلت بترکد، نه آخرِ کار.

## ۴. مسیر C: گوشی وصل می‌شود، ربات جواب می‌دهد

مسیر C امروز دو مهمان روی ربات سوار می‌کند. اول MPU6050: با چسبِ دوطرفه یا پیچ، **صاف و تراز** وسطِ شاسی، موازیِ کف — کج نصبش کنی، ربات سالم را هم «واژگون» گزارش می‌دهد! چهار سیم بیشتر ندارد: همان جفتِ I2C آشنای ترم ۲ (پایه‌های ۲۱ و ۲۲). دوم Buzzer روی GPIO 4 — آژیرِ آینده. باتریِ موتورها موقعِ همهٔ این سیم‌کشی‌ها: خاموش، طبقِ آیینِ ترم ۳.

![نصبِ MPU6050 و بازرِ مسیر C در قابِ بنفش: نمای بالای شاسیِ دوچرخ با MPU6050 صاف و تراز وسطِ شاسی و نشانِ «LEVEL!»؛ چهار سیم VCC 3V3، GND، SDA به GPIO 21، SCL به GPIO 22، و بازر روی GPIO 4؛ در گوشه نصبِ کجِ غلط با ضربدرِ قرمز در برابر نصبِ صافِ درست با تیکِ سبز](/lesson-assets/t5-s08-capstone-skeleton/prompt/04-image-path-c-mpu-mount.png)

</div>

| MPU6050 (GY-521) pin | ESP32 | Note |
|---|---|---|
| VCC | 3V3 | GY-521 board is 3V3-friendly |
| GND | GND | common ground |
| SDA | GPIO 21 | same I2C bus as the Term-2 OLED |
| SCL | GPIO 22 | — |
| Buzzer + / − | GPIO 4 / GND | alarm voice of the robot |

<div dir="rtl">

کدِ اسکلتِ مسیر C ساختمانِ بلندتری دارد، ولی نترس — دو طبقه‌اش را قبلاً ساخته‌ای و فقط کپی می‌کنی: **بلوک BLE از فصل ۶** (همان دکه و کشوهای RX/TX؛ فقط اسمِ دستگاه را `AIRO-RACER` می‌گذاریم که با رباتِ فصل ۶ اشتباه نشود) و **بلوک MPU6050 از فصل ۵** (همان کتابخانهٔ MPU6050_light: چاپِ عددِ وضعیت، یک ثانیه سکون و بعد صفرگیریِ `calcOffsets` — ربات موقعِ صفرگیری صاف و بی‌حرکت باشد! — و `mpu.update()` که مثل فصل ۵ در هر دورِ حلقه می‌زند). طبقه‌های جدید همه placeholder اند: `tank` خالی — قانونِ موتورهای ساکت — و `handleCommand` که فعلاً فقط echo می‌کند: هر حرفی بفرستی، جواب می‌دهد «fahmidam». راهِ تستِ بی‌گوشیِ فصل ۶ (فرمان از Serial Monitor) هم سرِ جایش است.

آپلود و Serial Monitor باز... و همان خطِ اول، خبرِ بد:

</div>

```text
vaziat-e MPU (0 yani OK): 2
```

<div dir="rtl">

عددِ وضعیت باید صفر باشد و ۲ آمده — و برنامه طبقِ همان قراردادِ فصل ۵، تا سنسور جواب ندهد از صفرگیری جلوتر نمی‌رود. خطای قرمزی در کار نیست؛ کد هم کلمه‌به‌کلمه مالِ فصل ۵ است — پس مشکل **سیم** است: SDA و SCL جابه‌جا زده شده‌اند و مکالمهٔ I2C اصلاً شکل نگرفته. دو سیم را جابه‌جا می‌کنی — ۲۱ به SDA، ۲۲ به SCL — ریست، و این بار `vaziat-e MPU: 0`، صفرگیری، و هر ثانیه یک زاویهٔ زنده. حالا اپِ ترمینالِ BLE گوشی را مثل فصل ۶ وصل می‌کنی — این بار به `AIRO-RACER`: ربات را کج می‌کنی، عددِ زاویه بالا و پایین می‌رود؛ حرفِ X می‌فرستی و `fahmidam: X` برمی‌گردد.

کد کامل در `path-c/racer_skeleton.ino` است:

</div>

```cpp
// Term 5 - Session 08 - Path C: eskelet-e "robat-e mosabeghe-i BLE" (C++)
// Milestone 1: gooshi vasl mishavad (echo) + zaviye-ye MPU chap mishavad + motor-ha sakat
// block-haye BLE (jalase 6) va MPU (jalase 5) hamun "ghete-haye amade"-ye khodat hastand

#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);           // hamun ketabkhane-ye MPU6050_light-e 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

// ---------- block-e BLE (copy az jalase 6 - esm-e jadid: AIRO-RACER) ----------
void bleSetup() {
  BLEDevice::init("AIRO-RACER");   // esm-e jadid ke ba robot-e jalase 6 eshtebah nashavad
  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("");   // keshoo ra khali kon baraye farman-e badi
    return v.charAt(0);
  }
  return 0;
}

void bleSend(String msg) {
  // javab be gooshi: dar keshoo-ye TX bogzar va khabar bede (jalase 6)
  txChar->setValue(msg);
  txChar->notify();
}

// ---------- block-e MPU6050 (copy az jalase 5) ----------
void mpuSetup() {
  Wire.begin();   // SDA=21 SCL=22 (hamun I2C-e term 2)
  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: placeholder ----------
void tank(float left, float right) {
  // TODO (jalase 9): block-e jalase 4
  // dar eskelet AMDAN khali ast: robot bi-farman harekat nakonad!
}

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

void handleCommand(char c) {
  // TODO (jalase 9): protocol-e kamel (F/B/L/R/S + 1/2/3 + A/M)
  Serial.print("farman resid: ");
  Serial.println(c);
  bleSend(String("fahmidam: ") + c + "\n");
}

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

unsigned long lastReport = 0;   // type-e kernometr-e millis (jalase 3)

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(BUZZER, 880, 10);  // hamun tanzim-e azhir-e jalase 5
  ledcWriteTone(BUZZER, 0);     // sokut

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

  stopMotors();   // ghanun-e aval: harekat faghat ba farman!

  mpuSetup();
  bleSetup();
  beep(2);
  Serial.println("Path C skeleton: zende-am! esm-e BLE: AIRO-RACER");
}

void loop() {
  mpu.update();   // ghalb-e ketabkhane-ye MPU: har door bezan (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);
  }

  if (millis() - lastReport > 1000) {
    lastReport = millis();
    float angle = mpu.getAngleX();
    Serial.print("zaviye: ");
    Serial.println(angle);
    bleSend(String("zaviye: ") + String(angle) + "\n");
  }
  delay(10);
}
```

<div dir="rtl">

✅ **چک کن:** عددِ زاویه با کج‌کردنِ ربات نفس می‌کشد و گوشی echo می‌گیرد. این milestoneِ یکِ توست: BLE echo + زاویهٔ زنده + موتورهای ساکت. تیک بزن و برو بخشِ پایانی.

> 🔧 **اگر کار نکرد:** اگر `vaziat-e MPU` غیرصفر است و برنامه از صفرگیری جلوتر نمی‌رود، سیمِ SDA/SCL جابه‌جاست یا شل — قانونی را که این باگ یادمان داد در دفترچه بنویس: **عددِ وضعیتِ غیرصفر یعنی مکالمهٔ I2C شکل نگرفته — اول سیم، بعد شک به قطعه.** اگر گوشی `AIRO-RACER` را نمی‌بیند، برد را ریست و بلوتوثِ گوشی را خاموش/روشن کن (همان چک‌لیستِ فصل ۶).

## چالش (مسیر C): چرا echo، نه موتور؟

چرا در اسکلت، `handleCommand` را فقط echo گذاشتیم و مستقیم به موتورها وصل نکردیم؟ دو دلیل بگو — یکی ایمنی، یکی مهندسی.

---

**جواب:** ایمنی: قانونِ موتورهای ساکت — ربات با مغزِ ناقص نباید حرکت کند و ممکن است بی‌کنترل برود. مهندسی: با echo اول مطمئن می‌شویم مسیرِ گوشی ← BLE ← برد سالم است؛ اگر مستقیم به موتور وصل می‌کردیم و کار نمی‌کرد، معلوم نبود مقصر BLE است یا موتور.

## ۵. تحویل milestone یک

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

اگر milestoneات عقب ماند ایراد ندارد؛ قبل از فصل بعد تمامش کن، چون فصل ۹ روی این پایه دیوار می‌چیند: PID و چرخهٔ تحویل برای A، داشبورد و هشدار و گزارشِ AI برای B، راندن و خودران و آلارم برای C. اسکلت‌ها منتظرند گوشت بگیرند!

✅ **چک کن (قانونِ طلاییِ امروز):** موتورها در کل فصل حتی یک بار بی‌فرمان حرکت نکرده‌اند — قانونِ موتورهای ساکت رعایت شده.

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| Skeleton | اِسکِلِتِن | اسکلت؛ ساختارِ کاملِ برنامه با بدنه‌های هنوز خالی |
| Placeholder | پلِیس‌هولدِر | جانگه‌دار؛ تابع/مقدارِ موقت تا نسخهٔ واقعی برسد |
| TODO | تودو | یادداشتِ «باید انجام شود» داخلِ کد |
| Heartbeat | هارت‌بیت | تپشِ قلب؛ کوچک‌ترین نشانهٔ حیاتِ سیستم |
| Upload | آپلود | فرستادنِ برنامهٔ کامپایل‌شده روی برد |
| Echo | اِکو | پژواک؛ برگرداندنِ همان چیزی که رسیده، برای تستِ ارتباط |

## تمرین‌ها

- **تمرین اجباری:** milestoneِ یکِ مسیرت را کامل تحویل بده: تپشِ قلب را به یکی از اعضای خانواده در حداکثر سی ثانیه نمایش بده، در دفترچه صفحهٔ «M1» را ثبت کن (تاریخ، چه چیزی کار می‌کند، خطای امروز + راه‌حلش) و طرحِ سیم‌کشیِ مسیرت را با دست بکش.
- **تمرین ستاره‌دار ⭐:** یکی از توابعِ TODO مسیرت را انتخاب کن و *فقط روی کاغذ* بنویس فصل بعد داخلش چه خواهد آمد — ورودی، خروجی، و سه خط منطقِ اصلی به زبانِ آدمیزاد. فصل بعد کاغذت را با کدِ واقعی مقایسه کن و در دفترچه بنویس چقدر نزدیک زدی.

## در فصل بعد

اسکلت‌ها گوشت می‌گیرند! فصل ۹ روی همین پایه‌ای که امروز ساختی قابلیت‌های اصلی را سوار می‌کند — یکی‌یکی، هر کدام جدا تست‌شدنی. مسیر A چرخهٔ تحویل با PID نرم، مسیر B داشبوردِ زنده و گزارشِ AI، مسیر C راندن و خودران و آلارمِ تعادل. توابعِ TODO منتظرِ فصل بعدند — می‌بینمت!

</div>

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