# فصل ۳ — ورودی آنالوگ: پتانسیومتر

<div dir="rtl">

# فصل ۳ — ورودی آنالوگ: پتانسیومتر

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

دو فصل است داری «خروجی» می‌سازی: LED نفس کشید و با duty هر روشنایی‌ای که خواستی ساختی. ولی یک چیز این وسط یک‌طرفه است — همه‌اش ما به ربات دستور می‌دهیم. در این فصل ورق برمی‌گردد: ربات برای اولین بار به دستِ تو گوش می‌دهد. اولین قطعهٔ کیت ترم ۲ باز می‌شود — پتانسیومتر، همان ولوم — و آخر فصل دو چیز ساخته‌ای: یک دیمر واقعی که با چرخش ولوم نور LED را نرم کم و زیاد می‌کند، و یک «پیانوی چرخان» که صدای Buzzer را زیر و بم می‌کند. قهرمان فصل این است:

![برش داخلی یک پتانسیومتر چرخان: نوار مقاومتی نعل‌اسبی که دو سرش به 3V3 و GND برچسب خورده، بازوی کوچک wiper که روی نوار سُر می‌خورد و به پایهٔ وسط با برچسب GPIO 34 وصل است، و فلش چرخشی که جابه‌جایی wiper را با چرخش سر نشان می‌دهد](/lesson-assets/t2-s03-adc-potentiometer/prompt/02-image-potentiometer-inside.png)

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

- توضیح بدهی ADC چه کاری می‌کند («مترجم ولتاژ به عدد») و چرا بازهٔ خروجی‌اش ۰ تا ۴۰۹۵ است.
- پتانسیومتر را درست سیم‌کشی کنی و بگویی چرا پایهٔ وسطش به GPIO 34 می‌رود.
- توضیح بدهی خط `pot.atten(ADC.ATTN_11DB)` چه مشکلی را حل می‌کند و بدون آن چه می‌بینیم.
- تابع `map_value` را با استدلال نسبت خودت بسازی و درستی‌اش را با چند تست `print` نشان بدهی.
- با چرخاندن ولوم، روشنایی LED و فرکانس Buzzer را زنده کنترل کنی.

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

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

- **از فصل ۱:** تعریف تابع، پارامتر و `return` — ستارهٔ امروز یک تابع با پنج پارامتر است.
- **از فصل ۲:** PWM و duty در بازهٔ ۰ تا ۱۰۲۳ — خروجی ولوم نور همین است.
- **از ترم ۱، فصل ۶ و ۷:** متغیر، `print` و حلقهٔ `while True`.
- **از ترم ۱، فصل ۱۰:** Buzzer و تغییر زیر و بمی صدا با `freq()`.

لوازم این فصل — اولین قطعهٔ کیت ترم ۲ امروز باز می‌شود:

| قطعه / ابزار | تعداد | جایگزین |
|---|---|---|
| ESP32 DevKit سی‌پین + کابل USB دیتا | ۱ | — |
| Breadboard بزرگ | ۱ | — |
| پتانسیومتر 10k (کیت ترم ۲) | ۱ | هر پتانسیومتر چرخان از 5k تا 100k جواب می‌دهد |
| LED قرمز + مقاومت ۲۲۰ اهم | ۱ | هر رنگ LED دیگر |
| Buzzer پسیو | ۱ | بدون آن، فقط بخش «پیانوی چرخان» حذف می‌شود |
| سیم جامپر | حدود ۸ | — |

## ۱. دنیای «چقدر»

به ولوم اسپیکر یا هدفون نگاه کن: وقتی می‌چرخانی‌اش، صدا پله‌پله زیاد نمی‌شود — نرم و پیوسته بالا می‌رود. یا دستهٔ بازی: فکر می‌کنی جوی‌استیک فقط هشت جهت دارد؟ نه! در بازی‌های مسابقه‌ای هرچه استیک را بیشتر خم کنی، ماشین تندتر می‌پیچد. کنسول دقیقاً می‌داند **چقدر** خم کرده‌ای، نه فقط کدام طرف.

![دو پرده: دستی که ولوم گرد اسپیکر را نرم می‌چرخاند و موج‌های صدا کم‌کم بزرگ می‌شوند، و استیک آنالوگ دستهٔ بازی که نیمه‌خم شده و ماشین روی صفحه دقیقاً با همان زاویه می‌پیچد](/lesson-assets/t2-s03-adc-potentiometer/prompt/01-image-volume-and-joystick.png)

این «چقدر» همان دنیای آنالوگ است که فصل قبل تعریفش کردیم: پیوسته، با بی‌نهایت حالت میانی. و امروز یاد می‌گیریم همین «چقدر» را بخوانیم.

## ۲. پتانسیومتر: شیر ولتاژ

پتانسیومتر در واقع همان ولوم است — یک مقاومت که مقدارش با چرخاندن عوض می‌شود. از ترم ۱ می‌دانی مقاومت جلوی عبور جریان را می‌گیرد؛ این یکی مقدارش ثابت نیست و به زاویهٔ چرخش بستگی دارد. تصویر اول فصل را نگاه کن: سه پایه دارد. دو پایهٔ کناری، دو سرِ ثابتِ مقاومت‌اند؛ و پایهٔ وسط — که اسمش wiper است، همان انگشتی که روی مقاومت سُر می‌خورد — با چرخش سر جابه‌جا می‌شود.

نتیجهٔ این ساختار برای ما: اگر دو پایهٔ کناری را به 3V3 و GND وصل کنیم، پایهٔ وسط بسته به زاویهٔ چرخش، ولتاژی بین صفر تا سه و سه دهم ولت بیرون می‌دهد. **یک شیر ولتاژ!** کاملاً چرخانده به یک طرف: صفر ولت. کاملاً به طرف دیگر: حداکثر. وسط: حدود نصف.

سیم‌کشی را همین حالا انجام بده. پایهٔ وسط به کجا برود؟ به GPIO 34 — از نقشهٔ پین استاندارد دوره. یک قانون قدیمی هم درباره‌اش داری، از ترم ۱، فصل ۴: پایه‌های ۳۴ تا ۳۹ فقط ورودی‌اند — نمی‌توانند چیزی روشن کنند، pull-up داخلی هم ندارند، ولی برای «خواندن» عالی‌اند. و ما امروز دقیقاً می‌خواهیم بخوانیم.

1. کابل USB را جدا کن.
2. پتانسیومتر را روی Breadboard بنشان و سه سیم با سه رنگ متفاوت انتخاب کن تا گم نشوی.
3. یک پایهٔ کناری به 3V3، پایهٔ کناری دیگر به GND.
4. پایهٔ وسط (wiper) به GPIO 34.
5. LED قرمز را هم مثل همیشه با مقاومت ۲۲۰ اهم به پایهٔ ۲۵ و Buzzer را به پایهٔ ۴ ببند — برای ساخت‌های آخر فصل.
6. کابل USB را وصل کن.

جدول اتصالات:

</div>

| Component | ESP32 Pin | Notes |
|---|---|---|
| Potentiometer outer leg A | 3V3 | either outer leg |
| Potentiometer outer leg B | GND | the other outer leg |
| Potentiometer wiper (middle) | GPIO 34 | input-only pin (34-39), ADC |
| LED red (+220 ohm) | GPIO 25 | long leg -> resistor -> GPIO, short -> GND |
| Passive buzzer | GPIO 4 | other leg -> GND |

<div dir="rtl">

> ⚠️ **مواظب باش:** دو پایهٔ کناری را درست وصل کن — یکی 3V3 و یکی GND. اگر حواس‌پرتی کنی و 3V3 مستقیم با یک سیم به GND برسد، اتصال کوتاه ساخته‌ای (قانون ترم ۱!) و برد ریست می‌شود یا داغ می‌کند.

## ۳. ADC: مترجم ولتاژ به عدد

سخت‌افزار آماده است؛ حالا مشکل نرم‌افزاری. پایهٔ ۳۴ قرار است ولتاژی بین صفر تا سه و سه دهم ولت ببیند. ولی برنامهٔ ما با ولتاژ چه کند؟ پایتون که ولت‌متر ندارد؛ پایتون فقط عدد می‌فهمد. این‌جا یک مترجم لازم داریم — اسمش ADC است. کارش دقیقاً همین است: ولتاژِ پیوسته را می‌گیرد و به یک عدد صحیح تبدیل می‌کند. مثل ترازوی دیجیتال آشپزخانه: وزن — یک کمیت پیوسته — می‌رود داخلش، عدد می‌آید بیرون.

چه عددی؟ در چه بازه‌ای؟ ADC داخل ESP32 دوازده‌بیتی است — یعنی خط‌کشش ۴۰۹۶ درجه دارد؛ دو به توان دوازده، همین یک جمله و رد می‌شویم. و چون شمارش مثل همیشه از صفر شروع می‌شود، بازهٔ خروجی می‌شود ۰ تا ۴۰۹۵. آشناست، نه؟ دقیقاً همان منطق ۰ تا ۱۰۲۳ در duty فصل قبل — فقط این خط‌کش چهار برابر ریزتر درجه‌بندی شده. پس: صفر ولت می‌شود عدد ۰، حداکثر ولتاژ می‌شود ۴۰۹۵، و وسط‌ها به نسبت.

## چالش: وسط ولوم، چه عددی؟

اگر ولوم را طوری بچرخانیم که ولتاژ پایهٔ وسط حدوداً وسط بازه باشد، انتظار داریم ADC چه عددی بدهد؟

---

**جواب:** حدود ۲۰۴۸ — نصفِ ۴۰۹۵، همان‌طور که نصف خط‌کش را انتظار داریم.

## ۴. اولین خواندن — و لحظهٔ «چرا این خط؟»

Thonny را باز کن و اولین نسخه را بنویس — عمداً هنوز یک خط کم دارد:

</div>

```python
from machine import Pin, ADC
import time

pot = ADC(Pin(34))

while True:
    value = pot.read()
    print("ADC:", value)
    time.sleep_ms(200)
```

<div dir="rtl">

خط‌به‌خط: `ADC` را از machine آوردیم — کنار همان `Pin` همیشگی. `pot = ADC(Pin(34))` یعنی: پایهٔ ۳۴ را بده دست مترجم. داخل حلقه، `pot.read()` هر بار ولتاژ همین لحظه را می‌خواند و عددش را برمی‌گرداند — با پرانتز، چون داریم صدایش می‌زنیم! و هر ۲۰۰ میلی‌ثانیه یک بار چاپ می‌کنیم که Shell قابل خواندن بماند. اجرا کن و ولوم را آرام بچرخان:

</div>

```text
ADC: 0
ADC: 155
ADC: 1489
ADC: 4095
ADC: 4095
ADC: 4095
ADC: 4095
```

<div dir="rtl">

هوم... یک چیزی عجیب است. از این سر که شروع می‌کنی صفر است، کمی که می‌چرخانی عددها بالا می‌روند — ولی خیلی زود، شاید یک‌چهارم مسیر، عدد می‌چسبد به ۴۰۹۵ و بقیهٔ چرخش هیچ اثری ندارد! سه‌چهارم ولوم ما مُرده. چرا؟

این لحظهٔ «چرا این خط؟» فصل است. مترجم ADC در ESP32 به‌طور پیش‌فرض فقط برای ولتاژهای کوچک تنظیم شده — چیزی در حدود یک ولت. هر چه بالاتر از آن باشد، از نظرش «بیشتر از حداکثر» است و می‌گوید ۴۰۹۵. مثل ترازویی که فقط تا یک کیلو درجه‌بندی شده: هندوانه بگذاری رویش، عقربه ته می‌زند و همهٔ وزن‌های بالاتر یک جواب می‌گیرند.

![دو ترازو در حال وزن کردن هندوانه: ترازوی کوچکی که صفحه‌اش فقط تا 1V درجه دارد و عقربه‌اش ته زده و نمایشگرش روی ۴۰۹۵ گیر کرده، در برابر ترازوی بزرگ‌تری با صفحهٔ کامل تا 3.3V که عقربه‌اش راحت وسط ایستاده](/lesson-assets/t2-s03-adc-potentiometer/prompt/04-image-atten-two-scales.png)

ولوم ما ولتاژ را تا سه و سه دهم ولت بالا می‌برد، پس ترازویمان باید تا سه و سه دهم درجه‌بندی شود. راه‌حل یک خط است — بعد از ساختن pot اضافه‌اش کن: `pot.atten(ADC.ATTN_11DB)`. کلمهٔ atten مخفف attenuation یعنی تضعیف است: به مدار ورودی می‌گوید سیگنال را آن‌قدر نرم کن که کل بازه تا حدود سه و سه دهم ولت در خط‌کش جا شود. لازم نیست عبارت `ATTN_11DB` را حفظ کنی — این خط در همهٔ پروژه‌های ADC این دوره همین شکلی است و همیشه دقیقاً بعد از ساختن ADC می‌آید. نسخهٔ کامل و درست (فایل `01_adc_first_read.py`):

</div>

```python
# Term 2 - Session 03 - avalin khandan-e ADC az potentiometer
from machine import Pin, ADC
import time

pot = ADC(Pin(34))
pot.atten(ADC.ATTN_11DB)   # bedun-e in khat faghat ta hodud-e 1 volt dide mishavad

while True:
    value = pot.read()     # adadi beyn-e 0 ta 4095
    print("ADC:", value)
    time.sleep_ms(200)
```

<div dir="rtl">

✅ **چک کن:** حالا از این سر تا آن سر، کل چرخش، اعداد باید نرم و پیوسته از حدود ۰ تا ۴۰۹۵ بالا و پایین بروند. ولومت زنده شد — تقریباً کل مسیرش معنی دارد.

> 💡 **نکته — چرا «تقریباً»؟** درست دو سرِ چرخش کمی مرده می‌مانند: نزدیک ته چرخش عدد چند درجه زودتر روی ۴۰۹۵ قفل می‌شود و اول چرخش هم چند درجه روی ۰ می‌ماند، بعد راه می‌افتد. این خرابی نیست و تقصیر تو هم نیست: ADC خودِ ESP32 در دو سرِ بازه‌اش خطی و دقیق نیست — همه‌جای دنیا همین است. برای کارهای این دوره هیچ مشکلی درست نمی‌کند؛ فقط وقتی دیدی آخرین یک‌دو درجهٔ چرخش عددی را عوض نمی‌کند، بدان که همین است و دنبال سیم خراب نگرد.

یک نکتهٔ ریز هم همین‌جا ببین: ولوم را ثابت نگه دار — عدد کاملاً ثابت نیست و مثلاً بین ۲۰۳۰ و ۲۰۷۰ ریز می‌لرزد. این طبیعی است؛ اسمش نویز است: لرزش‌های ریز الکتریکی که در هر مدار واقعی وجود دارد. فعلاً اذیتمان نمی‌کند و در فصل ۵ ترفند قشنگی به اسم میانگین‌گیری یاد می‌گیریم که این لرزش را اتو می‌کشد. فعلاً فقط بدان: لرزش چند ده تایی، خرابی نیست.

> 🔧 **اگر کار نکرد:** عدد همیشه ۰ یا همیشه ۴۰۹۵ است و با چرخش عوض نمی‌شود؟ پایهٔ وسط (wiper) به GPIO 34 نرسیده و احتمالاً یکی از پایه‌های کناری جایش رفته — سه سیم را با جدول اتصالات مقایسه کن. جهت برعکس است و چرخش به راست عدد را کم می‌کند؟ دو پایهٔ کناری جابه‌جا وصل شده‌اند — سیم‌های 3V3 و GND را با هم عوض کن. برد وسط کار ریست می‌شود یا داغ می‌کند؟ فوراً USB را جدا کن: اتصال کوتاه داری؛ سیم‌کشی را با سه رنگ سیم از نو ببند. و اگر روی پایهٔ ۳۵ کار می‌کند ولی روی ۳۴ نه، سیم به پایهٔ کناریِ اشتباه روی برد رفته — برچسب پایه‌ها ریز و کنار هم‌اند؛ ۳۴ مال پتانسیومتر است و ۳۵ برای سنسور نورِ فصل بعد رزرو است.

## چالش: بدون atten چه می‌دیدیم؟

بدون نگاه کردن به بالا جواب بده: اگر خط `pot.atten(ADC.ATTN_11DB)` را ننویسیم چه می‌بینیم و چرا؟

---

**جواب:** با کمی چرخش، عدد به ۴۰۹۵ می‌چسبد و بقیهٔ مسیر بی‌اثر می‌شود؛ چون بازهٔ پیش‌فرض ADC فقط تا حدود یک ولت را می‌سنجد و بالاتر از آن ته می‌زند.

## ۵. map_value: مترجم بازه‌ها

حالا می‌خواهیم با این عدد یک کار واقعی کنیم: روشنایی LED را با ولوم کنترل کنیم — یک دیمر واقعی! ولی یک ناهماهنگی داریم. ولوم چه می‌دهد؟ عددی از ۰ تا ۴۰۹۵. آن‌طرف، duty فصل قبل چه می‌خواهد؟ عددی از ۰ تا ۱۰۲۳. اگر عدد ولوم را مستقیم به duty بدهیم، تا یک‌چهارم چرخش همه‌چیز خوب است و بعدش عددهای بزرگ‌تر از ۱۰۲۳ می‌روند توی دستگاهی که خط‌کشش فقط تا ۱۰۲۳ است — همان قصهٔ ترازوی کوچک، این بار آن‌طرف ماجرا. باید بازه را «ترجمه» کنیم: هر عددی از دنیای ۰ تا ۴۰۹۵ به عدد هم‌نسبتش در دنیای ۰ تا ۱۰۲۳.

چطور؟ با ریاضی‌ای که از مدرسه بلدی: **قانون نسبت.** مثال آشنا: نمرهٔ ۱۵ از ۲۰ را می‌خواهی از ۱۰۰ اعلام کنی. چه می‌کنی؟ نسبت را نگه می‌داری: پانزده‌بیستم، ضرب در صد — می‌شود ۷۵. برای ولوم هم همین است: عدد خام تقسیم بر ۴۰۹۵ — یعنی «چند درصد از مسیر» — ضرب در ۱۰۲۳. مثلاً ۲۰۴۸ تقسیم بر ۴۰۹۵ حدوداً نیم است؛ نیم ضرب در ۱۰۲۳ یعنی حدود ۵۱۱. وسطِ ولوم، وسطِ نور. منطقی است!

ولی صبر کن — نمی‌خواهیم این فرمول را هر بار از اول بنویسیم. امروز برای LED است، چند دقیقه دیگر برای Buzzer با بازهٔ متفاوت، فصل بعد برای سنسور نور... فصل ۱ چه یاد گرفتیم؟ وقتی یک محاسبه قرار است بارها استفاده شود: کارخانه! تابعی می‌سازیم که هر عددی را از هر بازه‌ای به هر بازهٔ دیگری ببرد. اسمش `map_value` — map یعنی نگاشت: بردن نقطه‌به‌نقطه از یک نقشه به نقشهٔ دیگر. پنج پارامتر می‌گیرد: خود عدد، کف و سقف بازهٔ ورودی، کف و سقف بازهٔ خروجی. و چون جواب پس می‌دهد، `return` فصل ۱ هم برمی‌گردد. برنامهٔ کامل با تست‌ها (فایل `02_map_value.py` کنار درس — هیچ سخت‌افزاری لازم ندارد):

</div>

```python
# Term 2 - Session 03 - tabe map_value: tarjome-ye baze be baze

def map_value(x, in_min, in_max, out_min, out_max):
    # tabdil adad az yek baze be baze dige
    return (x - in_min) * (out_max - out_min) // (in_max - in_min) + out_min

# test-ha: javab-e dorost ra kenar-e har khat neveshtim
print(map_value(0, 0, 4095, 0, 1023))       # bayad 0 shavad
print(map_value(4095, 0, 4095, 0, 1023))    # bayad 1023 shavad
print(map_value(2048, 0, 4095, 0, 1023))    # bayad hodud-e 511 shavad
print(map_value(0, 0, 4095, 200, 2000))     # bayad 200 shavad (kaf-e baze-ye jadid)
print(map_value(4095, 0, 4095, 200, 2000))  # bayad 2000 shavad
print(map_value(1000, 0, 4095, 200, 2000))  # bayad hodud-e 639 shavad
```

<div dir="rtl">

فرمول را باز کنیم — ترسناک نیست: `x - in_min` یعنی «چقدر از کف ورودی بالاتری». ضرب در طول بازهٔ خروجی و تقسیم بر طول بازهٔ ورودی — همان قانون نسبت، همان پانزده‌بیستم ضرب در صد. و آخرش `+ out_min` یعنی از کف بازهٔ خروجی شروع کن. برای بازه‌هایی که از صفر شروع می‌شوند، این جمع و تفریق‌ها عملاً هیچ‌کاره‌اند؛ ولی وقتی بازهٔ خروجی مثلاً ۲۰۰ تا ۲۰۰۰ باشد — چند دقیقه صبر کن! — به کار می‌آیند.

فقط یک نکتهٔ ظریف: چرا تقسیمش دو تا اسلش دارد؟ تقسیم معمولی `/` جواب اعشاری می‌دهد — و duty عدد صحیح می‌خواهد. این‌جا دو ابزار تازهٔ امروز به جعبه‌ابزارت اضافه می‌شوند و هر دو را باید بشناسی: اولی تابع `int()` است که عدد اعشاری را به عدد صحیح گرد می‌کند، به سمت پایین — `int(3.9)` می‌شود ۳؛ همین یک جمله. دومی که در map_value استفاده کردیم: `//` — تقسیم صحیح. برادر دوقلوی همان `/` است، فقط از همان اول جواب را صحیح نگه می‌دارد و دیگر تبدیل لازم ندارد. تمیزتر است؛ همین را استاندارد دوره می‌کنیم.

✅ **چک کن:** Run بزن و شش جواب را با کامنت کنار هر خط مقایسه کن — هر شش تا باید درست باشند. مثل مهندس‌ها اول تست کردیم، حالا با خیال راحت در پروژه‌ها استفاده‌اش می‌کنیم. و خبر خوب: این تابع دقیقاً با همین شکل تا آخر دوره همراه ماست.

## چالش: ترجمهٔ وسط خط‌کش

`map_value(2048, 0, 4095, 0, 1023)` حدوداً چه عددی برمی‌گرداند و چرا؟

---

**جواب:** حدود ۵۱۱، چون ۲۰۴۸ تقریباً نصف بازهٔ ورودی است و نصفِ ۱۰۲۳ می‌شود همین حدود.

## ۶. ولوم نور: دیمر واقعی

وقت وصل کردن دو دنیاست: ولوم را می‌خوانیم، با map_value به بازهٔ duty می‌بریم، به LED می‌دهیم. ولی قبلش یک خرابکاری عمدی که سر خیلی‌ها می‌آید — پرانتز `read` را جا بینداز:

</div>

```python
raw = pot.read
print("ADC:", raw)
```

```text
ADC: <bound_method>
```

<div dir="rtl">

به‌جای عدد، این را چاپ کرد — و هیچ خطایی هم نداد! فصل ۱ را یادت هست؟ اسم تابع بدون پرانتز، خودِ تابع است، نه جوابش. `pot.read` یعنی «خودِ دستگاهِ خواندن» — انگار به‌جای آبمیوه، عکسِ دستگاه آبمیوه‌گیری را تحویل داده باشی! پایتون هم صادقانه همان را چاپ می‌کند: «این یک متد است.» پرانتز که بگذاری — `pot.read()` — تازه خواندن انجام می‌شود و عدد برمی‌گردد. اگر روزی در Shell به‌جای عدد `<bound_method>` دیدی، بی‌معطلی دنبال پرانتزِ جاافتاده بگرد.

برنامهٔ کامل دیمر (فایل `03_knob_led.py`):

</div>

```python
# Term 2 - Session 03 - volume-e noor: pot -> roshanayi LED
from machine import Pin, ADC, PWM
import time

pot = ADC(Pin(34))
pot.atten(ADC.ATTN_11DB)
led = PWM(Pin(25), freq=1000)

def map_value(x, in_min, in_max, out_min, out_max):
    # tabdil adad az yek baze be baze dige
    return (x - in_min) * (out_max - out_min) // (in_max - in_min) + out_min

while True:
    raw = pot.read()                              # 0 ta 4095
    brightness = map_value(raw, 0, 4095, 0, 1023) # 0 ta 1023
    led.duty(brightness)
    print("raw:", raw, "-> duty:", brightness)
    time.sleep_ms(50)
```

<div dir="rtl">

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

> 🔧 **اگر کار نکرد:** map_value عددهای عجیب می‌دهد — منفی یا خیلی بزرگ؟ ترتیب آرگومان‌ها اشتباه است و جای بازهٔ ورودی و خروجی عوض شده: `map_value(x, in_min, in_max, out_min, out_max)` — با تست‌های فایل ۰۲ مقایسه کن.

و اگر الان برد یا پتانسیومتر دم دستت نیست:

> 🧪 **آزمایشگاه:** همین مدار در آزمایشگاه دوره آماده است: «اجرا ▶» را بزن و ولوم را با موس بچرخان. شبیه‌ساز ولتاژ واقعیِ نقطهٔ وسط ولوم را حل می‌کند، `read()` همان را می‌خواند و LED به‌اندازهٔ همان عدد پرنور می‌شود — کدِ خودت، روی مدارِ حل‌شده. [مدار را همین‌جا امتحان کن](/lab).

## ۷. پیانوی چرخان

و حالا نسخهٔ صدادار: به‌جای LED، فرکانس Buzzer را کنترل می‌کنیم. این‌جاست که آن `out_min` و `out_max` واقعاً به کار می‌آیند: فرکانس‌های خیلی کم برای Buzzer شنیدنی نیستند، پس بازهٔ خروجی را می‌گذاریم ۲۰۰ تا ۲۰۰۰ هرتز. Buzzer با `duty(512)` روشن — رازش را که حالا می‌دانی! — و داخل حلقه فقط `freq` عوض می‌شود. برنامهٔ کامل (فایل `04_knob_buzzer.py`):

</div>

```python
# Term 2 - Session 03 - piano-ye charkhan: pot -> farkans-e buzzer
from machine import Pin, ADC, PWM
import time

pot = ADC(Pin(34))
pot.atten(ADC.ATTN_11DB)
buzzer = PWM(Pin(4))
buzzer.duty(0)   # aval-e kar sakit!

def map_value(x, in_min, in_max, out_min, out_max):
    # tabdil adad az yek baze be baze dige
    return (x - in_min) * (out_max - out_min) // (in_max - in_min) + out_min

buzzer.duty(512)   # seda roshan; az inja be bad faghat freq avaz mishavad

while True:
    raw = pot.read()
    tone = map_value(raw, 0, 4095, 200, 2000)   # 200 ta 2000 Hz
    buzzer.freq(tone)
    print("raw:", raw, "-> freq:", tone)
    time.sleep_ms(50)
```

<div dir="rtl">

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

## قطعه نداری؟ مسیر شبیه‌ساز

خبر خوب: قلب این فصل در آزمایشگاه خودمان واقعاً اجرا می‌شود — [مدار را همین‌جا امتحان کن](/lab/embed/term-2-sensors/session-03-adc-potentiometer). مدارِ آماده‌اش همان «ولوم → روشنایی LED» است: پتانسیومتر با موس می‌چرخد و LED کنارش جواب می‌دهد، پس بدون هیچ سخت‌افزاری می‌توانی کد اصلی این فصل را واقعاً اجرا کنی — شبیه‌ساز مدار را الکتریکی حل می‌کند، یعنی ولتاژ نقطهٔ وسط ولوم واقعاً حساب می‌شود و همان عدد از `read()` بیرون می‌آید. و سه تفاوت صادقانه با میز واقعی: اول، در مدار آمادهٔ آزمایشگاه بازر نیست، پس «پیانوی چرخان» را باید روی برد واقعی بشنوی. دوم، در شبیه‌ساز نویز وجود ندارد و اعداد کاملاً ثابت‌اند — لرزش چند ده تایی را فقط روی سخت‌افزار واقعی می‌بینی (و همین واقعیت، انگیزهٔ درس میانگین‌گیری فصل ۵ است). سوم، `atten` در شبیه‌ساز پذیرفته می‌شود ولی اثری ندارد؛ پس آزمایش «قبل و بعد از atten» را حتماً روی برد واقعی ببین.

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

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| analog | آنالوگ | کمیت پیوسته با بی‌نهایت حالت میانی، مثل زاویهٔ ولوم |
| ADC | اِی‌دی‌سی | مترجم ولتاژ به عدد؛ در ESP32 خروجی‌اش ۰ تا ۴۰۹۵ است |
| potentiometer | پُتِنشیامیتِر | مقاومت متغیر چرخان — همان ولوم؛ پایهٔ وسطش ولتاژ متغیر می‌دهد |
| resolution | رِزولوشِن | ریزی درجه‌بندی خط‌کش؛ ۱۲ بیت یعنی ۴۰۹۶ درجه |
| range | رِینج | بازه؛ فاصلهٔ کف تا سقف مقدارهای ممکن |
| map | مَپ | نگاشت؛ ترجمهٔ هم‌نسبت یک عدد از بازه‌ای به بازهٔ دیگر |

## تمرین‌ها

اول چک‌لیست پایان فصل: با چرخش کامل ولوم، اعداد Shell نرم و پیوسته از حدود ۰ تا ۴۰۹۵ تغییر می‌کنند (نه چسبیده به ۴۰۹۵)؛ می‌توانی توضیح بدهی خط atten چه مشکلی را حل کرد؛ map_value را نه از حفظ، بلکه با استدلال نسبت بازسازی می‌کنی و با سه تست print درستی‌اش را نشان می‌دهی؛ ولوم نور در کل مسیر نرم کار می‌کند؛ و با دیدن `<bound_method>` بدون کمک می‌گویی مشکل کجاست. اگر هر پنج تا بله است، برو سراغ تمرین‌ها:

- **تمرین اجباری:** پیانوی چرخان را دو جور تغییر بده: اول بازهٔ صدا را از ۲۰۰ تا ۲۰۰۰ به ۱۰۰ تا ۵۰۰ برسان (صدای بم‌تر) و تفاوت را گوش کن. بعد در ولوم نور، جهت را برعکس کن: ولوم که بالا می‌رود، LED کم‌نور شود (راهنمایی: `brightness = 1023 - map_value(...)` — یا فکر کن چطور با خود map_value می‌شود).
- **تمرین ستاره‌دار ⭐:** «کنترل سرعت آهنگ»: ملودی فصل ۱۰ ترم ۱ را بیاور و کاری کن پتانسیومتر سرعت پخش نت‌ها را کنترل کند — ولوم، مکث بین نت‌ها را از ۱۰۰ تا ۶۰۰ میلی‌ثانیه تعیین کند (map_value به کمکت می‌آید؛ داخل حلقهٔ نت‌ها، هر بار ولوم را دوباره بخوان).

## در فصل بعد

یک معما: چراغ‌های خیابان از کجا می‌فهمند هوا تاریک شده که خودشان روشن می‌شوند؟ فصل بعد به‌جای دستِ تو، نورِ اتاق ولوم را می‌چرخاند — سنسور نور می‌آید و چراغ خواب خودکار می‌سازیم.

</div>

---
Source: https://yaadestan.com/courses/airo/lessons/t2/s03-adc-potentiometer (یادستان, Yaadestan)
