کار با کتابخانه‌ها

سنسور دما را در نظر بگیرید: برای خواندنش باید پالس‌های زمان‌سنجی دقیق بفرستید، پاسخ را بیت‌به‌بیت بخوانید و عدد نهایی را از دل داده‌های خام دربیاورید. این کار صدها خط کد تخصصی می‌خواهد — و هر سازندهٔ سنسور محبوبی همین کار را یک بار کرده و نتیجه را به‌شکل «کتابخانه» (Library) در اختیار همه گذاشته است. کتابخانه بسته‌ای از کد آماده است که با یک #include به اسکچ شما می‌چسبد و جعبه‌ابزارتان را یک‌شبه بزرگ می‌کند. در این درس یاد می‌گیرید کتابخانه را از کجا بگیرید، چطور نصبش کنید و وقتی نصب «انجام شده» اما کد کامپایل نمی‌شود، چه بکنید.

کتابخانه چیست و چطور وارد اسکچ می‌شود؟

کتابخانه از نظر فنی مجموعه‌ای از فایل‌های کد C++ است: فایل سرآیند با پسوند .h که فهرست امکانات را معرفی می‌کند، و فایل پیاده‌سازی با پسوند .cpp که بدنهٔ توابع را دارد. شما فقط به سرآیند نگاه می‌کنید؛ خط زیر در بالای اسکچ، کل امکانات کتابخانه را در دسترس می‌گذارد:

#include <Servo.h>

دو شکل include را از هم تشخیص دهید: علامت < > یعنی «کتابخانه‌ای که در پوشه‌های کتابخانهٔ سیستم نصب است» و گیومهٔ " " یعنی «فایلی کنار همین اسکچ»، مثل "myHelper.h". اشتباه‌گرفتن این دو یکی از علت‌های رایج خطای کامپایل است.

نصب از Library Manager (روش اصلی)

Arduino IDE 2.x مدیر بستهٔ داخلی دارد و تقریباً همهٔ کتابخانه‌های مشهور آنجا هستند:

1. IDE را باز کنید و از منوی Tools گزینهٔ Manage Libraries را بزنید (کلید میان‌بر Ctrl+Shift+I).
2. در کادر جست‌وجوی بالا نام کتابخانه را بنویسید؛ مثلاً DHT sensor library.
3. در فهرست نتایج، نسخهٔ سازندهٔ معتبر را انتخاب کنید (برای این مثال، Adafruit) و از منوی کنار دکمه، نسخه را بگذارید Latest مگر دلیل دیگری داشته باشید.
4. دکمهٔ Install را بزنید.
5. اگر پنجره‌ای باز شد و از نصب وابستگی‌ها (Dependencies) پرسید، Install All را بزنید؛ بعضی کتابخانه‌ها روی کتابخانه‌های دیگر سوارند و ردکردن این پنجره یعنی کامپایل بعدی شکست می‌خورد.

پس از پایان، نام کتابخانه باید در فهرست File ← Examples ← کتابخانه‌های نصب‌شده دیده شود؛ همین، تأیید موفقیت نصب است. IDE نیازی به ری‌استارت ندارد.

نصب دستی و نصب ZIP

بعضی کتابخانه‌ها در Library Manager نیستند — مثلاً نسخهٔ آزمایشی از صفحهٔ GitHub سازنده. دو راه دارید:

• فایل ZIP: از منوی Sketch به Include Library و بعد Add .ZIP Library بروید و فایل ZIP دانلودشده را انتخاب کنید؛ IDE خودش آن را استخراج و در جای درست می‌گذارد.
• پوشهٔ دستی: پوشهٔ کتابخانه را در مسیر Documents/Arduino/libraries کپی کنید. هر کتابخانه باید پوشهٔ خودش را داشته باشد، مثلاً Documents/Arduino/libraries/MFRC522. بعد از کپی، اگر IDE باز بود ببندید و دوباره باز کنید.

ساختار یک پوشهٔ کتابخانه

پوشهٔ استاندارد کتابخانه چنین شکلی دارد:

بخش examples/ گنج بی‌بدیل یادگیری است: تقریباً هر کتابخانه‌ای برای هر قابلیتش یک نمونهٔ اجراشدنی دارد. عادت حرفه‌ای: پیش از نوشتن هیچ کدی، اول نمونهٔ کتابخانه را آپلود و اجرا کنید تا مطمئن شوید سخت‌افزار و اتصال‌ها درست‌اند.

کتابخانه‌های پرکاربرد

کتابخانه‌های «همراه هسته» پیش‌نصب‌اند و include کافی است؛ بقیه را یک بار نصب می‌کنید.

اشتباهات رایج و عیب‌یابی

تمرین‌ها

#include <Servo.h>

Servo myServo;   // Create a servo object

void setup() {
  myServo.attach(9);  // Signal wire on pin 9
}

void loop() {
  for (int angle = 0; angle <= 180; angle += 5) {
    myServo.write(angle);
    delay(15);
  }
  for (int angle = 180; angle >= 0; angle -= 5) {
    myServo.write(angle);
    delay(15);
  }
}

:::

خلاصه

• کتابخانه بستهٔ کد آماده است؛ #include <Name.h> امکاناتش را به اسکچ اضافه می‌کند و < > برای کتابخانهٔ نصب‌شده و " " برای فایل کنار اسکچ است.
• روش اصلی نصب، Library Manager با Ctrl+Shift+I است؛ پنجرهٔ وابستگی‌ها را همیشه با Install All بپذیرید.
• نصب ZIP از Sketch ← Include Library و نصب دستی در Documents/Arduino/libraries برای کتابخانه‌های خارج از مدیر بسته است.
• پوشهٔ استاندارد کتابخانه سرآیند .h، پیاده‌سازی .cpp یا src/ و پوشهٔ examples/ دارد؛ نمونه‌ها بهترین نقطهٔ شروع‌اند.

حالا ابزار هر کتابخانه‌ای را می‌توانید به اسکچ اضافه کنید؛ در درس بعدی با I2C آشنا می‌شوید، پروتکلی که بیشتر کتابخانه‌های ماژول‌ها روی آن سوارند.