|
|
Writing a Library for Arduino
為Arduino編個(gè)擴(kuò)展庫(kù)
This document explains how to create a library for Arduino. It starts with a sketch with a sketch for flashing Morse code and explains how to convert its functions into a library. This allows other people to easily use the code that you've written and to easily update it as you improve the library.
本文檔介紹了如何創(chuàng)建一個(gè)Arduino擴(kuò)展庫(kù)。它將向你描述如何將一個(gè)摩爾斯的代碼功能做成一個(gè)擴(kuò)展庫(kù)。這會(huì)使別人很容易使用你的代碼，并且你也很方便的編輯和修改你的擴(kuò)展庫(kù)。
We start with a sketch that does simple Morse code:
我們從寫(xiě)一個(gè)簡(jiǎn)單的摩爾斯碼開(kāi)始：
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);
}
If you run this sketch, it will flash out the code for SOS (a distress call) on pin 13.
運(yùn)行這段代碼，會(huì)使Pin 13腳發(fā)出SOS緊急呼救信號(hào)。
The sketch has a few different parts that we'll need to bring into our library. First, of course, we have the dot() and dash() functions that do the actual blinking. Second, there's the ledPin variable which the functions use to determine which pin to use. Finally, there's the call to pinMode() that initializes the pin as an output.
代碼有幾個(gè)不同的部分，我們將其寫(xiě)入我們的庫(kù)。首先，當(dāng)然，我們有dot()和dash()功能，它們的功能為閃爍。其次，還要用ledpin變量來(lái)確定使用哪個(gè)針腳。最后，要用pinmode()函數(shù)來(lái)初始化引腳輸出。
Let's start turning the sketch into a library!
讓我們開(kāi)始把程序?qū)懗蓴U(kuò)展庫(kù)！
You need at least two files for a library: a header file (w/ the extension .h) and the source file (w/ extension .cpp). The header file has definitions for the library: basically a listing of everything that's inside; while the source file has the actual code. We'll call our library "Morse", so our header file will be Morse.h. Let's take a look at what goes in it. It might seem a bit strange at first, but it will make more sense once you see the source file that goes with it.
你至少需要兩個(gè)文件：一個(gè)頭文件（擴(kuò)展名為.h）和一個(gè)源文件（擴(kuò)展名為.cpp）。頭文件定義擴(kuò)展庫(kù)：基本上是一個(gè)原代碼中所有東西的列表。我們引用我們的擴(kuò)展庫(kù)“Morse”，所以我們把頭文件名寫(xiě)為“Morse.h”，讓它看上去一目了然。它看上去有點(diǎn)奇怪，但它與源文件一起運(yùn)行時(shí)將有更多的功能。
The core of the header file consists of a line for each function in the library, wrapped up in a class along with any variables you need:
頭文件的核心是一個(gè)擴(kuò)展庫(kù)中所有功能的列表，這個(gè)列表以及你所需要的所有的變量寫(xiě)在一個(gè)類(lèi)里面：
class Morse
{
public:
Morse(int pin);
void dot();
void dash();
private:
int _pin;
};
A class is simply a collection of functions and variables that are all kept together in one place. These functions and variables can be public, meaning that they can be accessed by people using your library, or private, meaning they can only be accessed from within the class itself. Each class has a special function known as a constructor, which is used to create an instance of the class. The constructor has the same name as the class, and no return type.
類(lèi)是一個(gè)簡(jiǎn)單的函數(shù)和變量的集合。這些函數(shù)和變量可以是公開(kāi)的，以使別人可以使用你的擴(kuò)展庫(kù)。或者，他們只能從內(nèi)部訪(fǎng)問(wèn)類(lèi)本身。每個(gè)類(lèi)有一個(gè)特殊的功能，稱(chēng)為構(gòu)造函數(shù)，它是用來(lái)創(chuàng)建一個(gè)類(lèi)的實(shí)例。構(gòu)造函數(shù)與類(lèi)具有相同的名字，它沒(méi)有返回類(lèi)型。
You need a couple of other things in the header file. One is an #include statement that gives you access to the standard types and constants of the Arduino language (this is automatically added to normal sketches, but not to libraries). It looks like this (and goes above the class definition given previously):
在頭文件里你還需要一些其他的東西。是一個(gè)#include聲明，讓你訪(fǎng)問(wèn)Arduino語(yǔ)言中的標(biāo)準(zhǔn)變量和常量（它自動(dòng)添加，但不在擴(kuò)展庫(kù)中）。它看起來(lái)像這樣（它將最開(kāi)始運(yùn)行）：
#include "WProgram.h"
Finally, it's common to wrap the whole header file up in a weird looking construct:
最后，它將把整個(gè)頭文件打包進(jìn)一個(gè)特殊的構(gòu)造里：
#ifndef Morse_h
#define Morse_h
// the #include statment and code go here...
// 把聲明和代碼寫(xiě)在這里
#endif
Basically, this prevents problems if someone accidently #include's your library twice.
基本上，這可以防止別人不小心引用你兩次庫(kù)的問(wèn)題。
Finally, you usually put a comment at the top of the library with its name, a short description of what it does, who wrote it, the date, and the license.
最后，你通常會(huì)在頂部加入一些你自己的信息，比如庫(kù)的名字、簡(jiǎn)短的描述、作者的名字、日期和許可。
Let's take a look at the complete header file:
讓我們看一下完整的頭文件：
/*
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 "WProgram.h"
class Morse
{
public:
Morse(int pin);
void dot();
void dash();
private:
int _pin;
};
#endif
Now let's go through the various parts of the source file, Morse.cpp.
現(xiàn)在讓我們看看源文件morse.cpp的組成。
First comes a couple of #include statements. These give the rest of the code access to the standard Arduino functions, and to the definitions in your header file:
首先是一組#include報(bào)表，它提供其余代碼使用標(biāo)準(zhǔn)Arduino功能，并要寫(xiě)在文件開(kāi)頭：
#include "WProgram.h"
#include "Morse.h"
Then comes the constructor. Again, this explains what should happen when someone creates an instance of your class. In this case, the user specifies which pin they would like to use. We configure the pin as an output save it into a private variable for use in the other functions:
然后是構(gòu)造函數(shù)，再次說(shuō)明當(dāng)有人創(chuàng)建你的類(lèi)的實(shí)例時(shí)會(huì)發(fā)生什么。在這種情況下，用戶(hù)會(huì)指定要使用的針腳。我們將輸出引腳的配置保存到一個(gè)私有變量用于其他功能：
Morse::Morse(int pin)
{
pinMode(pin, OUTPUT);
_pin = pin;
}
There are a couple of strange things in this code. First is the Morse:: before the name of the function. This says that the function is part of the Morse class. You'll see this again in the other functions in the class. The second unusual thing is the underscore in the name of our private variable, _pin. This variable can actually have any name you want, as long as it matches the definition in the header file. Adding an underscore to the start of the name is a common convention to make it clear which variables are private, and also to distinguish the name from that of the argument to the function (pin in this case).
有一些特殊的東西在這個(gè)代碼里。首先是在這功能名字前的Morse::。這表示，功能是摩爾斯電碼的類(lèi)。你會(huì)在這個(gè)類(lèi)的其它功能里再次看到。其二是在私有變量名稱(chēng)前的下劃線(xiàn)，_pin。這個(gè)變量可以是任何你想要的名字，只要匹配頭文件中的定義。加下劃線(xiàn)開(kāi)始的名字是私有變量的約定，同時(shí)也從函數(shù)的功能段區(qū)分名字（在這種情況下）。
余下的部分（全文完）：
Next comes the actual code from the sketch that you're turning into a library (finally!). It looks pretty much the same, except with Morse:: in front of the names of the functions, and _pin instead of pin:
接下來(lái)，源代碼終于變成一個(gè)擴(kuò)展庫(kù)。它們看起來(lái)非常類(lèi)似，除了函數(shù)名前有“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);
}
Finally, it's typical to include the comment header at the top of the source file as well.Let's see the whole thing:
最后，在源文件的頂部同樣有注釋部分。讓我們來(lái)看看整個(gè)源文件：
/*
Morse.cpp - Library for flashing Morse code.
Created by David A. Mellis, November 2, 2007.
Released into the public domain.
*/
#include "WProgram.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);
}
And that's all you need (there's some other nice optional stuff, but we'll talk about that later). Let's see how you use the library.
這就是所有你需要的（其它一些可選的東西，我們將在以后再談）。讓我們來(lái)看看如何使用擴(kuò)展庫(kù)。
First, make a Morse directory inside of the libraries sub-directory of your sketchbook directory.Copy or move the Morse.h and Morse.cpp files into that directory.Now launch the Arduino environment.If you
open the Sketch > Import Library menu, you should see Morse inside.The library will be compiled with sketches that use it.If the library doesn't seem to build, make sure that the files really end in .cpp and
.h (with no extra .pde or .txt extension, for example).
首先，在擴(kuò)展庫(kù)的子目錄建一個(gè)莫爾斯擴(kuò)展庫(kù)目錄。把Morse.h和Morse.cpp文件復(fù)制或移動(dòng)到該目錄中。現(xiàn)在打開(kāi)Arduino編譯器。打開(kāi)“Sketch”>“Import Library”菜單，你應(yīng)該看到有“Morse”選項(xiàng)。在使用的時(shí)候該擴(kuò)展庫(kù)將
同時(shí)被編譯。如果沒(méi)有看到這個(gè)擴(kuò)展庫(kù)，請(qǐng)確保文件名為正常的“.cpp”和“h”（沒(méi)有其它多余的如“.pde”或“.txt”這樣的擴(kuò)展名）。
Let's see how we can replicate our old SOS sketch using the new library:
讓我們看看現(xiàn)在我們?cè)鯓佑眯碌臄U(kuò)展庫(kù)來(lái)編寫(xiě)我們的原先的程序：
#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);
}
There are a few differences from the old sketch (besides the fact that some of the code has moved to a library).
除了將一些代碼已經(jīng)轉(zhuǎn)移到擴(kuò)展庫(kù)里，代碼有些差別。
First, we've added an #include statement to the top of the sketch.This makes the Morse library available to the sketch and includes it in the code sent to the board.That means if you no longer need a library
in a sketch, you should delete the #include statement to save space.
首先，我們僅需要在代碼頂部添加#include語(yǔ)句，就可以使程序使用這個(gè)擴(kuò)展庫(kù)，并且在編譯時(shí)會(huì)被同時(shí)包括進(jìn)去。這也意味著你在程序中不需要再編寫(xiě)長(zhǎng)長(zhǎng)的代碼。而且如果你不再需這個(gè)功能，你只要?jiǎng)h除這個(gè)“#include”語(yǔ)句
就可以了。
Second, we now create an instance of the Morse class called morse :
現(xiàn)在，我們來(lái)創(chuàng)建一個(gè)莫爾斯類(lèi)的實(shí)例：
Morse morse(13);
When this line gets executed (which actually happens even before the setup() function), the constructor for the Morse class will be called, and passed the argument you've given here (in this case, just 13 ).
當(dāng)此行被執(zhí)行時(shí)（實(shí)際甚至在setup()函數(shù)之前），將引用莫爾斯類(lèi)（這個(gè)例子里中針腳13）。
Notice that our setup() is now empty; that's because the call to pinMode() happens inside the library (when the instance is constructed).
請(qǐng)注意，在這里“void setup()”是空的，這是因?yàn)椤皃inMode()”的調(diào)用發(fā)生在擴(kuò)展庫(kù)中（在調(diào)用函數(shù)的時(shí)候）。
Finally, to call the dot() and dash() functions, we need to prefix them with morse. - the name of the instance we want to use.We could have multiple instances of the Morse class, each on their own pin stored
in the _pin private variable of that instance.By calling a function on a particular instance, we specify which instance's variables should be used during that call to a function.That is, if we had both:
最后，調(diào)用“dot()”和“dash()”函數(shù)時(shí)，我們需要用“morse”作它們的的前綴。程序中我們可以多次使用這個(gè)引用，它們每個(gè)的針腳數(shù)據(jù)都儲(chǔ)存在“_pin”私有變量里。我們可以有多個(gè)實(shí)例莫爾斯類(lèi)，每一個(gè)都有自己的針_pin
該實(shí)例的私有變量存儲(chǔ)。在某個(gè)程序中調(diào)用函數(shù)時(shí)，我們指定的每個(gè)針腳變量，都僅是在函數(shù)調(diào)用過(guò)程中被使用。也就是說(shuō)，如果我們有兩次調(diào)用：
Morse morse(13);
Morse morse2(12);
then inside a call to morse2.dot() , _pin would be 12.
后面的私有變量“_pin”將會(huì)是針腳12 。
If you tried the new sketch, you probably noticed that nothing from our library was recognized by the environment and highlighted in color.Unfortunately, the Arduino software can't automatically figure out
what you've define in your library (though it would be a nice feature to have), so you have to give it a little help.To do this, create a file called keywords.txt in the Morse directory.It should look like
this:
如果你嘗試使用新的的sketch，你會(huì)看到我們的擴(kuò)展庫(kù)沒(méi)有被認(rèn)可，并且用高亮顯示出來(lái)。不幸的是，Arduino軟件不能自動(dòng)找出你在擴(kuò)展庫(kù)中已經(jīng)定義的功能（雖然這將是一個(gè)很好的功能），所以你必須給它一個(gè)小小的提示。 要
做到這一點(diǎn)，我們要在Morse擴(kuò)展庫(kù)目錄中創(chuàng)建一個(gè)名為“keywords.txt”的文件。它的內(nèi)容是這樣的：
Morse KEYWORD1
dash KEYWORD2
dot KEYWORD2
Each line has the name of the keyword, followed by a tab (not spaces), followed by the kind of keyword.Classes should be KEYWORD1 and are colored orange; functions should be KEYWORD2 and will be brown.You'll
have to restart the Arduino environment to get it to recognize the new keywords.
每行有一個(gè)關(guān)鍵字，后面有個(gè)tab（注意，不是空格），再后面是keyword.Classes類(lèi)，KEYWORD1是橙色;函數(shù)KEYWORD2是棕色。你必須重新啟動(dòng)Arduino的環(huán)境，找到到新的關(guān)鍵字。
|
|
QQ好友和群
QQ空間
騰訊微博
騰訊朋友
收藏
淘帖
頂
踩
