Importing Third-Party Libraries - Arduino Sketches: Tools and Techniques for Programming Wizardry - page 381

The Arduino IDE can recognize two different formats: either a compressed
Zip i le or a folder. You must either select a zipped archive or the folder you
want to import.
If the Arduino IDE can import the library, a message displays informing that
the import has completed and that the library is now accessible from the Add
Library menu. If the Arduino IDE cannot import the library, a message displays
in the information bar at the bottom of the application with a brief explanation
of the issue.

NOTE The Arduino IDE can import libraries with properly formatted names—it can
handle only ASCII characters such as letters and numbers, and a library cannot start
with a number. Also, dashes (“-”) are not supported, but underscores (“_”) are. Check
the library's name before you try to import it.

It is also possible to manually import a library. To do this, i rst start by down-
loading the library you want to import. It will normally be available in a com-
pressed format, so after downloading the compressed i le you must decompress
it. The result should be a folder with the name of the library you want to import.
Inside this folder, there should be one or more i les: the .cpp i le is the source
code, and the .h i le is the header i le. (It may also contain other i les.) You will
need to copy (or move) the folder that contains these two i les.
To manually import a library, you must i rst quit the Arduino IDE if it is run-
ning. Next, locate the Arduino library folder. On Windows machines, it is most
likely placed in your Documents or My Documents folder, inside a subfolder
called Arduino. On Macintosh, it will be in your Documents folder, again in
a subfolder called Arduino. Inside the Arduino folder will be another folder
called “libraries.” This folder may or may not contain subfolders, depending
on if you have already imported other libraries or not. Copy and paste your
decompressed archive into this folder, and the next time you start the Arduino
IDE your library will be visible under the Sketch ➪ Import Library menu item.

Using an External Library

Now that you have imported your library, it is time to use it. But where do you
start? You can import your library just like you would import any standard
Arduino library. New libraries appear at the bottom of the Import Library menu,
as shown in Figure 24-3.
This imports the library, but that is all it does. So how exactly do you get your
hardware to work? Most libraries come with at least one example application,