יצירת ספריות ל-Arduino

מדריך זה יסביר איך מייצרים ספריה לסביבת הפיתוח של Arduino. המדריך מתחיל בכתיבת תוכנית להבהוב לפי קוד מורס ואחרי זה מסביר איך להפוך את הפונקציות של התוכנית לספריה. הספריות מאפשרות לאנשים אחרים להשתמש בקוד שכתבתם וגם לבצע עדכונים אחרי שאתם משפרים את הספריה.

ראו מדריך לסגנון ה-API למידע נוסף על בחירה טובה של API בסביבת ארדואינו לספריה שלכם.

נתחיל מתוכנית שמייצרת קוד מורס פשוט:

קוד: בחר הכל

int pin = 13;

void setup()
{
    pinMode(pin, OUTPUT);
}

void loop()
{
    dot(); dot(); dot();
    dash(); dash(); dash();
    dot(); dot(); dot();
    delay(3000);
}

void dot()
{
    digitalWrite(pin, HIGH);
    delay(250);
    digitalWrite(pin, LOW);
    delay(250);
}

void dash()
{
    digitalWrite(pin, HIGH);
    delay(1000);
    digitalWrite(pin, LOW);
    delay(250);
}


אם תריצו את התוכנית, היא תהבהב קוד מצוקה (SOS) על קו 13.

לתוכנית יש כמה חלקים שונים שנצטרך להעביר לתוך הספריה שלנו. קודם כל, יש לנו את הפונקציות ()dot ו-()dash שמבצעות את ההבהוב עצמו. שנית, יש את המשתנה ledPin שהפונקציות משתמשות בו כדי לדעת איזה קו בשימוש. לבסוף, יש את הקריאה לפונקציה ()pinMode שמאתחלת את הקו למצב של פלט (output).

בואו נתחיל להפוך את התוכנית לספריה!

תצטרכו לפחות 2 קבצים: קובץ הגדרות (עם סיומת h.) וקובץ עם הקוד (עם סיומת cpp.). קובץ h. מכיל את ההגדרה/הצהרה של הספריה, סוג של רשימה של כל מה שכלול בפנים. קובץ cpp. מכיל את הקוד עצמו. נקרא לספריה שלנו "Morse", כך שקובץ ההגדרות יקרא Morse.h. בואו נראה מה נכנס לתוכו. זה יכול להראות קצת מוזר בהתחלה, אבל הדברים יראו הגיוניים יותר כשתראו את הקובץ עם הקוד.

הבסיס של קובץ ההגדרות הם רשימה של שמות הפונקציות בכל שורה, עטופות במחלקה (class), וגם שמות של משתנים שתצטרכו:

קוד: בחר הכל

class Morse
{
    public:
        Morse(int pin);
        void dot();
        void dash();
    private:
        int _pin;
};

מחלקה (class) היא אוסף של פונקציות ומשתנים שמקובצים יחד במקום אחד. פונקציות ומשתנים אלה יכולים להיות פומביים (public), מה שאומר שכל אחד שמשתמש בספריה שלכם יכול לגשת אליהם, או יכולים להיות פרטיים (private), מה שאומר שאפשר לגשת אליהם רק מתוך המחלקה עצמה. לכל מחלקה יש פונקציה מיוחדת שנקראת בונה (constructor), שנקראת כדי לייצר אובייקט של המחלקה (Class instance). לפונקציית בונה יש אותו השם כמו שם המחלקה והיא לא מחזירה ערכים.

אתם צריכים עוד כמה דברים בקובץ ההגדרות שלכם. הראשון הוא להוסיף פקודת include# שמספקת את הקבועים והגדרות הסטנדרטיות של שפת ה-Arduino (פקודה זו נוספת אוטומטית לתוכניות Arduino, אבל לא לספריות). זה נראה כך, והשורה מופיעה לפני הדגרת המחלקה של הספריה:

קוד: בחר הכל

#include "Arduino.h"

לבסוף, נהוג לעטוף את כל התוכן של קובץ ההגדרות במבנה מוזר שנראה כך:

קוד: בחר הכל

#ifndef Morse_h
#define Morse_h

// the #include statment and code go here...

#endif

למעשה, מבנה זה מונע בעיות במקרים שמישהו בטעות עושה include# לספריה שלכם כמה פעמים.

ועוד דבר אחד, בדרך כלל מוסיפים הערה בתחילת הקובץ עם שם הספריה, תיאור קצר של מה שהיא עושה, מי כתב אותה, תאריכים ורישיון לשימוש.

כך נראה כל קובץ ההגדרות:

קוד: בחר הכל

/*
  Morse.h - Library for flashing Morse code.
  Created by David A. Mellis, November 2, 2007.
  Released into the public domain.
*/
#ifndef Morse_h
#define Morse_h

#include "Arduino.h"

class Morse
{
    public:
      Morse(int pin);
      void dot();
      void dash();
    private:
      int _pin;
};

#endif

עכשיו בואו נעבור על החלקים השונים של קובץ הקוד, Morse.cpp.

בהתחלה יהיו כמה שורת עם פקודות include#. הן מספקות לשאר הקוד גישה לפונקציות הסטנדרטיות של Arduino ולהגדרות של המחלקה בקובץ ה-h. שיצרתם:

קוד: בחר הכל

#include "Arduino.h"
#include "Morse.h"

אחרי זה מגיעה פונקציית הבונה (constructor). הפונקציה מתבצעת כשמישהו מייצר אובייקט מהמחלקה שלכם (Class Instance). במקרה שלנו המשתמש מציין באיזה קו הוא רוצה להשתמש. אנחנו מגדירים את הקו הזה כפלט (Output) ושומרים אותו במשתנה פרטי שיהיה בשימוש ע"י פונקציות אחרות של המחלקה:

קוד: בחר הכל

Morse::Morse(int pin)
{
    pinMode(pin, OUTPUT);
    _pin = pin;
}

יש כמה דברים מוזרים בקוד הזה. קודם כל ה-"::Morse" לפני שם הפונקציה, זה אומר שהפונקציה היא חלק ממחלקת Morse. תראו את זה גם בפונקציות האחרות של המחלקה. דבר לא רגיל נוסף הוא קו התחתון בשם המשתנה הפרטי pin_. למשתנה זה יכול להיות כל שם שתרצו, כל עוד הוא תואם להגדרה בקובץ ה-h. הוספה של קו התחתון לפני השם היא גישה נפוצה לסימון ברור שהמשתנה הוא פרטיי (private), וגם כדי להבדיל אותו מהפרמטר שמועבר לפונקציה שבמקרה שלנו בשם pin (ללא הקו התחתון).

ואחרי זה סוף סוף מגיע הקוד מהתוכנית שאתם רוצים להפוך לספריה. הקוד נראה די דומה למה שהיה בתוכנית חוץ מהתוספת של ::Morse לפני שמות הפונקציות ושימוש ב-pin_ במקום pin.

קוד: בחר הכל

void Morse::dot()
{
    digitalWrite(_pin, HIGH);
    delay(250);
    digitalWrite(_pin, LOW);
    delay(250); 
}

void Morse::dash()
{
    digitalWrite(_pin, HIGH);
    delay(1000);
    digitalWrite(_pin, LOW);
    delay(250);
}

לבסוף, נהוג להוסיף הערות גם בתחילת קובץ הקוד. בואו נראה איך הכל נראה יחד:

קוד: בחר הכל

/*
  Morse.cpp - Library for flashing Morse code.
  Created by David A. Mellis, November 2, 2007.
  Released into the public domain.
*/

#include "Arduino.h"
#include "Morse.h"

Morse::Morse(int pin)
{
    pinMode(pin, OUTPUT);
    _pin = pin;
}

void Morse::dot()
{
    digitalWrite(_pin, HIGH);
    delay(250);
    digitalWrite(_pin, LOW);
    delay(250); 
}

void Morse::dash()
{
    digitalWrite(_pin, HIGH);
    delay(1000);
    digitalWrite(_pin, LOW);
    delay(250);
}

זה בגדול כל מה שצריך. יש עוד כמה דברים נחמדים שאפשר להוסיף, אבל הם אופציונליים ונזכיר אותם קצת יותר מאוחר. בואו נראה איך אתם משתמשים בספריה.

קודם כל, תייצרו תיקיה חדשה בשם Morse בתיקיית libraries בתוך תיקיית העבודות שלכם. תעתיקו או תעבירו את הקבצים Morse.h ו-Morse.cpp לתוך התיקיה שיצרתם. עכשיו תפעילו את סביבת הפיתוח של Arduino, אתם אמורים לראות ספריית Morse בתפריט Sketch > Import Library. הספריה תעבור הידור (compilation) יחד עם התוכניות שישתמשו בה. אם נראה שהספריה לא מיוצרת, בדקו את השמות והסיומות של הקבצים שהן אכן h. ו-cpp. ושאין אחרי זה כל מני תוספות כמו pde. או txt. למשל.

באו נראה איך אפשר לשכפל את תוכנית ה-SOS שלנו בעזרת הספריה החדשה:

קוד: בחר הכל

#include <Morse.h>

Morse morse(13);

void setup()
{
}

void loop()
{
    morse.dot(); morse.dot(); morse.dot();
    morse.dash(); morse.dash(); morse.dash();
    morse.dot(); morse.dot(); morse.dot();
    delay(3000);
}

יש כמה הבדלים מהתוכנית הישנה (חוץ מהעבודה שחלק מהקוד עבר לספריה). קודם כל הוספנו את פקודת include# בתחילת התוכנית, זה גורם לספריית Morse להיות זמינה לתוכנית ויכלול אותה בקוד שישלח בסופו של דבר לכרטיס הארדואינו. מה שאומר שאם אתם כבר לא צריכים את הספריה בתוכנית, צריך למחוק את ה-include# כדי לשמור על הזיכרון בכרטיס.

דבר נוסף הוא שעכשיו אנחנו מייצרים אובייקט של מחלקת Morse שנקרא morse:

קוד: בחר הכל

Morse morse(13);

כששורה זו מתבצעת (מה שלמעשה קורה עוד לפני פונקציית ()setup), הבונה (constructor) של מחלקת Morse יקרא ויועבר אליו פרמטר שציינו, שבמקרה שלנו זה מספר 13.

שימו לב כי פונקציית ()setup עכשיו ריקה מכיוון שהקריאה ל-()pinMode מתרחשת עכשיו בתוך הספריה (כשנוצר האובייקט של המחלקה).

לבסוף, כדי לקרוא לפונקציות ()dot ו-()dash צריך להוסיף קידומת .morse, שזהו השם של האובייקט שאנחנו רוצים להשתמש. אם נרצה, נוכל לייצר כמה אובייקטים של מחלקת Morse, כל אחד עם מספר הקו שישמר במשתנה pin_ הפרטי של אותו האובייקט. ע"י קריאה לפונקציה של אובייקט מסוים אנחנו מציינים באילו משתנים צריך להשתמש באותה הקריאה לפונקציה. כך למשל אם היו לנו שניי אובייקטים:

קוד: בחר הכל

Morse morse(13);
Morse morse2(12);

כך שבתוך הקריאה לפונקציה ()morse2.dot הערך של pin_ יהיה 12.

אם ניסיתם את התוכנית החדשה, כנראה ששמתם לב ששום דבר מהספריה החדשה לא מזוהה בתוך סביבת הפיתוח ולא מופיע עם צבעים. לצערנו סביבת פיתוח Arduino לא מסוגלת לזהות בצורה אוטומטית את מה שהגדרתם בתוך הספריה שלכם, כך שצריך לעזור לה קצת. כדי לעשות זאת, ייצרו קובץ בשם keywords.txt בתיקיית Morse. הקובץ צריך להיראות כך:

קוד: בחר הכל

Morse   KEYWORD1
dash    KEYWORD2
dot     KEYWORD2

כל שורה צריכה לכלול מילת מפתח, אחריה TAB (לא רווחים!) ואחריו מציין סוג של מילת המפתח. שמות המחלקות (Classes) צריכות להיות מסומנות כ-KEYWORD1 ויופיעו בצבע כתום, פונקציות צריכות להיות מסומנות כ-KEYWORD2 ויופיעו בצבע חום. תצטרכו להפעיל מחדש את סביבת הפיתוח כדי שהיא תקרא את קובץ מילות המפתח.

יהיה גם נחמד לספק לאנשים קובץ עם תוכנית לדוגמה שתעשה שימוש בספריה. כדי לעשות זאת, תייצרו תיקייה בשם examples בתוך תיקיית Morse. תעבירו או תעתיקו לשם תיקיה שכוללת את התוכנית שכתבנו קודם, בואו נקרא לה SOS. תוכלו למצוא איפה שמרתם את התוכנית בעזרת התפריט Sketch > Show Sketch Folder. אם שוב תפעילו מחדש (זו הפעם האחרונה!) את סביבת הפיתוח, תוכלו לראות רשומה Library-Morse בתוך תפריט File > Sketchbook > Examples שכוללת את הדוגמה שלכם. רצוי מאד להוסיף לתוכנית הדוגמה קצת הערות שיסבירו לאנשים איך הספריה שלכם פועלת.

אם תרצו לבדוק את הספריה בשלמותה (עם קובץ הגדרות מילות מפתח ודוגמה), תוכלו להוריד את הקובץ Morse.zip.

זה הכל. אם יש לכם איזה שהם בעיות או הצעות, תוכלו להודיע עליהם בפורום המפתחים.

ראו מדריך לסגנון כתיבת ה-API כדי ללמוד איך לכתוב ספריות בצורה טובה ומובנת, כדי שיתאימו לסגנון הכתיבה של ספריות Arduino האחרות.

ראו גם:

פירוט שפת תכנות לסביבת Arduino


עמוד זה הוא תרגום של Writing a Library for Arduino לפי רישיון Creative Commons Attribution-ShareAlike 3.0.