/Breakout

Breakout is a javascript library and toolkit for connecting Arduino and other IOBoards to the web

Primary LanguageJavaScriptMIT LicenseMIT

About

Breakout is a prototyping tool for exploring the intersection of the web and the physical world. The popular Arduino platform and the Firmata protocol are leveraged to enable users to access physical input and output purely from javascript. This makes it easy for anyone familiar with javascript and basic web development to explore the possibilities of using physical I/O in their web applications. Furthermore, the Breakout framework includes a growing library of hardware abstractions such as buttons, leds, servo motors, accelerometers, gyros, etc enabling the user to easily interface with a range of sensors and actuators using just a few lines of javascript code.

Breakout grew out of a need for a simple platform to enable designers to prototype functional web-based interfaces to the physical world. It is based largely on the Funnel toolkit and informed by the experiences of the developers of both Funnel and Breakout as designers, technologists and educators.

Breakout is currently beta software. The API is stable, but bugs are possible. Please create an issue if you suspect a bug. Additional examples and hardware abstractions (Breakout/src/io/) will likely be added.

See breakoutjs.com for detailed documentation and other helpful information.

Contributors are welcome. If you have any ideas, suggestions for improvements, examples to share, or anything else you'd like to contribute please get in touch.

Quick Start

See the detailed Getting Started guide on breakoutjs.com or the quickstart guide below.

The first step is to upload StandardFirmata to your Arduino (or Arduino-compatible) board and wire up some components:

  1. Launch Arduino 1.0 and navigate to File -> Examples -> Firmata -> StandardFirmata
  2. Compile StandardFirmata for your board and upload.
  3. Wire up a button and led to you I/O board as illustrated on page 2 in Breakout/examples/schematics.pdf (or download here).

The next step is to run the Breakout Server application:

  1. Make sure your I/O board is attached and the StandardFirmata sketch is uploaded.
  2. You'll find Breakout Server (Breakout Server.app for OS X, Breakout Server.exe for Windows, BreakoutServer.jar for Linux) in Breakout/server/. Simply double-click to launch the application. Note: Linux users need to run sudo apt-get install librxtx-java or manually install the librxtxSerial.so driver before launching the BreakoutServer.jar application.
  3. Select the serial port for your board from the drop-down if it is not the current port displayed.
  4. If your firewall is enabled, make sure port 8887 is open (or enter a new port that is open).
  5. Click the Connect button. You should see the message "Server running on: : 8887/" followed by "Connected to IOBoard on: ".
  6. Open http://localhost:8887/examples/getting_started/hello_world.html in Chrome (v14 or greater), Firefox (v7 or greater), or Safari (v5 or greater). If you changed the network port in step 4, update it on line 36 of the hello_world.html example and in the url above.

For more information on using Breakout Server including enabling multiple client connections, changing the webserver root directory, or using Breakout with mobile devices, see Using Breakout Server.

As an alternative to the Breakout Server application, a node.js-based server is also included. See the Using the node.js server for details.

Requirements

Breakout is only supported for Arduino 1.0 and higher Download Arduino 1.0.

You will need one of the following I/O boards:

  • An Arduino version Diecimila or newer (Uno, Fio, Mega, Pro, LilyPad, etc).
  • Teensy 2.0, Teensy++ 1.0 or 2.0
  • Many Arduino clones / variants should also work
  • See Test Environment for full list of tested I/O boards

OS:

  • Mac OS X 10.6 or higher
  • Windows 7 or XP (32-bit Java JRE 1.6 or greater required)
  • Has been tested successfuly on Ubuntu 11.10 running in 64-bit mode on an x86-64 processor
  • May work on older versions of OS X and Windows as well but has not been tested
  • May work on other Linux distributions but has not been tested

Desktop Browsers:

  • Chrome version 14 - 18
  • Firefox version 7 - 11 (version 11 is recommended)
  • Safari version 5 or higher

Mobile Browsers (browser must support websockets):

  • Safari mobile
  • Firefox mobile version 7 or higher
  • Chrome Beta (for Android 4.0 and higher)
  • See Test Environment for list of tested phones and tablets

Credits

Breakout is developed by Jeff Hoefs

Breakout is based largely on the as3 library of Funnel. The author is also a contributor to the Funnel as3 library.

Logo and icon designed by Claire Lin

Breakout Server uses webbit

License

Breakout is distributed under the terms of the MIT License. See the LICENSE file.

Change Log

See the ChangeLog file.