iAct

Act on Ai

برنامه‌نویسی ESP32 با Claude Code؛ از تست LED تا اجرای بازی


برنامه‌نویسی ESP32 با Claude Code؛ از تست LED تا اجرای بازی
وقتی هنوز LCD و بردبورد پروژه به دستت نرسیده، چطور مطمئن می‌شوی ESP32-S3 واقعاً برای کنسول دستی‌ات مناسب است؟ می‌توانی فاز اول Luzia Pocket را به چند آزمون کوچک تبدیل کنی: برد را دقیق شناسایی کنی، یک برنامهٔ بی‌خطر روی آن اجرا کنی، LED داخلی را ــ اگر قابل‌کنترل بود ــ آزمایش کنی و بعد موتور بازی را با نمایش تصویر روی کامپیوتر بررسی کنی. نتیجه قرار نیست یک کنسول کامل باشد؛ قرار است بدانی کدام بخش واقعاً کار می‌کند و برای مرحلهٔ بعد چه چیزی هنوز اثبات نشده است.

۱. مرز فاز اول را مشخص کن

ایدهٔ نهایی، دستگاهی دستی است که بازی‌های ساده را روی سخت‌افزار خودش اجرا کند. اما در شروع، فقط برد ESP32-S3 و چند دکمه در دسترس بود؛ LCD، بردبورد و سیم‌های اتصال هنوز نرسیده بودند. پس اتصال دکمه‌ها و نمایش تصویر روی LCD را باید کنار گذاشت. اگر همین ابتدا موتور بازی، ورودی‌ها، سیم‌کشی و نمایشگر را با هم تغییر بدهی، هنگام خرابی نمی‌فهمی اشکال از کدام قسمت است.

ESP32-S3 خانواده‌ای از تراشه‌هاست، نه نام یک برد با پایه‌بندی ثابت. برد توسعه‌ای که این تراشه روی آن قرار دارد ممکن است دکمه، LED یا قطعات جانبی متفاوتی داشته باشد. همین تفاوت، دلیل خوبی است که برنامه‌نویسی را با شناسایی برد آغاز کنی، نه با فرض گرفتن شمارهٔ یک پایه. برای شناخت کلی تراشه می‌توانی معرفی ESP32-S3 را بخوانی؛ برای اتصال‌ها و قطعات روی برد مشخص خودت، نوشته‌های روی برد و مستندات سازندهٔ همان برد تعیین‌کننده‌اند.

خروجی این مرحله یک برگهٔ کوتاه است: نوشتهٔ روی برد، نوع درگاه USB که استفاده می‌کنی، برچسب دکمه‌ها و اینکه LED قابل‌کنترل روی آن شناسایی شده است یا نه. ظرفیت حافظه یا شمارهٔ پایه را از روی ظاهر تراشه حدس نزن.

۲. اتصال USB را از اجرای برنامه جدا بدان

برد را روی سطحی غیررسانا بگذار و با کابل USB مناسب به کامپیوتر وصل کن. اگر LED چشمک می‌زند یا درگاه ارتباطی ظاهر می‌شود، فقط می‌دانی برد احتمالاً برق گرفته و نشانه‌ای از فعالیت دارد. چشمک‌زدن ممکن است حاصل برنامه‌ای باشد که از قبل روی برد قرار دارد؛ هنوز ثابت نمی‌کند کد تو اجرا شده است. در این مرحله چیزی را به پایه‌های برد متصل نکن.

در پروژهٔ نمونه، روی برد دکمه‌های BOOT و RST دیده می‌شد. این نام‌ها را روی برد خودت هم بررسی کن. دکمهٔ RST معمولاً برد را بازنشانی می‌کند؛ BOOT می‌تواند هنگام راه‌اندازی در ورود به حالت دریافت برنامه نقش داشته باشد. ترکیب دکمه‌ها و رفتار درگاه USB را نباید برای همهٔ بردهای ESP32-S3 یکسان فرض کرد.

پیش از سپردن کنترل کامپیوتر به Claude Code، محدودهٔ اختیارش را روشن کن. Claude Code می‌تواند در بررسی فایل‌ها و اجرای دستورها کمک کند، اما تشخیص برد و تأیید عملیات تغییردهندهٔ حافظه همچنان با توست.

بازنویسی آموزشی پرامپت برای Claude Code:

فقط برد ESP32-S3 و کابل USB را دارم؛ LCD و بردبورد هنوز آماده نیستند. ابتدا درگاه‌های احتمالی، نوشته‌های روی برد و اطلاعاتی را که بدون تغییر حافظه می‌توان خواند مشخص کن. پیش از پاک‌کردن، فلش‌کردن یا تغییر فایل‌های برد، دقیقاً بگو چه چیزی تغییر می‌کند و از من تأیید بگیر. شمارهٔ پایهٔ LED یا مدل دقیق برد را حدس نزن.

نتیجهٔ مطلوب، گزارش وضعیت و یک برنامهٔ آزمایش است؛ نه اینکه دستیار بلافاصله firmware نصب کند.

۳. پیش از فلش‌کردن، مدل و firmware را راستی‌آزمایی کن

در اجرای نمونه، برنامه‌ای که از قبل روی برد بود با جریان کار بعدی تداخل داشت و برد با کمک دکمه‌های BOOT و RST وارد حالت دریافت برنامه شد. سپس MicroPython روی آن قرار گرفت. این ترتیب را می‌توان فهمید، اما نباید آن را به نسخه‌ای از firmware یا فایل آمادهٔ پیشنهادی برای برد تو تبدیل کرد: اطلاعات بردها، از جمله ظرفیت flash و PSRAM، متفاوت است و متن ضبط‌شده هم دربارهٔ بعضی عددها ناسازگاری دارد.

MicroPython پیاده‌سازی سبک‌تری از Python برای دستگاه‌هایی مانند میکروکنترلرهاست. با نصب firmware سازگار، می‌توانی دستورهای Python را در محیط تعاملی آن، یا REPL، اجرا کنی. پیش از هر فلش، مدل دقیق برد، مشخصات حافظه، شیوهٔ ورود همان برد به حالت دریافت برنامه و سازگاری firmware را از مستندات مربوط بررسی کن. راهنمای MicroPython برای ESP32 برای شناخت محیط و APIها مفید است، اما به‌تنهایی مشخص نمی‌کند کدام فایل firmware برای برد ناشناس تو مناسب است.

فلش‌کردن ممکن است برنامهٔ قبلی برد را از بین ببرد. اگر حفظ آن برنامه برایت مهم است و راه پشتیبان‌گیری یا بازیابی‌اش را نمی‌دانی، اینجا توقف کن. اگر ارتباط برقرار نمی‌شود، اول کابلِ دارای انتقال داده، درگاه انتخاب‌شده، دسترسی برنامه‌های دیگر به آن درگاه و روش BOOT/RST همان برد را بررسی کن؛ چند بار فلش‌کردن با حدس‌های متفاوت راه‌حل خوبی نیست.

۴. با یک گزارش بی‌خطر از برد شروع کن

پس از آنکه از سازگاری MicroPython و دسترسی به REPL مطمئن شدی، نخست اطلاعات پایه را بخوان. مثال تکمیلی آموزشی: کد زیر هیچ پایه‌ای را تغییر نمی‌دهد، چیزی را پاک نمی‌کند و به شناسهٔ یکتای دستگاه هم دست نمی‌زند. فرضش این است که MicroPython از قبل روی برد نصب شده و REPL آن در دسترس توست.

برای اجرای آزمایش، این کد را در فایلی به نام board_info.py در ریشهٔ فایل‌سیستم خود برد قرار بده؛ آن را به‌عنوان boot.py یا main.py ذخیره نکن تا با هر روشن‌شدن خودکار اجرا نشود. سپس در REPL بنویس import board_info. اگر ابزار انتقال فایل به برد نداری، می‌توانی همین چند خط را مستقیم در REPL وارد کنی.

import sys
import os
import machine

print('platform:', sys.platform)
print('system:', os.uname().sysname)
print('machine:', os.uname().machine)
print('frequency_hz:', machine.freq())

باید چند خط شامل پلتفرم، توصیف ماشین و فرکانس گزارش‌شده ببینی. این خروجی نقطهٔ شروع شناسایی است، نه گواه قطعیِ مدل تجاری برد یا محل اتصال LED. اگر import board_info برای بار دوم خروجی نداد، طبیعی است: Python ماژول واردشده را نگه می‌دارد. برای تکرار سادهٔ آزمون، برد را بازنشانی کن و دوباره وارد REPL شو. خروجی را کنار عکس نوشته‌های روی برد نگه دار؛ اگر اطلاعات با انتظار تو نمی‌خواند، پیش از کار با پایه‌ها اختلاف را بررسی کن.

۵. LED داخلی را بدون حدس‌زدن پایه آزمایش کن

حالا نوبت یک خروجی قابل‌دیدن است. در برد نمونه، LED رنگی داخلی با فشار دکمهٔ BOOT بین رنگ‌ها تغییر می‌کرد؛ اما LED داخلی همهٔ بردهای ESP32-S3 یکسان نیست. ممکن است LED ساده باشد، از نوع RGB آدرس‌پذیر باشد، به پایه‌ای متفاوت وصل شده باشد یا اصلاً برای برنامهٔ تو قابل‌کنترل نباشد. حتی دیدن دو چراغ روی برد، نوع و پایهٔ آن‌ها را مشخص نمی‌کند. بنابراین دستور رایج «GPIO2 را روشن کن» را برای این پروژه کپی نکن.

برچسب و مدل برد را با مستندات همان برد تطبیق بده و از Claude Code بخواه ابتدا نوع LED، شیوهٔ کنترل و پایهٔ مربوط را با ذکر منشأ هر مورد گزارش کند. فقط پس از تأیید تو، برنامه‌ای کوچک بسازد که دکمهٔ مناسب را بخواند و LED را بین چند حالت شناخته‌شده جابه‌جا کند. اگر این اطلاعات پیدا نشد، آزمون LED را کنار بگذار؛ نداشتن آزمایش LED بهتر از دست‌کاری پایهٔ نامعلوم است.

بازنویسی آموزشی پرامپت برای Claude Code:

مدل برد و اطلاعات خوانده‌شده از REPL را به تو می‌دهم. اول بررسی کن آیا LED قابل‌برنامه‌ریزی و دکمهٔ روی برد برای این مدل مستند شده‌اند یا نه. تفاوت LED برق/وضعیت و LED قابل‌کنترل را توضیح بده. تا وقتی نوع LED، پایه یا روش کنترل آن تأیید نشده، کد GPIO تولید و اجرا نکن. پس از تأیید من، یک آزمون کوچک تغییر رنگ یا روشن/خاموش بساز و رفتار مورد انتظارش را بنویس.

در آزمون نمونه، تغییر رنگ با هر فشار BOOT دیده شد. چنین مشاهده‌ای ثابت می‌کند مسیر همان دکمه و همان LED در آن برنامه کار کرده است؛ هنوز دربارهٔ LCD، دکمه‌های خارجی یا موتور بازی چیزی ثابت نمی‌کند. اگر فشار دکمه نتیجه‌ای ندارد، به‌جای عوض‌کردن تصادفی شمارهٔ پایه، ابتدا معلوم کن برنامهٔ جدید واقعاً اجرا شده، دکمهٔ درست را می‌فشاری و LED از نوع مورد انتظار برنامه است یا نه.

۶. موتور بازی را از نمایش تصویر جدا کن

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

«موتور بازی» در اینجا برنامه‌ای است که قواعد و به‌روزرسانی بازی‌ها را اجرا می‌کند. هر بازی می‌تواند داده یا کد مخصوص خودش را داشته باشد؛ برای شروع لازم نیست معماری کارتریج‌ها را پیچیده کنی. نخست یک بازی و یک ورودی را اجرا کن، بعد تغییر بازی و سایر ورودی‌ها را بیازما. از Claude Code بخواه مرز مسئولیت برد و میزبان و قالب پیام‌های بین آن‌ها را در کد موجود نشان بدهد، نه اینکه صرفاً بگوید بازی اجرا می‌شود.

بازنویسی آموزشی پرامپت برای Claude Code:

LCD هنوز ندارم. کد فعلی موتور بازی و نمایشگر میزبان را بررسی کن و بگو کدام قسمت روی ESP32-S3 اجرا می‌شود و کدام قسمت روی کامپیوتر. ابتدا فقط یک بازی را با یک ورودی راه بینداز. تغییرات firmware را پیش از اجرا توضیح بده و بعد از هر مرحله بگو چه خروجی قابل مشاهده‌ای باید ببینم. هیچ سرعت یا تعداد فریمی را بدون اندازه‌گیری معتبر تضمین نکن.

اگر صفحهٔ میزبان خالی ماند، مشکل را به بخش‌های کوچک‌تر بشکن: آیا برد در REPL پاسخ می‌دهد؟ آیا برنامهٔ مورد نظر روی برد اجرا شده؟ آیا برنامهٔ میزبان به درگاه درست وصل است؟ آیا برنامهٔ دیگری همان درگاه را باز نگه داشته است؟ در نمونه، اتصال نمایشگر میزبان در تلاش اول برقرار نشد و پس از بستن پنجرهٔ قبلی مرورگر و اتصال دوباره کار کرد. همین تجربه یادآوری می‌کند که خرابی اتصال میزبان الزاماً خرابی موتور بازی نیست.

۷. برای ادعای «اجرای روی برد» شاهد مستقل بساز

وقتی تصویر بازی روی کامپیوتر ظاهر شد، سؤال دقیق‌تری بپرس: با تغییر بازی، روی خود برد چه چیزی تغییر می‌کند؟ در پروژهٔ نمونه، رنگ LED برای بازی‌های مختلف تغییر داده شد و بعضی رویدادها نیز با چشمک‌زدن همراه بودند. این تغییر هم‌زمان، شاهدی قوی‌تر از تصویر مرورگر است که میان انتخاب بازی و برنامهٔ برد ارتباطی وجود دارد.

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

اگر حرکت بازی گاهی پرش دارد، آن را پنهان نکن و فوراً هم به توان پردازنده نسبت نده. ثبت کن پرش در کدام بازی و هنگام چه عملی دیده می‌شود؛ سپس ارتباط USB، کد نمایش میزبان و زمان‌بر بودن کارهای روی برد را جداگانه بررسی کن. یک عدد نمایش‌داده‌شده برای نرخ فریم، بدون روش اندازه‌گیری روشن، معیار عملکرد نهایی روی LCD نیست.

۸. آزمون قطع اتصال را در زمان درست انجام بده

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

آزمون استقلال واقعی را برای زمانی نگه دار که LCD و ورودی‌های فیزیکی، پس از بررسی مشخصات و اتصال‌های برد و نمایشگر خودت، جداگانه آزمایش شده‌اند. سپس سیستم را خاموش کن، اتصال‌ها را بازبینی کن و به‌جای کامپیوتر از یک منبع USB مناسب و مطمئن برای برق استفاده کن. اگر بازی روی LCD بالا می‌آید و دکمه‌ها بدون اتصال داده به کامپیوتر پاسخ می‌دهند، وابستگی آن تجربهٔ بازی به نمایشگر میزبان رد می‌شود. در اجرای نمونه، پس از رسیدن قطعات و اتصال نمایشگر و دکمه‌ها، برق از گوشی تأمین شد و بازی روی LCD ادامه پیدا کرد. این نتیجه دربارهٔ همان نمونه است، نه وعده‌ای برای هر برد و هر سیم‌کشی.

برای تمرین، یک برگهٔ آزمایش بساز و در آن سه مشاهدهٔ جدا بنویس: خروجی REPL، واکنش LED به دکمه یا تغییر بازی، و نتیجهٔ قطع اتصال میزبان. کنار هر مشاهده بنویس «چه چیزی ثابت شد» و «چه چیزی هنوز ثابت نشده». محصول قابل‌تحویل فاز اول تو همین گزارش همراه با کد کوچک شناسایی و نسخهٔ آزمایش‌شدهٔ برنامه است؛ گزارشی که وقتی LCD یا اتصال بعدی مشکل پیدا کرد، به تو نشان می‌دهد از کدام نقطهٔ سالم باید عیب‌یابی را شروع کنی.

ویدیوی کامل

اگر می‌خواهی روند کار و آزمون‌ها را هم ببینی، ویدیوی کامل این آموزش اینجاست:

تماشای ویدیو در یوتیوب · گروه گفت‌وگو و پرسش‌های آموزشی


دیدگاهتان را بنویسید