Creating Your Own Library - Arduino Sketches: Tools and Techniques for Programming Wizardry - page 415

Adding Examples
Now that you have read through this example and added functions to turn on
the different lights, it is time to move on. Before distributing your library, your
users need to know how the library works. You can spend time writing docu-
mentation, but the easiest way to show people how a library works is to create
an example program. From there, they can upload the example to an Arduino,
modify the code to see how it works, and then copy/paste parts of the example
into their own projects.
An example program is simply a sketch that uses your library. Again, make
sure to comment your code to make it readable, and explain what is being done.
Don't use a variable that hasn't been explained.
To add an example, i rst, write a sketch that uses the library. Next, go to
the folder that you are creating for your library. Inside this folder, create a
folder, “examples”. This is where the examples will be placed. Inside that folder,
create another folder, the name of the example you want to create. Some libraries
might require several examples. (Remember, the Ethernet library in Chapter 9
has multiple examples for servers and clients.) Now, paste your sketch inside
this folder, keeping the same name as the folder but with the extension .ino (for
Arduino sketch). Alternately, you can use the Arduino IDE to create the i les
and save them to disk directly. When the folder is imported, the Arduino IDE
automatically adds any examples it i nds into the Examples menu. For example,
Figure 26-3 shows my Trafi cLight library folder with two example sketches.
Figure 26-3: Traffic lights folder layout
Read Me
Most projects contain a README i le—a text i le that contains information about
i les in a folder. Historically, they were used to describe the contents of a folder,
and were sometimes called README.1ST to inform the user that the contents
should be read i rst. The README i le should contain information about the
project, the functionality that the library adds, what the user needs to make it