Writing a Library for Arduino

为Arduino编个扩展库

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.

  本文档介绍了如何创建一个Arduino扩展库。它将向你描述如何将一个摩尔斯的代码功能做成一个扩展库。这会使别人很容易使用你的代码,并且你也很方便的编辑和修改你的扩展库。

We start with a sketch that does simple Morse code:

我们从写一个简单的摩尔斯码开始:

If you run this sketch, it will flash out the code for SOS (a distress call) on pin 13.

  运行这段代码,会使Pin 13脚发出SOS紧急呼救信号。

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.

  代码有几个不同的部分,我们将其写入我们的库。首先,当然,我们有dot()和dash()功能,它们的功能为闪烁。其次,还要用ledpin变量来确定使用哪个针脚。最后,要用pinmode()函数来初始化引脚输出。

Let’s start turning the sketch into a library!

  让我们开始把程序写成扩展库!

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.

  你至少需要两个文件:一个头文件(扩展名为.h)和一个源文件(扩展名为.cpp)。头文件定义扩展库:基本上是一个原代码中所有东西的列表。我们引用我们的扩展库“Morse”,所以我们把头文件名写为“Morse.h”,让它看上去一目了然。它看上去有点奇怪,但它与源文件一起运行时将有更多的功能。

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:

  头文件的核心是一个扩展库中所有功能的列表,这个列表以及你所需要的所有的变量写在一个类里面:

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.

  类是一个简单的函数和变量的集合。这些函数和变量可以是公开的,以使别人可以使用你的扩展库。或者,他们只能从内部访问类本身。每个类有一个特殊的功能,称为构造函数,它是用来创建一个类的实例。构造函数与类具有相同的名字,它没有返回类型。

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

  在头文件里你还需要一些其他的东西。是一个#include声明,让你访问Arduino语言中的标准变量和常量(它自动添加,但不在扩展库中)。它看起来像这样(它将最开始运行):

Finally, it’s common to wrap the whole header file up in a weird looking construct:

  最后,它将把整个头文件打包进一个特殊的构造里:

Basically, this prevents problems if someone accidently #include’s your library twice.

  基本上,这可以防止别人不小心引用你两次库的问题。

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.

  最后,你通常会在顶部加入一些你自己的信息,比如库的名字、简短的描述、作者的名字、日期和许可。

Let’s take a look at the complete header file:

  让我们看一下完整的头文件:

Now let’s go through the various parts of the source file, Morse.cpp.

  现在让我们看看源文件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报表,它提供其余代码使用标准Arduino功能,并要写在文件开头:

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:

  然后是构造函数,再次说明当有人创建你的类的实例时会发生什么。在这种情况下,用户会指定要使用的针脚。我们将输出引脚的配置保存到一个私有变量用于其他功能:

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

  有一些特殊的东西在这个代码里。首先是在这功能名字前的Morse::。这表示,功能是摩尔斯电码的类。你会在这个类的其它功能里再次看到。其二是在私有变量名称前的下划线,_pin。这个变量可以是任何你想要的名字,只要匹配头文件中的定义。加下划线开始的名字是私有变量的约定,同时也从函数的功能段区分名字(在这种情况下)。

转载:http://www.geek-workshop.com/forum.php?mod=viewthread&tid=184

十一月 27th, 2016

Posted In: Arduino

发表评论