The Arduino is a very useful system because there is a strong community of users with expertise in a variety of fields. Sometimes we want to use our Arduino system to interface with a complex piece of electronics like a wi-fi module, or a GPS receiver. For most of us, to code the protocols required to communicate with these devices would be far too complex, but there are people out there who have worked out how to do it, and they usually share this information in the form of a "library" which we can then use to interact with this advanced hardware in a simplified way. They do this by providing custom procedures and functions which we can call upon to do the complicated communication for us.
If you ever find yourself wanting to use a sensor or a "shield" (a specially designed board for a specific application which plugs onto a standard Arduino board) which you do not understand, searching for a library can be a really good place to start. They also usually come with examples. Aside from a google search for "Arduino library X" where X is the device you are trying to use, the Libraries page of the Arduino website and the sparkfun website are some pretty good places to start looking.
The first library we are going to look at is one created by me to help you get to grips with one of the other components on the Tutorial Board. This is the RGB LED. This LED is a little bit complicated, and uses a "common anode" configuration which means that controlling it might not be immediately intuitive. I have therefore made a library with a couple of examples, that allows us to use this device more easily.
You can find the library at the bottom of this page if you want to download it yourself.
From the Arduino IDE, choose File>>Examples>>RGB>>ColourScroller, and then re-save it as Ex_RGBLED.
You will see at the top of the program the command #include <RGB.h>. This tells the program that we want to use the library RGB, and that it should include all of its custom routines for us to call upon.
Next you can see that there is an "array" of "enum"s, which are essentially numbers given special names, where UNDEF would be 0, RED would be 1, etc.
An "array" is a really important structure in programming that we won't have time to look at in any great detail in this course, but it is essentially a group of several instances of the same data type, all referenced by the same group name, and individually referenced by number within that group. If you go on to do more advanced programming, you will explore this concept further. You will also see a practical example of using arrays next week when we look at sounds.
Next comes a declaration of a new entity. It is of "type" RGB (which is custom defined by the library) and I am calling it "rgb". This may seem confusing at first, but try to think of it like our variable declarations. We could declare "int myVariable", where int is the data "type", and "myVariable" is one particular instance of it. I could have many instances of int in one program, and similarly I could have many different instances of the RGB type.
In the setup procedure I simply set the starting state for my RGB LED by using the colour() procedure, which you will note takes a parameter which is an unsigned integer.
N.B. The Arduino programming language makes use of the "dot notation" to indicate routines that belong to a specific data type. Here colour() is a routine of the RGB data type, in this case our instance of it called "rgb" (told you it would get confusing!).
We have seen this before with the Serial.print() and Serial.println() commands, which are procedures of the Serial type.
In this case, all instances of the RGB data type can run a colour() routine, but we need to tell the Arduino that we want our particular instance of it called "rgb" to run the routine. Imagine if we had 3 RGB LEDs called rgb1, rgb2, and rgb3. We would need to be able to identify which one we wanted to change colour.
That probably doesn't make a lot of sense to you right now but don't worry, just download and run this program first to see what it does.
It should hopefully be clear that it is running through the colours listed in the enum list at the top of the program.
The enum list at the top of the program allows me to make use of sensible names to represent the numbers that the colour() procedure is expecting. Note the capital letters are important. this means I can tell the RGB LED to display a particular colour by name.
Empty the code in loop() and change the word in the rgb.colour() call in setup() from UNDEF to another colour of your choice from the enum list (e.g.RED), then download it and see what happens.
Save the program as Ex_NamedColour.
This use of libraries to hide the complexity of the controlling of hardware from you as a programmer is very useful, but is limited to the functionality implemented by the person or company who wrote the library.
For example, if you tried rgb.colour(TURQUOISE), it would not work because I have not included a TURQUOISE option in my library.
Good libraries contain the majority of functions you would want to use for a given piece of hardware, but obviously I need to know what routines are available to me, what parameters they require, etc.
To find this information, I can do one of two things:
Look at the examples which are almost always included with a library, and should cover the key things you might want to do using that library.
Look for some online documentation. The Arduino standard libraries are all described on the Libraries page of the Arduino website, and a list of all the routines available is given, alongside a description of what the routines do, and what parameters they require, etc. Also, examples are usually provided including each routine so you can see exactly how it is used. This is a really valuable resource, especially when you start using "shields" to extend the functionality of your projects.
The RGB library has another procedure called rgbcolour() which takes three parameters, all of them integers. This function allows you to specify the actual RGB value of the colour you want to display. This is a standard way of representing colours in computer programming, and also on the web. You can find a list of the RGB numbers for various colours on websites like this.
Let's look at the example, so load up File>>Examples>>RGB>>RGBColourSelector, and re-save it as Ex_RGBColours.
This program makes use of the Serial Monitor connection to receive information from the PC, and interpret it for use in the program.
Download it, then open the Serial Monitor, and in the text box type an RGB value separated by commas (e.g. 255,0,0) being red.
Try out some different RGB values chosen from the website listed above, and see if the RGB LED gives a good representation of them.
We now have two ways of controlling the colour of an RGB LED in our programs.
You might have noticed that there is an LCD display attached to the tutorial board. This is a special module produced by Revolution Education (available here), the company that make PICAXE, and it can be controlled via a single wire using a special serial protocol.
This protocol is not that trivial, so someone has created a library so that you can easily send text to this screen. The library is called AXE133Y which is the product code of the OLED version of this display.
You can find the library at the bottom of this page, and the documentation for it on the Arduino playground here.
Once again, there is an example (although only one), so go ahead and load up File>>Examples>>AXE133Y>>AXE133Y and re-save it as Ex_HelloWorldLCD.
We are going to tweak it slightly so that it references an LCD not an OLED, so go ahead and change every instance of OLED or oled to lcd.
We also need to change the #define statement so it references pin 12 not pin 5, so do that now.
This example only shows us two commands, clearScreen() and splash(). The first of these is obvious, and the second should become clear if you download the program.
Generally the splash() procedure is not going to be that useful to us, so let's take some guidance from the documentation and experiment with the most useful procedures - print() andcursorposition().
print() works in exactly the same way as the Serial.print() command we have already encountered, and it sends a series of ASCII characters to the LCD display to be shown on the screen. The display has 16 characters on each line, but has some extra space on each line for characters which do not get displayed.
When we clear the screen, the cursor moves to the first position of the top line, so if we simply printed a message, it would appear here.
Try this out by replacing the splash() command with:
lcd.print(" Hello World! ");
Notice I have made the message exactly 16 characters long, padding with spaces so it will be centered on the display.
If you download this you should see the message appear on the first line.
Unfortunately there is no println() function on this display, so we need to manually move the cursor to the start of the second line if we want to use that line. This is done with the cursorPosition() procedure.
Add the following to your code and run it to see how this works:
lcd.cursorPosition(2,0);
lcd.print(" Hello World! ");
Now we can write to both lines of the display. Don't forget to save.