arduino库文件建立方法.docx

1、arduino库文件建立方法Writing a Library for ArduinoThis document explains how to create a library for Arduino. It starts 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 youve written and to easily update it

2、as you improve the library.For more information, see theAPI Style Guidefor information on making a good Arduino-style API for your library.We start with a sketch that does simple Morse code:intpin=13;voidsetup()pinMode(pin,OUTPUT);voidloop() dot();dot();dot(); dash();dash();dash(); dot();dot();dot()

3、;delay(3000);voiddot()digitalWrite(pin,HIGH);delay(250);digitalWrite(pin,LOW);delay(250);voiddash()digitalWrite(pin,HIGH);delay(1000);digitalWrite(pin,LOW);delay(250);Get CodeIf you run this sketch, it will flash out the code for SOS (a distress call) on pin 13.The sketch has a few different parts t

4、hat well need to bring into our library. First, of course, we have thedot()anddash()functions that do the actual blinking. Second, theres theledPinvariable which the functions use to determine which pin to use. Finally, theres the call topinMode()that initializes the pin as an output.Lets start turn

5、ing 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 thats inside; while the source file has the actual code. Well call

6、our library Morse, so our header file will be Morse.h. Lets 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.The core of the header file consists of a line for each function in the library, wrapped up in

7、a class along with any variables you need:classMorsepublic: Morse(intpin); voiddot(); voiddash(); private: int_pin;Get CodeA class is simply a collection of functions and variables that are all kept together in one place. These functions and variables can bepublic, meaning that they can be accessed

8、by people using your library, orprivate, meaning they can only be accessed from within the class itself. Each class has a special function known as aconstructor, which is used to create aninstanceof the class. The constructor has the same name as the class, and no return type.You need a couple of ot

9、her 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 Ard

10、uino.hGet CodeFinally, its common to wrap the whole header file up in a weird looking construct:#ifndef Morse_h#define Morse_h/ the #include statment and code go here.#endifGet CodeBasically, this prevents problems if someone accidently #includes your library twice.Finally, you usually put a comment

11、 at the top of the library with its name, a short description of what it does, who wrote it, the date, and the license.Lets 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 Mo

12、rse_h#define Morse_h#include Arduino.hclassMorsepublic: Morse(intpin); voiddot(); voiddash(); private: int_pin;#endifGet CodeNow lets go through the various parts of the source file, Morse.cpp.First comes a couple of #include statements. These give the rest of the code access to the standard Arduino

13、 functions, and to the definitions in your header file:#include Arduino.h#include Morse.hGet CodeThen 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

14、 as an output save it into a private variable for use in the other functions:Morse:Morse(intpin)pinMode(pin,OUTPUT); _pin=pin;Get CodeThere are a couple of strange things in this code. First is theMorse:before the name of the function. This says that the function is part of theMorseclass. Youll see

15、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 c

16、onvention to make it clear which variables are private, and also to distinguish the name from that of the argument to the function (pinin this case).Next comes the actual code from the sketch that youre turning into a library (finally!). It looks pretty much the same, except withMorse:in front of th

17、e names of the functions, and_pininstead ofpin:voidMorse:dot()digitalWrite(_pin,HIGH);delay(250);digitalWrite(_pin,LOW);delay(250);voidMorse:dash()digitalWrite(_pin,HIGH);delay(1000);digitalWrite(_pin,LOW);delay(250);Get CodeFinally, its typical to include the comment header at the top of the source

18、 file as well. Lets see the whole thing:/* 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.hMorse:Morse(intpin)pinMode(pin,OUTPUT); _pin=pin;voidMorse:dot()digitalWrite(_pin,HIGH);delay(250)

19、;digitalWrite(_pin,LOW);delay(250);voidMorse:dash()digitalWrite(_pin,HIGH);delay(1000);digitalWrite(_pin,LOW);delay(250);Get CodeAnd thats all you need (theres some other nice optional stuff, but well talk about that later). Lets see how you use the library.First, make aMorsedirectory inside of thel

20、ibrariessub-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 theSketch Import Librarymenu, you should see Morse inside. The library will be compiled with sketches that use it. If the library does

21、nt seem to build, make sure that the files really end in .cpp and .h (with no extra .pde or .txt extension, for example).Lets see how we can replicate our old SOS sketch using the new library:#include Morse morse(13);voidsetup()voidloop() morse.dot();morse.dot();morse.dot(); morse.dash();morse.dash(

22、);morse.dash(); morse.dot();morse.dot();morse.dot();delay(3000);Get CodeThere are a few differences from the old sketch (besides the fact that some of the code has moved to a library).First, weve added an #include statement to the top of the sketch. This makes the Morse library available to the sket

23、ch 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.Second, we now create an instance of the Morse class calledmorse:Morse morse(13);Get CodeWhen this line gets executed (which actually happe

24、ns even before thesetup()function), the constructor for the Morse class will be called, and passed the argument youve given here (in this case, just13).Notice that oursetup()is now empty; thats because the call topinMode()happens inside the library (when the instance is constructed).Finally, to call

25、 thedot()anddash()functions, we need to prefix them withmorse.- 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 i

26、nstances variables should be used during that call to a function. That is, if we had both:Morse morse(13);Morse morse2(12);Get Codethen inside a call tomorse2.dot(),_pinwould be 12.If you tried the new sketch, you probably noticed that nothing from our library was recognized by the environment and h

27、ighlighted in color. Unfortunately, the Arduino software cant automatically figure out what youve 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 calledkeywords.txtin the Morse directory. It should look like this:Mor

28、se KEYWORD1dash KEYWORD2dot KEYWORD2Get CodeEach line has the name of the keyword, followed by a tab (not spaces), followed by the kind of keyword. Classes should beKEYWORD1and are colored orange; functions should beKEYWORD2and will be brown. Youll have to restart the Arduino environment to get it t

29、o recognize the new keywords.Its also nice to provide people with an example sketch that uses your library. To do this, create anexamplesdirectory inside theMorsedirectory. Then, move or copy the directory containing the sketch (lets call itSOS) we wrote above into the examples directory. (You can f

30、ind the sketch using theSketch Show Sketch Foldercommand.) If you restart the Arduino environment (this is the last time, I promise) - youll see aLibrary-Morseitem inside theFile Sketchbook Examplesmenu containing your example. You might want to add some comments that better explain how to use your library.If youd like to check out the complete library (with keywords and example), you can download it:Morse.zip.Thats all for now but Ill probably write an advanced library tutorial soon. In the meantime, if you have any problems or suggestions, pleas