# آموزش ESP32 با میکروپایتون از صفر: نصب، REPL، چشمک‌زن و دکمه

برای شروع ESP32 با میکروپایتون چهار قدم لازم است: برنامهٔ رایگان Thonny را نصب کن، برد را با یک **کابل دیتا** (نه کابل فقط‌شارژ) وصل کن، از منوی Thonny فرم‌ور MicroPython را روی برد بریز، و وقتی علامت `>>>` آمد، اولین دستورت را بنویس. بعد یک LED را با کد چشمک‌زن کن و برنامه را با نام `main.py` روی خود برد ذخیره کن تا بدون کامپیوتر هم اجرا شود.

این راهنما همان مسیری را می‌رود که فصل‌های ۴، ۵ و ۸ ترم اول [خودآموز آیرو](/courses/airo) می‌روند، با همان پایه‌ها: LED روی `GPIO 25` و دکمه روی `GPIO 32`. اگر هنوز بین آردوینو و ESP32 مردّدی، اول [آردوینو یا ESP32](/blog/arduino-vs-esp32) را بخوان.

> **ایمنی.** پایه‌های ESP32 برای ۳٫۳ ولت ساخته شده‌اند و ۵ ولت را تحمل نمی‌کنند. LED را همیشه با مقاومت سری ببند، مدار را فقط وقتی USB جداست عوض کن، و اگر قطعه‌ای داغ شد یا بو داد، فوراً کابل را بکش. همه‌چیز این آموزش از درگاه USB تغذیه می‌شود؛ برق شهر موضوع هیچ آزمایشی نیست.

## چه لازم داری

| قطعه | تعداد | نکته |
|---|---|---|
| برد توسعهٔ ESP32 | ۱ | نوع DevKit با ماژول ESP32 معمولی |
| کابل USB دیتا | ۱ | بعضی کابل‌ها فقط شارژ می‌کنند |
| کامپیوتر | ۱ | ویندوز، مک یا لینوکس؛ لپ‌تاپ قدیمی هم کافی است |
| `breadboard` و سیم جامپر | ۱ دست | |
| LED قرمز و مقاومت `220Ω` | ۱ | برای چشمک‌زن |
| دکمهٔ فشاری | ۱ | برای بخش دکمه |

برد نداری؟ همهٔ قدم‌های کدنویسی این راهنما را می‌توانی در آزمایشگاه شبیه‌ساز یادستان با یک ESP32 مجازی امتحان کنی.

## قدم ۱: Thonny و تلهٔ کابل

Thonny هم ویرایشگر کد است و هم پل ارتباطی با برد. آن را از سایت رسمی‌اش، thonny.org، بگیر و با گزینه‌های پیش‌فرض نصب کن.

حالا برد را وصل کن. **اولین تله این‌جاست:** بعضی کابل‌های USB فقط سیم برق دارند و سیم دیتا ندارند. نشانه‌اش این است که چراغ برد روشن می‌شود ولی کامپیوتر هیچ واکنشی نشان نمی‌دهد. آزمون ساده: همان کابل را به گوشی بزن؛ اگر کامپیوتر گوشی را برای انتقال فایل شناخت، کابل دیتاست.

در ویندوز، Device Manager را باز کن و زیر `Ports (COM & LPT)` دنبال خطی بگرد که نام تراشهٔ USB برد را دارد، معمولاً CP2102 یا CH340، با یک شماره مثل `COM3`. اگر به‌جایش «Unknown device» با علامت زرد دیدی، باید درایور همان تراشه را از سایت سازنده‌اش نصب کنی. در مک و لینوکس معمولاً درایوری لازم نیست.

## قدم ۲: ریختن فرم‌ور MicroPython

برد هنوز پایتون نمی‌فهمد. باید **فرم‌ور** MicroPython را رویش بریزی؛ یعنی نرم‌افزار پایه‌ای که روی حافظهٔ برد می‌ماند و با خاموش‌شدن پاک نمی‌شود. Thonny این کار را خودش انجام می‌دهد:

1. در Thonny منوی `Tools` و بعد `Options` را باز کن.
2. زبانهٔ `Interpreter` را انتخاب کن.
3. از فهرست بالا `MicroPython (ESP32)` را بزن و در `Port` همان درگاه قدم ۱ را انتخاب کن.
4. روی پیوند `Install or update MicroPython` کلیک کن.
5. درگاه را انتخاب کن، نوع برد را ESP32 بگذار و `Install` را بزن.
6. صبر کن تا کار تمام شود و وسطش کابل را نکش.

اگر نصب شروع نشد یا وسطش خطا داد، دکمهٔ `BOOT` برد را نگه دار، `Install` را بزن و وقتی نوار پیشرفت راه افتاد رهایش کن. بعضی بردها برای ورود به حالت نصب این فشار را لازم دارند.

## قدم ۳: REPL، گفتگوی زنده با برد

اگر همه‌چیز درست باشد، در بخش `Shell` پایین Thonny پیغامی می‌بینی که نام MicroPython در آن هست و آخرش علامت `>>>` آمده. این حالت **REPL** است: یک خط می‌نویسی، برد همان لحظه اجرایش می‌کند و جواب را برمی‌گرداند.

```text
>>> print("salam donya")
salam donya
>>> 2 + 3
5
```

هر چه در REPL بنویسی با کشیدن کابل از بین می‌رود. برای برنامه‌ای که بماند، باید فایل بسازی.

## قدم ۴: اولین چشمک‌زن

مدار را با USB جدا ببند: از `GPIO 25` به یک مقاومت `220Ω`، از مقاومت به پایهٔ بلند LED، و پایهٔ کوتاه LED به `GND`. فصل [اولین کد: چشمک‌زن](/courses/airo/lessons/t1/s05-first-code-blink) همین مدار را قدم‌به‌قدم می‌بندد. برای اینکه بدانی کدام پایه‌ها برای چه کاری امن‌اند، [راهنمای پایه‌های ESP32](/blog/esp32-gpio-pins) را ببین.

حالا در بخش بالای Thonny، یعنی ویرایشگر فایل، بنویس:

```python
# main.py - blink an external LED on GPIO 25
# wiring: GPIO 25 -> 220 ohm -> LED long leg, LED short leg -> GND
import machine
import time

led = machine.Pin(25, machine.Pin.OUT)

while True:
    led.value(1)      # LED on
    time.sleep(0.5)
    led.value(0)      # LED off
    time.sleep(0.5)
```

- `import machine` جعبه‌ابزار سخت‌افزار را باز می‌کند و `import time` ابزارهای زمان را.
- `machine.Pin(25, machine.Pin.OUT)` پایهٔ ۲۵ را خروجی می‌کند.
- `led.value(1)` پایه را روشن و `led.value(0)` خاموش می‌کند.
- `time.sleep(0.5)` نیم ثانیه صبر می‌کند. بدون آن، برد آن‌قدر سریع روشن و خاموش می‌کند که چشم چیزی نمی‌بیند.

`Run` را بزن. برای توقف، دکمهٔ قرمز `Stop` را بزن.

**این کد را چطور آزموده‌ایم:** کد با پایتون معمولی روی کامپیوتر و با نسخه‌های ساختگی از `machine` و `time` اجرا شد و ترتیب روشن و خاموش‌شدن پایهٔ ۲۵ درست بود. روی برد واقعی اجرایش نکرده‌ایم؛ همان دستورهای `machine.Pin` و `value` است که آیرو در ترم اول به کار می‌برد.

## main.py و boot.py

برای اینکه برنامه بدون کامپیوتر اجرا شود، از منوی `File` گزینهٔ `Save as` را بزن، **`MicroPython device`** را انتخاب کن (نه `This computer`) و نام فایل را دقیقاً `main.py` بگذار. حالا برد را با یک پاوربانک روشن کن: LED خودش چشمک می‌زند.

| فایل | کی اجرا می‌شود | برای چه |
|---|---|---|
| `boot.py` | اول، هر بار که برد روشن یا ریست می‌شود | تنظیم‌های راه‌اندازی؛ معمولاً لازم نیست دستش بزنی |
| `main.py` | بعد از `boot.py` | برنامهٔ اصلی تو |
| هر نام دیگر، مثل `blink.py` | هیچ‌وقت خودکار | فقط وقتی دستی اجرایش کنی یا `import` شود |

این ترتیب را مستندات رسمی MicroPython برای ESP32 می‌گوید. ممکن است روی برد یک `boot.py` کوچک ببینی که فرم‌ور خودش گذاشته است. برنامه‌ات را در `main.py` بنویس و `boot.py` را دست‌نخورده بگذار.

یک نکته: وقتی `main.py` یک حلقهٔ بی‌پایان دارد، Thonny ممکن است بعد از ذخیره «گیر» به نظر برسد و `>>>` نیاید. برد مشغول اجرای برنامه است. `Stop` را بزن تا REPL برگردد.

## قدم ۵: خواندن یک دکمه

یک پایهٔ دکمه را به `GPIO 32` و پایهٔ آن‌طرفش را به `GND` وصل کن. اگر دکمهٔ چهارپایه داری، طوری روی `breadboard` بنشانش که شکاف وسط را بغل کند.

پایهٔ ورودی که به هیچ‌جا وصل نیست مقدار مشخصی ندارد و با نویز محیط بین ۰ و ۱ می‌پرد. راه‌حل **pull-up** داخلی است: مقاومتی درون خود ESP32 که پایه را تا وقتی دکمه رهاست روی ۱ نگه می‌دارد. دربارهٔ این «پایهٔ شناور» در [مقالهٔ دکمهٔ فشاری](/blog/pushbutton) بیشتر بخوان.

```python
# main.py - LED on GPIO 25 is on while the button on GPIO 32 is held
# button: one leg to GPIO 32, the other leg to GND (internal pull-up)
import machine
import time

button = machine.Pin(32, machine.Pin.IN, machine.Pin.PULL_UP)
led = machine.Pin(25, machine.Pin.OUT)

while True:
    if button.value() == 0:   # pressed reads 0 (pin pulled to GND)
        led.value(1)
    else:                     # released reads 1 (pull-up)
        led.value(0)
    time.sleep(0.05)
```

به **منطق وارونه** دقت کن: دکمهٔ فشرده پایه را به `GND` می‌چسباند، پس `value()` صفر می‌دهد؛ دکمهٔ رها یک. فصل [ورودی دکمه](/courses/airo/lessons/t1/s08-button-input) همین را با REPL قدم‌به‌قدم نشان می‌دهد. این کد هم مثل چشمک‌زن با نسخهٔ ساختگی `machine` آزموده شد: با ورودی‌های «رها، رها، فشرده، فشرده، رها»، LED به ترتیب خاموش، خاموش، روشن، روشن، خاموش شد.

## خطاهای رایج

| نشانه | علت محتمل | راه حل |
|---|---|---|
| چراغ برد روشن، کامپیوتر بی‌خبر | کابل فقط‌شارژ | کابل دیتا |
| «Unknown device» در Device Manager | درایور تراشهٔ USB نصب نیست | درایور CP2102 یا CH340، طبق نام تراشهٔ برد |
| نصب فرم‌ور شروع نمی‌شود | برد وارد حالت نصب نشده | نگه‌داشتن `BOOT` هنگام شروع نصب |
| `Device is busy or does not respond` | برنامهٔ دیگری درگاه را گرفته، یا `main.py` در حال اجراست | پنجره‌های اضافه را ببند و `Stop` را بزن |
| `ImportError: no module named 'machin'` | غلط تایپی در نام ماژول | نام درست: `machine` |
| `SyntaxError: invalid syntax` روی خط `if` | `=` به‌جای `==` | داخل شرط همیشه `==` |
| `IndentationError` | تورفتگی‌ها یکسان نیستند | بلوک‌های داخل `while` و `if` هم‌تراز باشند |
| برنامه با پاوربانک اجرا نمی‌شود | فایل روی کامپیوتر ذخیره شده | `Save as` و انتخاب `MicroPython device` با نام `main.py` |
| LED روشن نمی‌شود ولی خطایی نیست | LED برعکس یا سیم روی پایهٔ دیگر | پایهٔ بلند سمت مقاومت؛ شمارهٔ پایه را با کد مقایسه کن |
| دکمه همیشه فشرده یا هرگز فشرده | دکمه در جهت غلط نشسته | دکمه را ۹۰ درجه بچرخان |

یک خطای بی‌صدا هم هست: پایه‌های `GPIO 34` تا `GPIO 39` فقط ورودی‌اند و نمی‌توانند LED را روشن کنند. فصل [راه‌اندازی ESP32](/courses/airo/lessons/t1/s04-esp32-setup) در آیرو کل مسیر نصب را با عکس و چالش‌هایش آورده است، و ترم اول از همین چشمک‌زن تا یک پروژهٔ کامل با بازر و منطق جلو می‌رود.

---
Source: https://yaadestan.com/blog/esp32-micropython-getting-started (یادستان, Yaadestan)
