为 Arduino 编写一个库

        本文档介绍了如何为 Arduino 创建库。它从闪烁摩尔斯电码的草图开始，并解释了如何将其函数转换为库。这使得其他人可以轻松使用您编写的代码，并在您改进库时轻松更新它。

我们从一个执行简单摩尔斯电码的草图开始：

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()执行实际闪烁的函数。其次，有pin函数使用该变量来确定要使用哪个引脚。最后，用pinMode将引脚初始化为输出。

        下面让我们开始将草图变成一个库！

        一个库至少需要两个文件：头文件（扩展名为 .h）和源文件（扩展名为 .cpp）。头文件包含库的定义：基本上是内部所有内容的列表；而源文件包含实际的代码。我们将我们的库称为“Morse”，所以我们的头文件将是Morse.h。让我们看看里面有什么。乍一看可能有点奇怪，但是一旦您看到它附带的源文件，就会更有意义。

        头文件的核心由库中每个函数的一行组成，与您需要的任何变量一起包装在一个类中：

class Morse

{

 public://公共的

 Morse(int pin);//构造函数的特殊函数，用于创建该类的实例

 void begin();

 void dot();

 void dash();

 private://私有的

 int _pin;

};

        类只是函数和变量的集合，它们都保存在一个地方。这些函数和变量可以是公共的，这意味着使用您的库的人可以访问它们，也可以是私有的，这意味着它们只能从类本身内部访问。每个类都有一个称为构造函数的特殊函数，用于创建该类的实例。构造函数与类具有相同的名称，并且没有返回类型。

        头文件中还需要一些其他内容。一种是 #include 语句，可让您访问 Arduino 语言的标准类型和常量（这会自动添加到普通草图中，但不会添加到库中）。它看起来像这样（并且高于前面给出的类定义）：

1#include "Arduino.h"

最后，通常将整个头文件包装在一个看起来很奇怪的结构中：

#ifndef Morse_h

#define Morse_h

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

#endif

防止有人不小心加载两次库。

        最后，您通常会在库的顶部添加注释，其中包含库的名称、功能的简短描述、编写者、日期和许可证。

我们看一下完整的头文件：

#ifndef Morse_h

#define Morse_h

#include "Arduino.h"

class Morse

{

 public:

 Morse(int pin);

 void begin();

 void dot();

 void dash();

 private:

 int _pin;

};

#endif

        现在让我们浏览一下源文件 Morse.cpp 的各个部分。

        首先是一些 #include 语句。这些使其余代码可以访问标准 Arduino 函数以及头文件中的定义：

#include "Arduino.h"

#include "Morse.h"

            然后是构造函数。同样，这解释了当有人创建您的类的实例时会发生什么。在这种情况下，用户指定他们想要使用哪个引脚。构造函数将其记录在私有变量中，以便在其他函数中使用：

Morse::Morse(int pin)

{

 _pin = pin;//将传入的参数保存到私有变量_pin中。

}

        这段代码中有一些奇怪的事情。首先是函数名称之前的Morse:: 。这表示该函数是Morse类的一部分。您将在类中的其他函数中再次看到这一点。第二个不寻常的事情是我们的私有变量名称中的下划线，

        该变量实际上可以具有任何您想要的名称，只要它与头文件中的定义匹配即可。在名称开头添加下划线是一种常见的约定，以明确哪些变量是私有的，并且还可以将名称与函数参数的名称区分开来（在本例中为pin）。

        接下来，您将创建一个begin()处理硬件配置的函数。这将从setup()草图的功能。硬件配置是在专用函数而不是构造函数中完成的，因为在执行构造函数代码时硬件尚未初始化。在我们的库中，我们需要将引脚设置为输出：

void Morse::begin()

{

 pinMode(_pin, OUTPUT);

}

        然后是来自草图的实际代码，您将把它变成一个库（最后！）。它看起来几乎相同，除了函数名称前面有Morse:: ，并且_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);

}

最后，通常还会在源文件的顶部包含注释标题。让我们看看整个事情：

#include "Arduino.h"

#include "Morse.h"

Morse::Morse(int pin)

{

 _pin = pin;

}

void Morse::begin()

{

 pinMode(_pin, OUTPUT);

}

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);

}

        让我们看看您如何使用该库：

        首先，在sketchbook 目录的库子目录中创建一个Morse目录。将 Morse.h 和 Morse.cpp 文件复制或移动到该目录中。现在启动 Arduino 环境。如果打开“草图”>“导入库”菜单，您应该会在里面看到莫尔斯电码。该库将与使用它的草图一起编译。如果库似乎无法构建，请确保文件确实以 .cpp 和 .h 结尾（例如，没有额外的 .ino、.pde 或 .txt 扩展名）。

让我们看看如何使用新库复制旧的 SOS 草图：

#include <Morse.h>

Morse morse(13);

void setup()

{

 morse.begin();

}

void loop()

{

 morse.dot(); morse.dot(); morse.dot();

 morse.dash(); morse.dash(); morse.dash();

 morse.dot(); morse.dot(); morse.dot();

 delay(3000);

}

        与旧的草图有一些区别（除了一些代码已移至库中的事实）。

        首先，我们在草图顶部添加了 #include 语句。这使得莫尔斯库可用于草图并将其包含在发送到电路板的代码中。这意味着如果您不再需要草图中的库，您应该删除 #include 语句以节省空间。

其次，我们现在创建一个名为morse的 Morse 类的实例：

Morse morse(13);

        当这一行被执行时（这实际上发生在setup()函数），构造函数Morseclass 将被调用，并传递您在此处给出的参数（在本例中为 13）。

        最后，调用dot()和dash()函数，我们需要在它们前面加上morse前缀。我们要使用的实例的名称。我们可以有多个实例Morse类，每个都有自己的引脚，存储在该实例的 _pin 私有变量中。通过在特定实例上调用函数，我们指定在调用函数期间应使用哪个实例的变量。也就是说，如果我们两者都有：

Morse morse(13);

Morse morse2(12);

然后在通话中morse2.dot(),_pin将会是12。

        如果您尝试新的草图，您可能会注意到我们库中的任何内容都未被环境识别并以颜色突出显示。不幸的是，Arduino 软件无法自动找出您在库中定义的内容（尽管这将是一个很好的功能），因此您必须给它一些帮助。为此，请在 Morse 目录中创建一个名为keywords.txt的文件。它应该看起来像这样：

Morse KEYWORD1

begin KEYWORD2

dash KEYWORD2

dot KEYWORD2

        每行都有关键字的名称，后跟一个制表符（不是空格），然后是关键字的类型。类应为 KEYWORD1 且颜色为橙色；函数应为 KEYWORD2 并且为棕色。您必须重新启动 Arduino 环境才能让它识别新关键字。

        向人们提供使用您的库的示例草图也很好。为此，请在Morse目录中创建一个示例目录。然后，将上面编写的包含草图（我们称之为SOS）的目录移动或复制到示例目录中。如果您重新启动 Arduino 环境（我保证，这是最后一次）- 您将在“文件”>“示例”菜单中看到一个Library-Morse项目包含你的例子。您可能需要添加一些注释来更好地解释如何使用您的库。