Getting Started

1. Setting Up Spacebrew

First things first - you need to launch Spacebrew. This requires a server to host the Spacebrew session. Don't worry if you don't have one setup, you can use a public Spacebrew server for now. 

 

LOCAL + REMOTE HOSTING
This method requires a bit more setup, but once installed, Spacebrew will launch a private session that can be hosted locally or remotely. This option is a good choice for long-term projects, client work, and those who want full control over their setup. 
// Download Spacebrew from GitHub

PUBLIC SPACEBREW SESSION
If you don't want to setup your own server, you can use our public Spacebrew session hosted on Amazon EC2. We host this session to facilitate prototyping, but be warned that there is just one public session for the whole world that anyone can access. You will see any publishers, subscribers, and routes that other users have established. You will have the ability to route new connections and re-route existing ones. Users will be able to route to and from your publishers and subscribers. Play nice!
// Spacebrew Cloud

Please note: If no other users are connected, the admin site will appear blank. 

Active Spacebrew session with no connected clients.

Screenshot of Spacebrew in action.

2. Connecting Clients to Spacebrew

Spacebrew uses WebSockets as the communication protocol for talk between clients and the server. Any client that can speak WebSockets can communicate with Spacebrew. We've run successful tests with node.js, C++ (using libwebsockets), Processing, Java, Python, and client-side javascript. The public Spacebrew server is currently written in node.js and uses the WS WebSocket module for communication. If you successfully connect with anything else, drop us a line - we'd love to hear about it. If you'd like more details on connecting something new, we will be publishing documentation on the message protocol soon.

Communication begins when clients are connected to the server via a websocket connection. Once connected, clients will be ignored unless they register themselves as applications or admins. 

APPLICATION
If creating an application, you only need to communicate your 'config' information to Spacebrew to let it know you would like to connect. If the config is recognized, your application will appear as a row in the web admin tool for the server.

​Active Spacebrew session with two connected clients. JE's Button can send a boolean and receive a range and/or string. JE's Range Slider can send a range and receive a range.

PUBLISHERS + SUBSCRIBERS
In Spacebrew, information sent from connected clients is called a Publisher. Information that can be received and interpreted by a client is called a Subscriber. Each client can have multiple publishers and subscribers.  

At the moment there are only three types of values that can be sent via Spacebrew: 

  • booleans (true / false) 
  • ranges (normalized to a range of 0-1023)
  • strings (text)

In a pinch, strings can be hacked to send all kinds of things if you are so inclined. We encourage you to think about building your application out of these simple building blocks in order to maximize their ability to be routed and re-routed in the space. Each of these must be registered as either a publisher or subscriber of data. 

When a client successfully establishes a connection with Spacebrew it will appear in the Clients column. Any booleans, ranges, or strings the client is capable of sending will appear as nodes in the Publishers column. Any information the client is configured to interpret will appear as nodes in the Subscribers column.

3. Making Things Talk

​Hover over modules to see what they can be connected to.

Once you have successfully connected two or more clients to Spacebrew, you can begin linking clients together so they can talk to each other.

Hover over publishers and subscribers to see what other modules they can connect to. Remember, values can only be linked to like values, i.e., a boolean can only link to another boolean, range to range, string to string. Publishers can only be linked to subscribers, and subscribers to publishers - you can not link a publisher to another publisher or a subscriber to another subscriber.

 

Click on a module to select it, and click on a like-valued module across the dotted line to establish a connection.

Click on a module to select it, and click on a like-valued module across the dashed line to establish a connection. 

 

When a connection has been made, a black line will visually pair the connected modules together.

When a connection has been made, a black line will visually pair the connected modules together - now the publisher can speak to the subscriber! Make as many connections as you like - a single publisher can be connected to several subscribers, and a single subscriber can be connected to several publishers.

 

​To break a connection, click its publisher or subscriber and an X will appear next to each module it's connected to. Click the X next to the module you wish to disconnect from.

Spacebrew makes it easy to reroute connections. To break a connection, click on its publisher or subscriber - an X will appear next to the modules it's connected to. Click the X next to the module you wish to disconnect from.

 

Examples

If you’re just getting started, it may be helpful to download and play with the following examples. They are set up and ready to connect to Spacebrew upon launch - no coding required.

Download Processing Library
A ZIP file that contains the base scripts to communicate with Spacebrew.

Download Processing Examples 
A ZIP file that contains the following scripts:

  1. Base.pde
    This script launches and connect to the online, public version of Spacebrew. It has all the code you will need to setup publishers and subscribers commented out and ready for a new project.

  2. Button.pde
    Launches and connects a virtual button to Spacebrew.
    Publishes boolean.
    Subscribes to range to control background color.
    Subscribes to string to control button text.

  3. Arduino_Button.pde
    Connects a physical button to Spacebrew using Arduino. 
    Publishes boolean. 

  4. Powertail_Arduino.pde
    Connects a Powertail to Spacebrew using Arduino. 
    Subscribes to boolean. 

  5. Range_Slider.pde
    Launches and connects a virtual range slider to Spacebrew. 
    Publishes range. 
    Subscribes to range to control slider position.

Javascript Examples
A ZIP file that contains the following scripts:

  1. Button
    This script creates and connects a virtual button to Spacebrew.
    It publishes a boolean value when button is pressed, and subscribes to a boolean value, that changes the background color when set to true.

  2. Slider
    This script creates and connects three virtual sliders (or linear pots) to Spacebrew.
    It publishes and subscribes to three range messages. The sliders function as outputs and inputs.

  3. String
    This script creates and connects a text box that sends strings to Spacebrew. 
    It publishes and sends strings to Spacebrew.

​

Example Processing button.​

Example Processing button.​

Example Processing code.

Example Processing code.

Example javascript slider.

Example javascript slider.