📚 چطور کتابخانه‌ی دلخواه آردوینو را به شبیه‌ساز اضافه کنم؟

شبیه‌ساز ده‌ها کتابخانه‌ی معروف (Servo، LiquidCrystal، Adafruit_NeoPixel، DHT، …) را از قبل دارد. ولی گاهی کتابخانه‌ای می‌خواهی که در فهرست نیست: کتابخانه‌ی یک سنسور کم‌تر معروف، نسخه‌ی خاصی از یک کتابخانه، یا کتابخانه‌ای که خودت برای پروژه‌ات نوشته‌ای. از این به بعد می‌توانی آن را خودت آپلود کنی — همان کاری که در Wokwi با «library upload» می‌کنی.

اول بدان: فقط با «اجرای واقعی»

شبیه‌ساز دو جور کدت را اجرا می‌کند. اجرای معمولی کد C++‎ را ترجمه می‌کند و با یک مجموعه کتابخانه‌ی داخلی اجرا می‌کند؛ این حالت کتابخانه‌ی دلخواه را نمی‌شناسد. اجرای واقعی کدت را با کامپایلر واقعی آردوینو (avr-gcc) روی سرور کامپایل می‌کند و کد ماشین را روی تراشه‌ی شبیه‌سازی‌شده‌ی ATmega328P اجرا می‌کند — درست مثل برد واقعی. کتابخانه‌ی دلخواه فقط در این حالت کار می‌کند، چون کامپایلر واقعی فایل‌های ‎.cpp کتابخانه را می‌سازد.

اجرای واقعی جزو ابزارهای حرفه‌ای است و با اشتراک باز می‌شود؛ خود محتوای سایت (درس‌ها، مثال‌ها، مأموریت‌ها) رایگان است.

قدم ۱: کتابخانه را آماده کن

دو راه داری:

• فایل zip — در صفحه‌ی گیت‌هاب کتابخانه، دکمه‌ی سبز «Code» و بعد «Download ZIP». همان فایل را، بدون باز کردن، آپلود کن. پوشه‌ی اضافی (Foo-master/) خودش برداشته می‌شود و اسم کتابخانه از روی آن انتخاب می‌شود.
• چند فایل — اگر کتابخانه فقط یک Foo.h و یک Foo.cpp است، هر دو را با هم انتخاب کن. اسم کتابخانه از روی فایل ‎.h گذاشته می‌شود.

قدم ۲: تب «کتابخانه‌ها» در ویرایشگر کد

در مود آردوینو، پایین صفحه کنار تب‌های sketch.ino و Serial Monitor، تب کتابخانه‌ها را باز کن و دکمه‌ی «آپلود کتابخانه» را بزن. بعد از آپلود، کتابخانه با اسم، تعداد فایل‌ها و خط‌های #include آماده‌اش در فهرست دیده می‌شود. برای حذف، آیکون سطل کنارش را بزن.

قدم ۳: در کدت include کن و «واقعی» را روشن کن

#include <MyLib.h>      // اسم هدر همان است که در تب کتابخانه‌ها نوشته

MyLib sensor(A0);

void setup() {
  Serial.begin(9600);
  sensor.begin();
}

void loop() {
  Serial.println(sensor.read());
  delay(500);
}

در نوار بالا دکمه‌ی «واقعی» را روشن کن و «اجرا» را بزن. در Serial Monitor می‌بینی: «در حال کامپایل روی سرور با ۱ کتابخانه‌ی دلخواه…» و بعد حجم برنامه و رم. اگر کامپایل نشد، پیغام کامپایلر با شماره‌ی خط همان‌جا چاپ می‌شود.

ذخیره همراه پروژه

کتابخانه‌ها بخشی از پروژه‌اند: با ذخیره‌ی sketch (محلی یا ابری) همراهش ذخیره می‌شوند و با باز کردن پروژه برمی‌گردند. خروجی JSON پروژه هم آن‌ها را دارد، پس می‌توانی پروژه را با کتابخانه‌اش به دوستت بدهی.

محدودیت‌ها

فایل‌های دیگر داخل zip (مثال‌ها، عکس‌ها، README، اسکریپت‌ها) خودشان کنار گذاشته می‌شوند و هیچ‌چیزی از داخل zip اجرا نمی‌شود — فقط فایل‌های متنی کد خوانده و کامپایل می‌شوند.

خطاهای رایج

• «کتابخانه‌ی … در اجرای واقعی نصب نیست» — کتابخانه آپلود نشده، یا اسم هدر در #include با فایل داخل کتابخانه فرق دارد. در تب کتابخانه‌ها خط #include دقیق را ببین.
• «فقط با اجرای واقعی کار می‌کند» در Serial Monitor — دکمه‌ی «واقعی» خاموش است و اجرای معمولی کتابخانه را نمی‌شناسد.
• خطای کامپایل داخل کتابخانه — بعضی کتابخانه‌ها برای ESP32 یا بردهای ARM نوشته شده‌اند و روی AVR کامپایل نمی‌شوند. دنبال نسخه‌ای بگرد که Uno را پشتیبانی کند.
• «برنامه در حافظه جا نمی‌شود» — کتابخانه‌های گرافیکی بزرگ (فونت‌ها، تصویرها) به‌راحتی از ۳۲ کیلوبایت فلش Uno می‌گذرند. بخش‌های اضافه را حذف کن یا Mega را انتخاب کن.
• «هیچ فایل ‎.h یا ‎.cpp پیدا نشد» — zip اشتباهی است (مثلاً فقط مثال‌ها)، یا کتابخانه ساختار غیرعادی دارد. فایل‌های اصلی را جدا انتخاب کن.

کتابخانه‌ی خودت را بنویس

ساده‌ترین کتابخانه دو فایل است. Blinker.h:

#pragma once
#include <Arduino.h>

class Blinker {
public:
  Blinker(int pin) : _pin(pin) {}
  void begin() { pinMode(_pin, OUTPUT); }
  void blink(int ms) {
    digitalWrite(_pin, HIGH); delay(ms);
    digitalWrite(_pin, LOW);  delay(ms);
  }
private:
  int _pin;
};

هر دو فایل را (اگر ‎.cpp هم داری) با هم آپلود کن، در کدت #include <Blinker.h> بنویس و با اجرای واقعی امتحان کن. این دقیقاً همان کاری است که بعداً روی برد واقعی هم می‌کنی: پوشه‌ی کتابخانه را در Documents/Arduino/libraries می‌گذاری.

مقاله‌های دیگر