How to Use and Understand the Arduino Reference

So you just opened up your fancy new gadget - maybe an awesome DSLR camera, or the newest gaming system, or maybe a new Blu-ray player. As you gladly tear away the packaging - you notice a small book that feels like it was printed on 4th generation recycled newspaper - it's the instruction manual.

As you skim the pages you realize it was first written in Japanese, translated to Chinese by an Australian ventriloquist and then an intern in California used Google Translate to finish the job for your native tongue.

So you toss the instruction manual and just plug the gadget in. Good for you - especially since it appears as everything is working just fine.

Until..

...something isn't working just fine. Maybe you can't navigate the menu options to find a setting that was advertised on the box, or maybe the functionality you thought your gadget has does not appear to be working no matter how correctly it seems you are pressing the buttons.

This tutorial is going to focus on the Arduino instruction manual, known more commonly as the "Arduino Reference" or the "Arduino Documentation". It is an important and useful aspect of learning to use Arduino - it will be your best friend in times of bewilderment, brain lapses and fits of rage.

I know that instruction manuals get a bad wrap - but don't fret - the Arduino Reference is awesome!

To be honest what really keeps us away from the documentation is our fears.

That's right - the reference pages can be a bit intimidating when you are just starting out.

They use a lot of technical jargon, are loaded with funky acronyms and filled with rabbit holes. Nobody uses the stuff anyway...right? ( Not right - that was a joke! )

This Tutorial Will Cover:

1. What is the Arduino Reference?
2. The Anatomy of an Arduino Reference Page.
3. Why You Should Be Using the Arduino Reference More.
4. How to use brain waves to trick your cat into eating less.

Have you ever read a book and come upon a word you didn't understand? Sometimes you can infer the meaning from it's context, but what about when no such context exists?

Likely, you used a search engine to find the definition. The definition told you what the word meant, whether is was a verb or adjective (or both), it gave some examples of how to use the word, and maybe even the etymology.

The Arduino Reference is the same thing. It is the "dictionary" for all the structures, variables and functions that you can use when programming a sketch.

It tells you the description, the parameters it uses, the syntax (how it is written), and even gives a bunch of examples on how to use it.

So let's jump into an Arduino Reference page and dig into what we can learn.

The Anatomy of an Arduino Reference Page

So let's navigate to a reference page to start our journey. You can find the index of all the Arduino Reference pages on the Arduino Website:

http://arduino.cc/en/Reference/HomePage

Or - if you are offline - don't worry, your Arduino IDE comes with an html copy of all the pages. You can get to it through the Arduino IDE: Help > Reference

You will note at the top of the Reference Index page, there are three columns; Structure, Variables, Functions. This is the first level of organization in the reference. So if you are looking for a variable, you know which column to start looking in.

Each of the hyperlinked items on this index page will take you to the individual entries reference page.

What's great about the individual reference pages is that they are organized in a similiar manner from one to the next, so you should know what to expect. They are also terse, so don't think you are going to have to scour through someones dissertation.

Each page has some major headings. We will walk through each of the main ones, and then talk about some less common ones.

Description:

All entries will have a description. Pretty straightforward - this is going to be a simple explanation of what the item does. It usually uses language that is basic.

Syntax:

Most all entries have a "syntax" heading, but they are more prevalent for functions. The syntax shows how the function (or other code) should be written when you use it in your sketch.

Basically - it is what the function needs to know to do it's job. Let's take an example from the digitalWrite() reference page.

The words in the parentheses are telling you what type of value should be passed to the function. If we want to use this function than it will need to know 2 things - the pin number and the value to write to the pin.

You don't type in the word "pin" when you use the function, you would replace that with the actual pin number, or a variable that represents that pin number. Same is true for the word "value", you would replace this with one of the acceptable parameters (see below).

So when you actually wrote the function, it might look like this:

digitalWrite( 13 , HIGH )

Where 13 is the "pin" and HIGH is the "value".

Parameters:

Only structures and functions will have the "Parameters" heading. These describe exactly what can go in the parentheses in the syntax above. This is good to know, because you might be trying to pass a floating point number when the function calls for an integer.

Returns:

This tells you what value to expect a function to give you back. For example, when you use the square root function, you expect to get back the square root. But what data type will the square root be - an integer, a float or a double? The "Return" heading will tell you.

Sometimes, a function will return nothing. Take the pinMode() function for example, you give it the pin number and the mode that you want the pin to be and it simply sets the mode - there is no data it needs to give you back.

Example:

This is your best bet at understanding how the structure, function or variable is intended to be implemented in code. It is usually a very short code snippet, though sometimes they can be lengthy. The example below is taken from the map() reference page.

A nice feature of the example description is the "get code" option on the right of the reference page next to the example code. When you click this, it will take your browser to a plain text web page where you can copy and then paste the code into your Arduino IDE.

See Also:

This is a bulleted list of similar or related entries to the reference page you are looking at.

They will link to other reference pages inside the reference directory. If I end on a reference page that isn't quite what I was looking for, I will usually check out the options they provide here.

Sometimes, they will also link to tutorials on the Arduino website (and who doesn't like tutorials?) Keep in mind if you are using the reference in the offline mode through the Arduino IDE and you do not have an internet connection that any links outside the reference directory will not work.

That includes the most common headings, what follow are some less common, but none-the-less useful headings you will run into.

Programming Tips / Coding Tip / Tip:

These are going to little bits of knowledge provided by people who know their stuff. I always like to read these, because they add to the depth of my understanding.

Warning:

These point out common errors that occur when people like me and you try to use the code.

Caveat:

If there is an exception to the rule, they will be described here.

Note:

In many cases, the notes are the "miscellaneous" heading, capturing information that doesn't particularly fall under other headings.

Why You Should Be Using the Arduino Reference More

Here is a scenario I have played out myself about 7,000 times. I am writing a program and some function does not seem to be working right. I spend 30 minutes making changes to the program, but keep getting errors. Every time I think I have it fixed, I find I am wrong.

Then I decide to check out the reference at which point I quickly realize I simply didn't understand how a function was supposed to work.

So the habit I have developed when I don't completely understand a function it to check out the associated Arduino Reference page.

It saves me times, teaches me something I didn't know or re-teaches me something I forgot - and it will do the same for you.

Let's sum all this up.

The Arduino Reference page is:

• The Bee's Knee's.
• The Lions Mouth.
• My favorite page on the Arduino website.
• Your favorite page on the Arduino website?

Challenge(s):

1. Go the Arduino Reference Index Page and start perusing some functions.
2. See if you can find entries with the following headings: Caveat / Warning / Tip

Further Reading:

Warning - this gets deep!

- AVR Libc (This is the reference for what the Arduino language is based on)

- User Manual for the AVR Libc

P.S.

Ok - as much as I love the Arduino Reference page, sometimes it has errors. So if you find any, mention it on the Arduino Forum.