Basics: Spacebrew + openFrameworks

Connecting to Spacebrew with openFrameworks

This tutorial will show you how to create a simple input/output application for Spacebrew in openFrameworks. It’s targeted towards the (as of now) latest version of OF, 0.8.4, and towards Mac OS X users (though it also works on Windows and Raspberry Pi).

---

Setup

1. if you haven’t already, download openFrameworks and follow the guide for getting set up on your platform
   http://www.openframeworks.cc/download/
   
2. Checkout, fork or download the ofxSpacebrew repository and place it in your  toF/addons folder:
   checkout/fork: https://github.com/spacebrew/ofxSpacebrew
   download: https://github.com/spacebrew/ofxSpacebrew/archive/master.zip
   
3. Spacebrew is built on WebSockets, which oF and C++ don’t support out of the box. So, you must also checkout, fork, or download our oF wrapper of libwebsockets, a C WebSocket library and place into your oF/addons folder:
   checkout/fork: https://github.com/labatrockwell/ofxLibwebsockets
   download: https://github.com/labatrockwell/ofxLibwebsockets/archive/master.zip
   
4. If you downloaded the folders, they might have funky names. Rename them to ofxSpacebrew and ofxLibwebsockets (respectively). Your OF install should look a little something like this now:
   

---

Button Example: Getting started

1. open the Xcode project inside ofxSpacebrew/example_button

2. Make sure the correct target is selected (“example_button Debug” or “example_button Release”)

3. compile and run the project (⌘ + R or the big Play button in the top left corner of Xcode)

4. You should see a window open up with a lovely giant grey button that says “Press Me”

5. Open the Spacebrew Cloud Admin http://spacebrew.github.com/spacebrew/admin/admin.html?server=sandbox.spacebrew.cc

6. You should see your application show up as "of-button-example" (note: if a bunch of people are using the admin, you may have to scroll down to find yourself)

8. Route “button” and “backgroundOn” to each other

9. Now, when you click on the button, you should see the background change like this:

Amazing! Now let’s dive into the code

---

Button example: Code breakdown

• If you look under the “addons” folder in Xcode, you’ll see both ofxLibwebsockets and ofxSpacebrew. We’ll talk more about this in the next section, but all Spacebrew apps you make should have at least these two addons
• Open up ofApp.h. Here’s where we import ofxSpacebrew, create a connection object, and listen to Spacebrew messages
   
• Import: 
  including Spacebrew is extremely simple; it all happens on line 5:

#import "ofxSpacebrew.h"

• ofxSpacebrew takes care of importing ofxLibwebsockets
  
  
• Connection: 
  The line Spacebrew::Connection spacebrew;
  declares a variable called “spacebrew” of type Spacebrew::Connection
• Spacebrew:: is a namespace, which is a way of grouping code in C++
• ofxSpacebrew includes a number of classes and constants under the Spacebrew:: namespace
• Note: some people may want to use this line above their testApp to not have to type Spacebrew:: all the time; we’ve left it out for clarity’s sake:

using namespace Spacebrew;

• Listen: 
  ofxSpacebrew broadcasts an ofEvent when it receives a message (see oF/examples/events for more on this concept). The ofEvent passes a reference to a Spacebrew::Message object. We’ll want to catch that event in a custom function like this:

void onMessage( Spacebrew::Message & m );

• The rest of the code in testApp is related to drawing our on-screen button
  
  
• Let’s open up testApp.cpp. Here’s where we make all the stuff we declared in testApp.h actually work. We’ll need to connect to Spacebrew, tell Spacebrew what we’re publishing + subscribing to, send Spacebrew messages, and react to incoming messages. We’ll also have to make a button!
  
  
• Connect:
  Connecting and setting up publishers/subscribers should happen in your OF setup function. In there, you’ll see we’re connecting to Spacebrew with a specific host, name, and description 

string host = Spacebrew::SPACEBREW_CLOUD;
string name = "of-button-example";
string description = "It's amazing";
spacebrew.connect( host, name, description );

• you’ll see I’m using a special constant declared in ofxSpacbrew: Spacebrew::SPACEBREW_CLOUD. This is the same as typing “sandbox.spacebrew.cc”. If you wanted to switch this to a local installation, you might declare your host like this instead:

string host = “localhost”;

• PubSub:
  Tell Spacebrew what you’re talking about + listening to:

spacebrew.addPublish("button", Spacebrew::TYPE_BOOLEAN);
spacebrew.addSubscribe("backgroundOn", Spacebrew::TYPE_BOOLEAN);

• addPublish and addSubscribe both take the arguments “name” and “type” (both strings). You’ll see another helper here: Spacebrew::TYPE_BOOLEAN, which is the same as just typing “boolean”. There’s also Spacebrew::TYPE_RANGE and Spacebrew::TYPE_STRING. 
  
  
• Send:
  Since we’re making an on-screen button, we just want to react to mouse presses in the window. So, we’ll add code in OF’s built in mousePressed and mouseReleased functions. 
  

if ( checkInsideCircle( … ) ){
    bButtonPressed = true;
    spacebrew.sendBoolean("button", true);
}

• Using the checkInsideCircle function (you can probably guess what that does!), we see when someone clicks the button and send a boolean message to Spacebrew when they do. The send functions (sendBoolean, sendRange, sendString) take the same args: “name” and “value” (value is a different type for each function, bool, int, string respectively). We do the same thing when a user releases their mouse, sending “false” to spacebrew if the button is down:

if (bButtonPressed){
    spacebrew.sendBoolean("button", true);
}

bButtonPressed = false;

• React (aka Listen part II):
  Scroll down to our buddy onMessage. Here’s where you can actually receive and react to your Spacebrew::Message objects. Most of the time, what you want to do is look at the Spacebrew::Message’s name and value, which is what we’re doing in this app:
  

if ( m.name == "backgroundOn" ){
    bBackgroundOn = m.valueBoolean();
}

• You’ll see we’re looking for “backgroundOn” (which we said in setup that we’re listening to). If we get that message, we set a boolean variable equal to the value of the incoming message. If you look at the Spacebrew::Message class in ofxSpacebrew.h, you’ll see a few more helpers like valueBoolean. You can always grab the raw value by just looking at m.value.
  
• Looking up to “draw”, you’ll see we’re changing the background color based on the bBackgroundOn variable! Hurray!
  

Pro tip: Spacebrew::Message overrides the << operator. So, if you want to log an incoming message, you can do it like this (assuming you have a incoming Spacebrew::Message  ‘m’: 
ofLog()<<m; or cout<<m;

---

Starting a new project:

Starting a new project with ofxSpacebrew is fairly simple: just use the openFrameworks project generator! Make sure to select both ofxSpacebrew and ofxLibwebsockets in "addons".

From there, just follow these steps just like we did above:

• include ofxSpacebrew.h
• create a Spacebrew::Connection
• add functions to listen to spacebrew events (copying from one of the examples is easiest!)
• connect to a server
• add publishers and subscribers
• listen to the events you created
• send and receive stuff!