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 breadboard.


View system and browser requirements

Download and Install Breakout

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

Upload BreakoutFirmata 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 Arduino website.

  1. Install the ConfigurableFirmata library in you Arduino sketchbook libraries folder. The easiest way to install it if you are using Arduino version 1.6.4 or higher is to use the Arduino Library manager (in the Arduino IDE, navigate to Sketch > Include Library > Manage Libraries, then search for “ConfigurableFirmata” and click on Install after tapping on the ConfigurableFirmata item in the filtered results. If you have an older Arduino IDE, see the installation instructions in the ConfigurableFirmata README file.
  2. Navigate to Breakout/firmware/BreakoutFirmata/.
  3. Open BreakoutFirmata.ino in Arduino 1.0 or higher (Preferably Arduino version 1.6.4 or higher).
  4. Compile and upload BreakoutFirmata to your I/O board (make sure your particular I/O board is selected under Tools -> Board).

BreakoutFirmata 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 tutorial by ladyada..

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 (you’ll find it in Breakout/server/) for your platform to launch it (Linux users need to launch the jar file from the command line unless you set up a custom 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 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. You should be able to click the LED On an LED Off buttons to turn the LED wired to pin 11 on or off. If you press the button wired to pin 2 of the Arduino board, the button state (pressed or released) 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 71.

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. Use the buttons to turn the LED on or off. Pressing the physical button on the breadboard will display the button state (pressed or released) on the screen below.

Let’s take a look at the hello_world code

The minified file Breakout.js is included near the top of the file. You’ll see jQuery is also included on the following line. 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 LED =;
var Button =;
var ButtonEvent =;

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

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

var arduino = new IOBoard(host, 8887);

Host is the IP address or hostname of the computer the IO board is connected to. The host is set to either “localhost” or window.location.hostname (which is the IP address of the computer serving this web page). Just in case the following lines don’t make sense, I’ll explain them briefly:

var host = window.location.hostname;
// if the file is opened locally, set the host to "localhost"
if (window.location.protocol.indexOf("file:") === 0) {
  host = "localhost";

What this does is sets the host by default to window.location.hostname, but if the file is opened directly (double-clicking on the html file) instead of loading it from a server, the host is set to “localhost”. This enables the file to be opened by either means. However you can leave these lines out in your own applications and simple set the host to “localhost”, window.location.hostname, or a specific IP address. Setting host to window.location.hostname enables you to open the application locally or on a mobile device on the same network as the computer the IO board is connected to.

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.

arduino.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:

arduino.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.

led = new LED(arduino, arduino.getDigitalPin(11));

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 ( 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 button = new Button(arduino, arduino.getDigitalPin(2), Button.PULL_DOWN);

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

button.addEventListener(ButtonEvent.PRESS, onPress);
button.addEventListener(ButtonEvent.RELEASE, onRelease);

The onPress method is called whenever the physical button is pressed and the onRelease method is called every time the button is released. The parameter passed to onPress and onRelease 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 gives us a reference to the button that was pressed (in the case that 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 onPress(evt) {
  // get a reference to the button object that fired the event
  var btn =;
  $('#state').html("Button " + btn.pinNumber + " state: Pressed");

function onRelease(evt) {
  // get a reference to the button object that fired the event
  var btn =;
  $('#state').html("Button " + btn.pinNumber + " state: Released");

The following 2 lines register click events with the two on-screen buttons:

$('#btnLeft').on('click', turnLedOff);
$('#btnRight').on('click', turnLedOn);

When a button is clicked, the LED is turned on or off:

function turnLedOn(evt) {
  // turn the LED on

function turnLedOff(evt) {
  // turn the LED off;

The remaining code is simply used to show or hide the schematic view.

Next Steps

  • Take a look at the getting started examples in Breakout/examples/. Wire up the circuit on page 3 of the schematics.pdf and open Breakout/examples/index.html on a desktop/laptop computer, tablet or smartphone.
  • Try out some of the sensor and actuator examples if you have the components.
  • 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.