» Getting StartedBreakout

Getting Started

To get started, you’ll need to download the Breakout software, make sure you have the Arduino application installed and a compatible I/O board along with a button, LED, a couple of resistors and a .


View system and browser requirements

Download and Install Breakout

  1. Download and unzip the latest Breakout package or clone the repository
  2. See the Installation section of the Using Breakout Server guide.

Upload StandardFirmata to your I/O board

This section assumes you are familiar with the Arduino application and the process of uploading new programs (‘sketches’) to the I/O board. If you are new to Arduino, please first see the Getting Started section for your platform (Mac, Windows or Linux) on the  website.

  1. Open the application (Breakout requires Arduino 1.0 or higher).
  2. From the Arduino menu, open File -> Examples -> Firmata -> StandardFirmata
  3. Compile and upload StandardFirmata to your I/O board (make sure your particular I/O board is selected under Tools -> Board)

StandardFirmata is a program that allows a client application running on a computer to communicate with the I/O board, and is just one application of the Firmata protocol. See for a complete overview.

Wire a button and LED to your I/O board

Open Breakout/examples/schematics.pdf  and wire up your components according to wiring diagram on page 2. If you have no idea what the diagram means, read through the lessons in this .

Run Breakout Server

Assuming you performed the steps in the Download and Install Breakout section above, you can now double-click on the Breakout Server application for your platform to launch it (Linux users need to launch the jar file from the command line unless you set up a customer launcher).

When you launch the server you should see the following:

status panel












  1. Select the serial port your I/O board is connected to (if it is not already displayed in the drop down).
  2. If you have a firewall enabled for your computer or network, make sure port 8887 is open, or enter a new port number  that is open (be sure to hit the enter key upon typing in a new port number).
  3. Click the Connect button.

You should now see this screen:













The name of your computer and the network port you are connected to should be printed along with the serial port your I/O board is connected to (on windows this will say something like “com3″).

If you encounter any issues, refer to the Troubleshooting section of the Using Breakout Server guide. If you are still unable to get Breakout Server or the following example to work, please post the issue in the Breakout Beta Issues forum.

Running the Hello World example

Assuming you were able to launch the server and connect without any issues, you should now be ready to open an example.

  1. Open Chrome, Firefox or Safari and enter the following url: http://localhost:8887/examples/getting_started/hello_world.html
  2. The Led should be fading in and out every second and the Led on the I/O board (if you’re using an Arduino board that looks like the one on screen) should turn on for 2 seconds then off for 2 seconds. If you press the button, the state should be displayed on the screen.
  3. If this is not working, double (or triple) check your wiring. You may have the Led backwards for example.

Note that if you changed the network port in the server you will also need to change the network port in the url above as well as in the hello_world.html file on line 39.

Running the Hello World example from the Web

You can also load files from external web servers (such as the one hosting this post). In this case Breakout Server is simply bridging the serial data from the I/O board with the websocket connection to the page you have loaded from an external server. Note that the example below will only work if you can connect to network port 8887 (because this is the port number set in the file you are loading).

  1. With Breakout Server connected, refresh this page. You should see the Leds blinking and if you press the button you should see the state (‘pressed’ or ‘released’) displayed below.

Let’s take a look at the hello_world code

The minified file Breakout.js is included on line 17. You’ll see jQuery is also included on line 18. Many of the examples use the jQuery library. jQuery is not a requirement of Breakout and is only included for the examples. You can use any javascript framework you like with Breakout.

Breakout uses the namespace BO. If you do not want to type the full namespace for each object, you can declare variables at the top of your file to refer to the objects from the Breakout library that you are using. Here are the objects used in the hello_world example:

var IOBoard = BO.IOBoard;
var IOBoardEvent = BO.IOBoardEvent;
var Button = BO.io.Button;
var ButtonEvent = BO.io.ButtonEvent;
var LED = BO.io.LED;
var Oscillator = BO.generators.Oscillator;

See the Breakout docs for details on all of the Breakout objects.

The next line sets whether or not debug messages should be printed to the console. This is only for debug messages sent by the various Breakout objects, you can still print anything you want using console.log(). The default value is false so the following line of code is only needed when you want to print debug messages. Note that if debugging is enabled and lots of data is printed to the console it will slow down (and can even freeze) your browser so in many cases it is best to set it to false or not include it in your application.

BO.enableDebugging = true;

Next an instance of the IOBoard object is created. The constructor parameters are the IP address (as a String), and the network port.

var ard = new IOBoard("localhost", 8887);

Note: If you set the IP address to the actual IP address of the host computer (such as “″) and if you connect a phone or a tablet to the same local network (via wifi) then you can load the page on the mobile device (if your mobile device browser supports websockets – Safari for iOS, Firefox for Android, Chrome Beta for Android).

When an IOBoard instance is created it must finish its initialization routine before you can send any commands. Listen for the READY event to be notified when it is safe to send data to the I/O board.

ard.addEventListener(IOBoardEvent.READY, onReady);

When the onReady method is called, the first thing you should always do is remove the event listener for the READY event:

ard.removeEventListener(IOBoardEvent.READY, onReady);

Next an instance of an LED object is created. Breakout provides a number of hardware abstractions such as LED, Button, Servo, etc. The LED constructor parameters are a reference to the IOBoard object, and a reference to the pin the LED is connected to. The getDigitalPin(pinNumber) and getAnalogPin(analogPinNumber) methods are used to get a reference to a Pin object. See the docs for BO.Pin for details.

onboardLED = new LED(ard, ard.getDigitalPin(13));

The blink method toggles the Led on and off at the duration specified by the first parameter. The 2nd parameter specifies the number of times the Led should blink. If the 2nd parameter is 0, then the Led will blink ‘forever’. In the example, the LED will turn on and off 100 times.

onboardLED.blink(2000, 100);

A second LED is created:

fadeLED = new LED(ard, ard.getDigitalPin(11));

This time an Oscillator is passed to the blink method. Oscillator.SIN uses a sine wave to fade the LED in and out at the rate specified by the first parameter of the blink method. By default Oscillator.SQUARE is used which is why when the 3rd parameter is not specified for onboardLED above, the LED simply blinks on and off. See BO.generators.Oscillator in the docs for the full list of available Oscillators.

fadeLED.blink(1000, 0, Oscillator.SIN);

Next an instance of the Button object is created. Note that if you are using a javascript UI library that also has an object named ‘Button’ then you will need to use the full namespace for the Breakout button to avoid any naming conflicts (BO.io.Button). The Button object takes 3 parameters: A reference to the IOBoard, a reference to the Pin the button is attached to, and the button mode. The default mode is Button.PULL_DOWN. Other modes are Button.PULL_UP and Button.INTERNAL_PULL_UP. Which one you use depends on how you have wired the physical button to your I/O board. If the other end of the resistor connected to the button is connected to ground, then the mode is PULL_DOWN, if the other end is connected to power, then the mode is PULL_UP and if a resistor is not used, the mode is INTERNAL_PULL_UP.

var button01 = new Button(ard, ard.getDigitalPin(2), Button.PULL_DOWN);

Listen PRESS and RELEASE button events to be notified when the button state changes.

button01.addEventListener(ButtonEvent.PRESS, onButtonPress);
button01.addEventListener(ButtonEvent.RELEASE, onButtonRelease);

The onButtonPress method is called whenever the physical button is pressed and the onButtonRelease method is called every time the button is released. The parameter passed to onButtonPress and onButtonRelease callback functions is a reference to the event object. Each event object has a target property which refers to the object that triggered the event. Therefore event.target gives us a reference to the button that was pressed (in the case they more than one button is connected to the I/O board, this is helpful). jQuery is used simply to print the button state to the browser window.

function onButtonPress(event) {
  // get a reference to the button object that fired the event
  var btn = event.target;
  $('#button').html("button: pin = " + btn.pinNumber + " pressed");

function onButtonRelease(event) {
  // get a reference to the button object that fired the event
  var btn = event.target;
  $('#button').html("button: pin = " + btn.pinNumber + " released");

Next Steps

  • Take a look at the examples in Breakout/examples/. The examples demonstrate how to use many of the hardware abstractions found in Breakout/src/io/ as well as using filters and generators. There are also examples for using Breakout with and which can be interesting if you have sensors like gyroscopes, magnetometers and accelerometers.
  • Check out the Using the Pin Object guide for a detailed explanation on how to use digital and analog input and output in Breakout.
  • See the Breakout File Structure Overview guide.
  • Browse the documentation to learn more about the various objects in the Breakout library.
  • Read the Using Breakout Server guide to learn how to enable multi-client connections and how to select a new webserver root directory.