如何给arduino编写库文件
给Arduino编写库文件
Loki于2014-8-29整理本文档解释了如果给Arduino创建库文件。先从描述一个会闪烁的摩斯码代码开始，再解释怎么样把它转换成库文件。这样你写的代码就能很容易地让别人使用，同时也方便你进行修改并更新它。
如果想了解更多，请查看API Style Guide，一个让你的库制作一个良好的Arduino 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);
}
如果你运行这个工程，它会在13引脚上闪烁来发送一个SOS信号（一个求救信号）。
我们需要把该工程一些不一样的地方放到我们的库里面去。第一，当然我们需要真正起作用（制造闪光）的dot()和dash()函数。第二，需要一个给函数用来确定哪个引脚需要使用的ledPin变量。最后，代码中调用了一个把引脚初始化为输出的函数pinMode()。
让我们开始把这个工程转换成一个库！
你最少需要两个库文件：一个头文件（扩展文件.h）和一个源文件（扩展.cpp）。这个头文件为库做了各种定义：把所有基础的东西都罗列在里面了；而源文件则包含着真实的代码。我们会把我们的库叫做“摩斯码”，所以我们的头文件就是Morse.h。让我们来看一看它是什么样的。它刚开始看起来有点奇怪，但是当你看了它的源代码之后，你就会觉得它越来越亲切了。
头文件的核心包括了：把库的每一个函数列出来；声明了一个有你需要变量的类：
class Morse
{
public:
Morse(int pin);
void dot();
void dash();
private:
int _pin;
};
一个类是把所有的函数和变量都集中到了一个地方。这些函数和变量可以是公共的（public），意味着能让使用你的库的人来调用这些函数和变量；当是私有的（private）时候，这些函数和变量只能在类里面进行调用。每一个类都有一个特殊的函数被叫做构造器
（constructor），一个用来创建类的实例的函数。这个构造器有着和类一样的名字，同时不能有返回类型。
你还需要对头文件做两件事情。一个是需要使用#include声明你调用了Arduino语言的标准类型和变量（这个会自动在普通的工程中进行声明，但是不会在库中自动声明）。它看起来像这样（大概就像事先给类进行定义）：
#include "Arduino.h"
最后，都会使用如下奇怪的结构把整个头文件放到里面去：
#ifndef Morse_h
#define Morse_h
// the #include statment and code go here...
#endif
显而易见，这样的结构是预防某人不小心调用了两次你的库。
最后，你通常会对库的名字在最开始的部分进行说明，简单的描述它是干嘛用的，谁写的，什么时候写的，还有谁可以使用它。
让我们看一下完整的头文件：
/*
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。
第一需要把两个声明包含进来。这些声明能够调用标准的Arduino 函数，还可以调用你在头文件以定义的内容。
#include "Arduino.h"
#include "Morse.h"
下面我们来说说构造器。它解释了当某人使用你的类创建了一个实例之后会发生什么。这种情况下，用户最关心的是他们能够使用哪个引脚。我们把这个引脚配置成输出并将它保存到一个私有变量里，用来给其他的函数进行调用。
Morse::Morse(int pin)
{
pinMode(pin, OUTPUT);
_pin = pin;
}
这段代码中有两个奇怪的东西。第一个就是函数名之前的Morse::。其实它是说明这个函数是Morse类的一部分。你会在类里面的其他函数中再次看到他。第二个不寻常的东西就是在我们的私有变量前有下划线，_pin。事实上，你可以给这个变量取任何你想要的名字，只要它能够跟头文件中所定义的对应上就可以。在名字的前面加下划线是一种清楚地表示它是一个私有变量的惯例，同时也能让它和函数的参数区别开来（在这个例子中的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);
}
这就是你需要做的（还有一些好玩的选项，我们之后再说）。让
我看看怎么样使用这个库。
在你软件文件夹的libraries文件夹下面新建一个名为Morse 的文件夹。把Morse.h和Morse.cpp文件复制到该文件夹下面。现在启动Arduino软件。如果你打开了Sketch > Import Library菜单，你会看到Morse也在里面。这个库会在使用到它的工程里面进行编译。如果没有看到该库，请确保文件名的后缀是.cpp和.h（举个例子，没有其他的.pde、.txt后缀）。
让我们看看怎么样在老的SOS工程里面使用新的库：
#include
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（）函数之前执行的），Morse类的构造器就会被调用，会传递你在这里给的参数（在这里是13）。
现在我们留意到我们的setup（）函数是空的，那是因为调用pinMode（）函数是在库里面进行的（当这个实例已经被构造前提下）。
最后，调用dot()和dash()函数，我们需要加一个前缀morse.-这个实例的名字是我们想用的。我们可以有很多个Morse 类的实例，每一个实例都有自己的存储在私有变量_pin里面的引脚。当调用某一个实例的函数时，我们会特殊地区分不同的实例用不同的变量来调用实例的函数。就像这样，如果我们有两个实例的话：
Morse morse(13);
Morse morse2(12);
当内部调用的morse2.dot(),_pin将会是12。
如果你新建一个工程，你可能会注意到我们的库没有被软件识别，也没有对其中的函数等进行高亮处理。不幸的是，Arduino软件不能自动地识别你在库中自己定义的东西（虽然这是个将来可能会有的功能），所以你必须给软件一些提示。要那样做的话，需要在Morse 文件夹下新建一个叫做keywords.txt的文件。它可以像下面这样：Morse KEYWORD1
dash KEYWORD2
dot KEYWORD2
每一行都有关键字的名字，中间有一个tab（不是space），后面接的是关键字的类型。类会让关键字1标记成橙色；函数让关键字标记成褐色。你需要重启Arduino软件来让它识别新的关键字。给人们一个例子，可以让人民很好的使用你的库。首先，在Morse文件夹下面新建一个examples的文件夹。然后，移动或者复制我们之前写的工程（让我们叫他SOS）到examples文件夹下面（你可以使用Sketch > Show Sketch Folder功能来找到这个工程）。如果你重启Arduino软件（我保证这是最后一次）-你将会看到你的例子在File > Sketchbook > Examples菜单Library-Morse项里面。你可能会想添加一些说明来更好的解释怎么使用你的库。
好了，库已经建立好了。如果你想了解更多，请查看API Style Guide来了解更多内容，让你可以制作一个良好的Arduino风格的API。