SparkFun Support and Front Desk will be closed on Thursday 11/14 from 1-2:30pm for a company event. Please plan to pick up your orders before or after this timeframe.
openFrameworks is a very handy software library written in C++ that is written for the sole purpose of reducing the software development overhead faced by designers and artists that would like to create pieces that use various media (graphics, sound, video, electronics, etc.). On the surface, openFrameworks (we'll refer to it as oF from now on) seems very similar to Processing. So why use oF when Processing is seemingly simpler and just as powerful? Well, because there are some things that oF is well suited for that Processing just can't handle. oF is much better at creating projects that use a lot of 3D Graphics, computer vision libraries like OpenCV or projects that involve the real-time manipulation of video. Also, while Processing requires a Java backend, oF is simply a set of C++ libraries, meaning that developers comfortable with C++ will be right at home.
For some great examples of projects that use Arduino and the oF libraries, be sure to check out the openFrameworks section of the Arduino Blog.
This tutorial will go step-by-step through the process of installing openFrameworks, getting programs running with it and then using the oF software libraries to communicate over USB with an Arduino UNO.
This tutorial assumes that:
Installing openFrameworks is relatively simple, but there are some extra steps one must take to get the libraries running properly with a compiler. For this tutorial, we're going to be using Windows, but the steps are similar for Mac and Linux. For a full rundown of setting up with non-Windows operating systems, be sure to read the oF setup guide, and skip to Step 2 of this tutorial.
To use the oF libraries, we're going to need a development environment. For Windows, the recommended environment is called Code::Blocks, because it's a lightweight environment well suited for development with oF.
First, download the latest version of Code::Blocks. For this tutorial, we'll be using version 10.05. The compiler we need to use is called MinGW, and comes packaged with the download of the C::B IDE, so be sure to download the binary file that includes MinGW.
Now install Code::Blocks
Click next, and agree to the license (or don't, I'm not your boss)
You don't need to change anything here, just click Next
Pick your install directory, then click Install
When the installation is finished, you don't need to start Code::Blocks just yet, we've got to add some extra bits to the MinGW compiler files in order to compile oF programs properly. The next step is to download the latest version of the oF additions from the oF site. Download the zip file from the link below:
Unzip the file and open it. You should see this
The two folders in this file contain all the additions to the ...\MinGW\include\ and ...\MinGW\lib\ folders necessary for compiling programs using the oF libraries. To properly install these we need to put them in their respective folders in the ...\MinGW library. For example, take the contents of (not the folder itself!)
and copy/paste them into C:\Program Files\CodeBlocks\MinGW\include\
then do the exact same thing with the library files. Take the contents of
and copy/paste them into C:\Program Files\CodeBlocks\MinGW\lib\
With that done, we have all the configuration necessary to use the openFrameworks libraries, so it's time to download them. The most recent version of the libraries can be found here
For this tutorial, we'll be using v0.07.
Unzip the downloaded file and move the folder to wherever you want to work. Open the folder, and you should be looking at this
These are essentially the oF libraries. The folder we're interested in right now is "apps". Inside this folder are the examples that we will use to begin developing with oF and eventually oF with Arduino.
With the IDE and libraries installed, now it's time to have a bit of fun. Start Code::Blocks. It may ask you to confirm the compiler auto-detector. If so, just click okay. You should now be looking at an empty workspace in Code::Blocks.
Let's load up an example program from the oF examples folder.
Navigate to the openFrameworks folder that you downloaded in the previous step.
Navigate to apps->Examples
This folder contains several example programs written using the oF libraries to demonstrate the capabilities of oF. For starters, let's open the "advanced3dExample," and open the file advanced3dExample.workspace.
Note: when opening an example, be sure to open the workspace and not the Code::Blocks project (.cbp) file. This will ensure that the oF core libraries (openFrameworksLib) is loaded up along with the example project.
Now we're looking at an open workspace with a file navigator on the left. If we expand some of the folders in the navigator, we can get a loose idea of the file structure of an oF project.
Double click on the file "main.cpp".
Like any C++ program, this is where the program starts executing. However, this file is identical in most oF programs. It simply initializes a window and then run the application that uses the window, in the example cases, this code starts in "testApp.cpp," hence the final line
ofRunApp( new testApp());
Go ahead and open testApp.cpp.
This file contains the real bulk of the program. It has several functions, but there are three functions of note:
Now that we know a bit about the main bits of the program, let's run it and see what it actually does. Click Build->Build and run, or just hit F9. The program will compile and then open a new window that looks like this:
That's just a small example of the capability of the openFrameworks library. You don't need to understand exactly how this particular program works, just understand the basic structure of an oF program and how to run it.
Now we'll move on to the serial example that we'll be using to connect to the Arduino. In the Examples folder open the serialExample workspace. This example is a simple program that attempts to send a character to a device over a COM port, and then receives three characters. Open the file testApp.cpp, and let's have a look at what's going on.
In the setup() function of this program, you can see that we have an object called serial that sets up the parameters of our serial connection the line
sets up the device at 9600 baud. Also have a look at the line
You may not understand all the syntax of this line, but all you need to know now is that it is used to list all the serial devices in the CMD window when the program initializes. It allows us to know what first parameter to use in the serial.setup line. In this case, the parameter is 1, or the first serial device.
Now have a look at the update() function. This function has a line that sends the character 'a' to the serial device as a handshake:
and a while loop that attempts to read three bytes from the device:
while( (nRead = serial.readBytes( bytesReturned, 3)) > 0)
for now, that's all we need to know to program our Arduino. We need to write an Arduino program that simply waits for a character, and then responds with three characters. Open up the Arduino IDE and copy/paste this program into the IDE.
Verify and program this to your Arduino, taking note of which COM port the Arduino is connected to.
Now it's time to get the Arduino talking to the oF program. Open Code::Blocks and then open the serialExample workspace. Hit F9 to build and run or hit the Build and Run button on the toolbar.
oF will first launch a command prompt, which displays feedback not meant for the main program window. It then launches the main window. To test this program, just click in the main program window, which displays "click to test serial."
Does it work? Great! Mine does not. Why? Because of the line
serial.setup(1, 9600); //open the first device
in serialExample. In my case, I have more than one device, so when serialExample opens the first device, it opens another FTDI connected to my computer, which obviously does not respond properly. To fix this, we need to look at the Command Prompt that oF launches before it opens the main window.
Remember the line
vector deviceList = serial.getDeviceList();
This line is what prints out the serial port list in the command prompt. In this case we see the two devices
 = COM7
 = COM8
I know from programming my Arduino that it is connected to COM8, meaning that to openFrameworks, it has a device value of  in this list, so we need to change the serial setup line to
serial.setup(2, 9600); //open the second device
This tells oF to open device 2 (COM8) for use instead of device 1 (COM7). Make the same change for whichever COM port your Arduino happens to be connected to.
After making this change and hitting Build and Run again, the Arduino should be properly communicating with the program. In the main window, I click a couple times and see this
Success! The oF program has received the three '$' characters that the Arduino sent!
Now we know the basics of communicating between Arduino and an oF program. From this point we can use the lines found in the serialExample to control other programs and more advanced graphics with an Arduino, or vice versa. Read through testApp.cpp and testApp.h in the serialExample program and make sure you have an idea of how the two files work together. If you need more info, be sure to read through the oF Wiki. I personally recommend this book. It is a very thorough resource for getting started with openFrameworks, Processing, Arduino, and communicating among the three.
With what we've done in this tutorial, you should have everything you need to start to control Arduinos with oF programs and vice versa. Good luck!