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.
Bookmark this on Delicious
Recommend to StumbleUpon
This essay was written to support some pages I have about using the http://www.nuelectronics.com datalogging shield, but the skills and examples here have broader applicability. (That site had not been reachable for a while at 3/13. Please let me know if you find "them" again.)
This is, to be honest, done in haste... apologies for rough edges... but the concepts aren't complex. Sorry I rambled on in places... just skim!
A quick point before the work begins: You do not need the OneWire library from the Arduino home page to use the 1-Wire chips in, and associated with, the nuelectronics datalogging shield. (All will be revealed as needed, elsewhere.) Do not get confused, by the way, about the similarity of the terms "one wire" (used by nuelectronics) and "1-Wire" (a trademark). You may want to visit the brief note I've done on the subject.
However, to use at least some of the features of the nuelectronics datalogging shield, you will need the "sensor_pff" library which was once upon a time available from nuElectronics. At 3/13, 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?)
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". It 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.)
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.)
Much of the rest of this is no longer valid. At Oct 15, Arduino IDE 1.6.5, libraries are distributed, installed differently than they were at the time I wrote this essay.
It seems they are now put in a "libraries" folder inside whatever folder you have designated as where your sketches should go. (You may, of course, be using the default folder.)
Installing a library, if it is supplied in .zip form, is now a case of....
Open Arduino IDE, click on "Sketch", "Include Library", "Manage Libraries", "Add .ZIP Library"... and navigate to where the .zip file is on your machine. And then Things Happen. Not my preferred solution, but I imagine the people behind it worked hard, meant well. Sigh.
Where have they "put things"? In a "libraries" folder inside my "Sketches" folder, it would seem. I guess I'll need to adapt the way I use the "Sketches" folder. (In the past, from time to time, I would "move on" to a new one, the successive folders having names like "ArduinoProgramsSince2015-09". But if I move folders now, I lose installed libraries. Maybe I can just copy them forward. Sigh.
Once you have downloaded the .zip, and saved it on your hard drive, double click on it, and a Windows Explorer view of the zip's contents should appear, and they should be a single folder. It should have a name that's connected with what the library is about. In the case of the library above, for instance, the folder is called IRremote.
You need to drag that folder to the right place on your disk. The easiest way to do this is to open a separate Windows Explorer on your desktop, and navigate down to the destination folder. (The easy way to start a second instance of Windows Explorer is to hold down the Windows key, then press and release "E", and then release the Windows key.)
In "the good old days" before Windows 7, when you dragged the folder from within the zip file to its new "home", it was unzipped automatically as part of the copy process. (Ah, for the good old days of XP. and the older, gooder (well, maybe not) days of WinZip. Gone but not forgotten.)
Win7, "being helpful", makes it a little less clear as to whether you are looking at a file, or at what you would be looking at if an .zip archive you were looking in had been unzipped. To make the contents of a zipped library useable to the Arduino software, you almost certainly need to use the "extract all..." choice from Windows 7's Windows Explorer's right-click menu. Sigh. Aren't you glad Windows was made more complex, "to help you"?
Now... what is "the right place" for that unzipped copy of library??
Some references will tell you to put it in your sketchbook folder. As my sketchbook folder is within "My Documents", and therefor easy to see, backup, manage, etc, that would, in some ways, suit me. But not in other ways, and anyhow: For me that didn't work. Maybe because of where I put my sketchbook folder, or because I use folders within the folder.
The other place you can put libraries is in... ta! da!... is your Arduino "libraries" folder! Annoying, if you want to keep clear what was part of the basic Arduino development environment, and what was an add on, but this can't (?) be helped. A simple text file in the relevant folder will help. Where is the Arduino "libraries" folder? On a Windows machine, if you drill down into....
C:\Program Files
... then within that, you should find an Arduino folder. Be careful! If, like me, you've installed more than one version of the Arduino development environment, you need to find the folder of the environment you are currently using. Within that, you should find a "libraries" sub folder. Within it you will find folders for the standard libraries.... EEPROM, Ethernet, SoftwareSerial, Wire, etc.
This is the right destination for the folder in the zip library. Add the folder from the zip to the folder with your other libraries, and "presto"... you have another library available to you! Oops... almost presto. I think you have to restart the Arduino dev elopement environment if it was already running when you did the copy. At least, however, you don't need to restart Windows.
((Additonal notes, added 3/15, using Arduino 1.0.6 on a Win7 machine....)
At this time (3/15), I had another look at the "where" question. Many applications have "library path" fields which you can populate. I didn't find such a field for Ardunino... not that I think there "ought" to be one. Nor did I find anything in the Arduino Properties.txt ini file, which you should only mess with very respectfully... mess that up, and you could be in a world of hurt.
I put a 3rd party library on my Win7 system, in the "proper" place...
C:\Program Files (x86)\Arduino\libraries\
... with some difficulty. There are permissions issues you may have problems with. I was able to drag and drop and unzip in one fell swoop within Windows Explorer. When I tried to add a small text file to the contents of the folder, to document it: Hassle. Couldn't Just Do It... but could drag and drop a text file CREATED elsewhere to the folder, once I'd put what I wanted in it. BAH!
Anyway... having done that, I had access. (Always best to stop/ restart the Arduino development software if you have tinkered with the libraries. (True of many such programs.)
(End, "Additional notes... 3/15)
Now that you have your new library in place, how do you use it?
The library's web page will almost certainly have examples and documentation. There may be example programs within the folder the library is 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 subroutines, etc, provided in the library. 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", says "number in hex follows"). Don't worry now about why you would want to send A90... just trust me on that one... you might want to!
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 where to look for things.
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. That will create the "#include<IRremote.h>" line in your code. It will even put it 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.
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 did that when you copied the libraries folder to the right place on your hard drive. 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) of which you are going to avail yourself! You could probably type it by hand almost as fast as you are going to get it with the "Sketch/ Import" method... but that method has the advantage of checking that the Arduino development environment knows about the thing you think it knows about!
The library, by the way, has the software for READING signals from controllers, too. And http://www.nuelectronics.com will sell you a good sensor for about $3. You don't need their datalogging shield to use the sensor. (I've even done a tutorial on reading commands from TV remote controls... what a surprise!)
- - - - - - - - - - - - -
Oh dear. Too much said in some places. Not enough in others. I hope, though, even in this early state, that there is some useful material in the above?
Now that you know about libraries, even if you don't find yourself wanting the IRremote library, if you ever want to connect serial devices to your Arduino, but not via pins 0 and 1, then install the "new" library "NewSoftSerial", (available from main Arduino site), and use that in preference to the old, standard, "SoftwareSerial". (If your Arduino development environment is newer than version 18, you may find that NewSoftSerial has been incorporated as a standard package. But if it hasn't, you know a man (or woman) who can install it for you.... you!)
-------------------
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!
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.
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.
Click here to visit editor's Sheepdog Software (tm) freeware, shareware pages.
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?
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.
....... P a g e . . . E n d s .....