HOME  »  ARDUINO MAIN PAGE »  HINTS AND HOW-TOs
Delicious.Com Bookmark this on Delicious    StumbleUpon.Com Recommend to StumbleUpon

Using Arduino Libraries


Software Libraries- packages of useful stuff

This is done in haste... apologies for rough edges... The concepts aren't complex. And Libraries are exceedingly useful. Sorry I rambled on in places... just skim!

An aside: This page started life to support some pages about the NuElectronics datalogging shield. NuElectronics seems to be gone, but maybe you'll have one. To use it, you may want the "sensor_pff" library which was once upon a time available from NuElectronics. As the NuElectronics site had been unreachable for a while, I have put a copy of the "sensor_pff" library, as a .zip file, on my site for you to download. I didn't look at it very closely, if you see things in it I should not be distributing, please let me know. (I've no doubt the contents are safe and decent... but there may be copyright issues?)

Libraries...

The story starts with subroutines. You should be using them in your own programming to "wrap up" things that are logical entities. For instance, a burglar alarm program might entail a subroutine called "RingTheBell". The subroutine would take care of the details, so that, "higher" in the program, when it was time for the bell to start ringing, all that would appear would be "RingTheBell()".

The story goes on to fancier subroutines which accept parameters and/or return values. You could, for instance, (in some other program) have a function called AddThem, to which you pass two numbers, and from which you get back the total resulting from adding those number together... e.g.

int iFirst=5;
int iSecond=10;
iAnswer=AddThem(iFirst,iSecond);

You could, of course, write such subroutines and incorporate them directly into your program, especially for such simple functions, or for functions of little use beyond a single program.

Another thing you may want to do is to create new constants, types and classes. While this isn't something beginners frequently do, it is possible! (Don't worry about them, if not familiar.)

Now suppose you had some subroutines, etc, that you wanted to use frequently, wanted to use in lots of programs. With a little learning, you could create a library! Stored in the right place, it would let you put nothing more than #include<MyLibrary.h> at the start of your program, and, through that, have access to all the frequently used things that you packed away in the library!

But enough about building your own libraries! A delight for the future! This essay is about how you can use other people's libraries... and first, a word on why you would want to!

You'd want to because it gives you simple access to some stuff that can be very useful, even though, (beneath the level you need to concern yourself with,) it is very complex.

And there's good news: The libraries aren't tightly bound to the rest of your Arduino development environment. Don't worry about messing it up.

There's a discussion of using Arduino libraries at the official Arduino site, too, of course!

As an example, we will look at installing an using the infra-red control device library available from...

http://www.arcfn.com/2009/08/multi-protocol-infrared-remote-library.html

(You can also fetch that with http://tinyurl.com/ArduInfra if the tinyurl is easier for you for some reason.)

(If you go there, you'll see something about "GitHub". I explain "GitHub" further down the page.)

Like most libraries, that is supplied as a zip folder. (Some things I say in this section are expressed in Windows' terms. Those of you using Linux or Mac machines will have to make allowances. Sorry.)

What is adding a library all about, in practice?

Before we talk about adding a library, take a moment to think about how you added the Arduino IDE (Integrated Development Environment... the software that lets you "do Arduino").

Trusting, you went off to the web, and downloaded something. And then you said "go", and it set the IDE up... putting all sorts of "stuff" on your hard drive. And then you launched the IDE, and a program ran on your computer doing... you really don't know what, do you?

But the Arduino IDE, and the site it comes from, have been around for a long time, and if it did Bad Things, we'd probably know about it by now.

You don't, I hope, rummage around obscure corners of your hard drive, deleting things when you don't know what they are? That way lies MANY tears! You really need to know a lot about something before you can say it is not important. Not knowing what something is is a world away from knowing it is not important. Modern computer systems became way too complex for that, a long time ago.

So... if you want to be careful about what is on your machine... good luck to you. But we have to try.

There are many excellent third party libraries out there in internet-land. But there are probably some Bad Things lurking out there too, "wolves" in "nice third party library" clothing.

So here's how I prefer to proceed....

If I hear of a library, I am much more likely to give it a try if I can download a .zip, unzip that to a "scratch" folder, and have a little look around the code. (After scanning it with my anti-malware support, of course.)

And Arduino libraries should be very "happy" to let me (or you) do this. Most (all?) will involve an .h file and a .cpp file. Maybe more than one. Despite the extensions (.h, .cpp), these are just text files. Open them with whatever text editor you like. (I'm a longtime fan of TextPad. Free evaluation demo, without silly restraints.)

Anyway... though I can't make sense of all I read in these files... the fact that nothing is hidden greatly reassures me.

There's a second issue here, too: If I install this library, and later want to, say, move my Arduino work to a second computer, or upgrade to a newer version of the IDE, will the library still be available? Well, yes... If I've kept the files. They aren't "setup files". Nothing obscure has to be "done" to "install" them. They just have to be present on your hard drive, in a place that the IDE knows about. (More on that latter bit in a moment.)

Now. That's only half of the issues. My wants and worries have been taken care of.

The IDE isn't magic. And humans are unreliable. So sometime around 2015 the Arduino IDE had a big improvement incorporated.

Before the improvement, adding a library was a bit of a "thing". You either trusted an "install" routine, or you had to put copies of things in "the right place", and manage what "the right place" was.

Now it is all very much better.

You still have as much control as you like over "what's on my computer". And total freedom to archive everything associated with a new library. But the IDE will "take a copy" of "the stuff", for its purposes. Here's how I manage the process of keeping me AND the IDE happy....

When I see a library I want to use, I fetch the .zip. In whatever place you like, you should keep a copy of the .zip, and a folder with what was in the zip, unzipped. (The latter is not ENTIRELY necessary... but can be helpful.)

As mentioned before, the .zip may contain more than just the files essential to the library. There will often be demo programs, and sometimes text documents telling you what the features of the library are, and how to use them.

I keep my third party libraries in a folder called "ThirdPartyLibs", with a separate folder for each one. When I'm being really efficient, I add a little text file to the folder, noting where the contents came from.

Within the folder dedicated to a given library (that folder itself being inside "ThirdPartyLibs"), I create a folder "Unzipped", and put (you can figure it out!) in that.

NOW comes the clever bit...

So far it has been all about my wants. Now we're going to address the IDS's wants.

Fire up the IDE. (The following "blow-by-blow was drafted in March 17 using Arduino 1.8.1 on a Windows 7 PC.)

Invoke Sketch/ Include Library/ Add .Zip Library

Don't worry! Although you CAN add a library directly from a .zip file, if you wish, the same path takes you to the process for adding library files which have already been extracted from any .zip file they may have been in.

If you are adding a library using un-zipped files, change the "Files Of Type" field at the bottom of the "Open" dialog which doing what I've told you should have brought up on your screen. Change it to "All Files".

Navigate to the folder with the files that constitute the library you want to have available to your Arduino programming.

(Don't worry about selecting any of them...) Just click the Open button, once you've navigated to the right folder.

The Arduino IDE will take COPIES of the files, put them where it needs them. Yes...this is almost the "let it do (mysterious) things" that I don't like about ordinary installs. I don't know WHERE the IDE will put those copies, what (Arduino IDE) config files it will mess with. But at least I have backup copies of the necessary files, and I know what went "into" the Arduino IDE installation on my machine!

That's it! Library ready for use! You don't have to restart the IDE. You certainly don't have to restart the PC. Just use "Sketch/ Include Library", and scroll down through the libraries available until you come to the one you just installed!

Using the new library

Here's how you USE a new library, once it is in place. Really easy!

The library's web page will almost certainly have examples and documentation. There may be example programs within the .zip the library came in, often within a sub-folder called "examples".

In every case, you will have to add a line (or more) to the start of the program that is going to use any subroutines, etc, provided by the library. (Demos will probably have the necessary line in them already.)

Remember the good news: You don't have to know HOW the library does the things it does. You just have to know "the new words" that the library has "added" to your Arduino's "language". In the case of the IR library we've been discussing, one such new word is "SendSony". If you had an IR LED (and current limiting resistor) connected to pin 12 of your Arduino, and said "sendSony(0xA90,12);" the LED would "flash" exactly like the IR LED in a Sony remote control sending hex A90. (The "0x" ("zero ex", not "oh ex") says "number in hex follows"). Don't worry now about what "hex" is, or why you would want to send hex A90... just trust me on that one... you might want to one day! And when that day comes, the library makes it all REALLY easy.

Actually, I've simplified things a little. You'd actually need to say something like....

MyIR.sendSony(0xA90,12);

We'll come back to the "MyIR." part in a moment. First I'd like to stress that the "sendSony()" has to be exactly as shown. That was defined in the library, and you can't easily change it. In the case of sendSony, there needs to be two numbers, separated by a comma, inside the parentheses. I told you earlier what they specify. How did I know that the word was sendSony, and that the numbers are done like this? By looking at the example supplied with the library.

Now for the "MyIR." part.

Also within the library a class called IRsend was created. Again, that name is pretty inflexible. Early on in my program, but after the #include<> we'll discuss in a moment (last "new" thing"), you need to put something like...

IRsend MyIR;

You can't change the first word; the second word is something you choose. Once you have this line in your program, you can (and should) put the equivalent of "MyIR." in front of words which come from the IRsend class, which was set up for you inside the IRremote library. I'm new to C, and don't know the C-speak (which is also Arduino-speak) for the concepts, but in parallel universes, we would say that with "IRsend MyIR;" you are creating an instance of an object of class "IRsend". IRsend is a concept, defined within the library. "Concepts" are hard to work with. "Statesman" is a concept. Nelson Mandela is an instance of a statesman. A specific, named instance. One you can work with. Notice that "IRsend MyIR;" looks and works almost like, say, "int iTmp;", which would create a variable called iTmp, of the type "int". You can't change the word "int", but you can make up the name you want for the instance of an int type variable that you want to use in your program.

And now for the last thing.

If you just put "IRsend MyIR;" in your program, the compiler will complain. It hasn't heard of the "IRsend" class, can't make an instance of it. That's where the....

#include<IRremote.h>

... line comes in. You put it at the start of your program. With that in place, your program will compile. The Arduino compiler looks through all the words it knows before giving up on compiling something, and it looks in any libraries it has been told to check... for this program. The "#include<IRremote.h>" was where you told the compiler about the extra place to look for things. (You can include more than one library in a project, by the way, so the compiler will look in multiple places.)

A moment ago I told you to put the "#include<IRremote.h>" line in. But you don't have to type it by hand. If you have the library properly installed on your system, all you have to do is click on the "Sketch" menu item, and then the "Import library..." item on the sub-menu that arises. Then click on the name of the library you want your program to incorporate. All that does is to add the "#include<IRremote.h>" line in your code. But it doesn't make typos. And it makes sure that the library you want to use is actually present. And it puts the line at the top of the file, which is pretty well the right place. If you want it below a few rems, that's okay, but leave it near the top. Might as well use the "Import library..." convenience. Don't be worried about "What is this doing to my code? What problems will be added that I don't even know where to go looking to fix?"

I found the menu item's text, "Import library" confusing. The development environment is not talking about importing or installing a new library into the development environment. You do that separately, once and for all. (Explained above.) The "Sketch / Import Library" function is merely adding the right line of code (the "include" line) to your program, so that the compiler will know where to look for the "extra features" (from the library) you want to avail yourself of!

- - - - - - - - - - - - -


Getting libraries from GitHub

GitHub has been around for a long time. I know lots of sensible people use it, like it. I'm not terribly familiar with it.

Not infrequently, if you want a third party library, you will be sent to a GitHub page, which may look a bit like...

-

... well. May look like that, after you discover "the trick".

Don't be put off by what looks like a directory structure, on the left. You don't need that. What you do need to do is make your browser window wide enough for the "Clone or Download" button to appear. In the image above, you see what you should see after you click that. Having clicked the small black "Clone or download", select the bigger, blue, "Download Zip"... and you will... download the zip! Easy. Once you find the "download" button!





-------------------

See Also: The Arduino programming course from Sheepdog Guides:

Further to the Arduino ideas the page you are reading now will take you to, I have posted a series of essays which try to help you become a better Arduino programmer and engineer... but, for the best result, you will have to buckle down and work your way through them in sequence. The "How To's" here can be accessed in whatever order you like.


Feel free to use this information in programming courses, etc, but a credit of the source would be appreciated. If you simply copy the pages to other web pages you will do your readers a disservice: Your copies won't stay current. Far better to link to these pages, and then your readers see up-to-date versions. For those who care- thank you- I have posted a page with more information on what copyright waivers I extend, and suggestions for those who wish to put this material on CDs, etc.






Have you heard of Flattr? Great new idea to make it easy for you to send small thank you$ to people who provide Good Stuff on the web. If you want to send $$erious thank yous, there are better ways, but for a small "tip" here and there, Flattr ticks a lot of boxes which no one else has found a way to do yet. Please at least check out my introduction to Flattr, if you haven't heard of it? "No obligation", as they say!




Editorial Philosophy

See the discussion near the bottom of the "top level" page covering the bulk of my Arduino contributions. There is information there, too, about things like "May I copy your material?", and the system of file names I am trying to work to.


   Search this site or the web        powered by FreeFind
 
  Site search Web search
Site Map    What's New    Search

The search engine is not intelligent. It merely seeks the words you specify. It will not do anything sensible with "What does the 'could not compile' error mean?" It will just return references to pages with "what", "does", "could", "not".... etc.
In addition to the information about the NuElectronics data shield of which this page is part, I have other sites with material you might find useful.....

Tutorials about the free database which is part of the free Open Office.
Sequenced set of tutorials on Pascal programming and electronics interfacing.
Some pages for programmers.
Using the parallel port of a Windows computer.

If you visit 1&1's site from here, it helps me. They host my website, and I wouldn't put this link up for them if I wasn't happy with their service... although I was less than pleased the other day to have what I was doing interrupted by a telephone call from their sales team, trying to get me to extend my involvement. Sigh. Hardly a rare event, but I'd thought 1&1 were a bit classier that some of the people who have my telephone number.



Ad from page's editor: Yes.. I do enjoy compiling these things for you... hope they are helpful. However.. this doesn't pay my bills!!! If you find this stuff useful, (and you run an MS-DOS or Windows PC) please visit my freeware and shareware page, download something, and circulate it for me? Links on your page to this page would also be appreciated!

Click here to visit editor's Sheepdog Software (tm) freeware, shareware pages.


And if you liked that, or want different things, here are some more pages from the editor of these tutorials....

Click here to visit the homepage of my biggest site.

Click here to visit the homepage of Sheepdogsoftware.co.uk. Apologies if the "?Frmar3ne1libs" I added to that link causes your browser problems. Please let me know, if so?

Click here to visit editor's pages about using computers in Sensing and Control, e.g. weather logging.



To email this page's editor, Tom Boyd.... Editor's email address. Suggestions welcomed!


Valid HTML 4.01 Transitional Page tested for compliance with INDUSTRY (not MS-only) standards, using the free, publicly accessible validator at validator.w3.org. Mostly passes. There were two "unknown attributes" in Google+ button code. Sigh.


Why does this page cause a script to run? Because of the Google panels, and the code for the search button. Why do I mention the script? Be sure you know all you need to about spyware.

....... P a g e . . . E n d s .....