Arduino - Examples and Libraries
From the Arduino IDE menu, Examples are accessed via
By default, these examples are read only.
Programs that you write, and Examples you modify,
are accessed via
To add a library to your program, use
Sketch / Import Library...
|
Directories
| What is a Library?
- keywords.txt
| Adding a Library to the System
| Adding a Library to your program
| Writing your own
| References
Directories
These are the 4 directories on my Windows Vista system
that contain the Examples and Libraries.
Your system is probably a bit different, but the general structure will be the same.
C:\downloads\Arduino\arduino-1.0.5-windows\arduino-1.0.5\examples
C:\downloads\Arduino\arduino-1.0.5-windows\arduino-1.0.5\libraries
C:\Users\[username]\Documents\Arduino
C:\Users\[username]\Documents\Arduino\libraries
|
Depending on which location is used, the associated code and examples will appear in
different locations in the IDE menu structure.
For example, everything in
C:\Users\[username]\Documents\Arduino
|
is accessed via
The Examples (programs) in the other 3 locations are available via
where
| Menu section
| Directory
|
|---|
| Top
| C:\downloads\Arduino\arduino-1.0.5-windows\arduino-1.0.5\examples
|
| Middle
| C:\Users\[username]\Documents\Arduino\libraries
|
| Bottom
| C:\downloads\Arduino\arduino-1.0.5-windows\arduino-1.0.5\libraries
|
What is a Library?
A library is a collection of header (.h) and optional program (.cpp) files
located in a single directory.
Before it can be used, the Arduino IDE must know about it
(it must be placed in one of 2 directories).
Libraries may (and frequently do) contain examples showing how to use them.
These will always be placed in an examples directory.
keywords.txt
Libraries should also contain a keywords.txt file which,
when present, tells the IDE how to color various strings.
The colors shown in the table are for my system and are different
from what various sources on the web claim.
(As you can see, KEYWORD1, KEYWORD2 and KEYWORD3 all have the same color
though it is obvious that the intent is for them to be different.)
| Type ID
| Purpose
| Color
|
|---|
| KEYWORD1
| Datatypes
| Brown | #cc6600,plain
|
| KEYWORD2
| Method and function names
| Brown | #cc6600,plain
|
| KEYWORD3
| setup, loop, Serial, and a few more
| Brown, bold | #cc6600,bold
|
| LITERAL1
| Constants
| Blue | #006699,plain
|
| LITERAL2
| Apparently, not used
| Blue | #006699,plain
|
The keyword and the identifier must be separated with one tab - no spaces.
On my system, the main Arduino keywords are defined in
C:\downloads\Arduino\arduino-1.0.5-windows\arduino-1.0.5\lib\keywords.txt
|
All the IDE editor colors (including keywords) are defined in
C:\downloads\Arduino\arduino-1.0.5-windows\arduino-1.0.5\lib\theme\theme.txt
|
The Arduino IDE I am using (1.0.5) does not provide a method (that I have found)
to edit these system colors.
However, you can presumably do it by hand.
(This is the Linux philosophy - GUI's suck, direct editing is always preferred.)
Looking at the libraries supplied with the IDE you will be sure to notice that
some keywords.txt files only include a part of the associated key terms.
This is most likely an oversight where the file was not updated when
the rest of the library changed.
Adding a Library to the System
Before you can add a library to your program,
it must be added to the system.
This is accomplished via one of these methods.
Unzip the library and copy the included directory to one of the 2 library directories
C:\downloads\Arduino\arduino-1.0.5-windows\arduino-1.0.5\libraries
C:\Users\[username]\Documents\Arduino\libraries
|
After this, the library can be used immediately.
However, the associated examples will not be visible in the menu
until after the IDE is restarted.
|
From the IDE menu, select
Sketch / Import Library... / Add Library...
|
and select either the zip file or the un-zipped directory.
This procedure places the library (copies the file to)
C:\Users\[username]\Documents\Arduino\libraries
|
With this method, the associated examples are immediately available
(no restart required - yet the main Arduino help page
still says that a restart is necessary).
|
Adding a Library to your program
Once a library is known to the system,
you can add it to your program using the IDE menu via
Sketch / Import Library...
|
which will add all the associated header (.h) files
with compiler directives similar to
At the bottom of the menu there may be a line,
everything above it is in the main Arduino directory,
everything below it is in your local directory.
Alternatively, you can just add the #include directives manually.
| Caution: |
| It does not matter if a sketch (program) includes all the header files in a library,
if one file is included, then
all the .cpp files in the library directory will be included when the program is linked.
This is a violation of standard practice and will cause problems
if multiple files contain methods or variables with the same names!
|
Writing your own
Based on the information provided above,
when you write your own libraries, be sure to include
| Code
| These are the .h and .cpp files
|
| keywords.txt
| This instructs the IDE how to color key words
|
| Examples
| One directory per example
|
| Description
| Explain why this library exists
|
| License.txt
| Where would we be without lawyers?
|
| Instructions
| Instructions on how to install it
|
Your name should be in every file - just because.
References
Author:
Robert Clemenzi