breakout-server is provided as an alternative to the Breakout Server GUI application. It is a node.js-based server for Breakout.js, bridging serial data from an Arduino board to and from a web browser using websockets. It also provides a simple webserver for hosting static content.
$ npm install breakout-server
This will only install the server. You will need to clone or download Breakout.js separately. Minimally all you need from Breakout.js is the files in
Breakout/dist/ and the firmware in
Windows users, refer to the readme for node-serialport before attempting to install breakout-server.
Install required Arduino libraries
- Install ConfigurableFirmata to your Arduino sketchbook library. The easiest way to get it if you are using Arduino 1.6.4 or higher is using the Arduino Library Manager. In the Arduino IDE, go to
Sketch > Include Library > Manage Librariesthen search for "ConfigurableFirmata" and click Install after tapping on the ConfigurableFirmata item in the filtered results. Otherwise, following the instructions in the ConfigurableFirmata readme.
- Download or clone Breakout.js and navigate to
BreakoutFirmata.inoin the Arduino IDE. Compile and upload the sketch to your board.
node server.js --help to view the command line options.
You will need to provide the name of the serial port you are connecting to. You can get the name
by connecting a board to your computer, and running
ls /dev/tty.* in the terminal in OS X,
ls /dev/ttyACM* in the terminal in Linux, or get it from the Arduino IDE under
Tools -> Serial Port. When running the server, specify the port using the
-p command as follows (substituting in the serial port name for your attached board):
$ node breakout-server/server.js -p /dev/cu.usbmodem14241
You can alternatively change the default serial port name by updating the following line in server.js:
.option('-p, --port <device>', 'Specify the serial port [/dev/cu.usbmodemfd121]', '/dev/cu.usbmodemfd121')
It is important to understand the relative path from where you run breakout-server to the root of the website. You may need to supply the path using the
-d option depending on the location of your index.html file relative to where you run the server from. For example, if you created a project directory and installed breakout-server into that directory using npm and you also created another folder named 'public' that contains your static files, then you would run the server from the root of the project directory as follows:
$ node breakout-server/server.js -p /dev/cu.usbmodem14241 -d public
And then in your browser navigate to:
To run the examples included with breakout-server, navigate to the breakout-server directory and run server.js:
$ cd breakout-server $ node server.js -p YOUR_SERIAL_PORT
Then navigate to
http://localhost:8887/examples/simple_led.html in your browser.
To run the examples included with Breakout (
Breakout/examples/) you will need to
install breakout-server within the Breakout directory. This is due to the relative paths set to
the socket.io.js file (see more about this below).
$ cd Breakout $ npm install breakout-server $ node breakout-server/server.js -p YOUR_SERIAL_PORT
And then in your browser navigate to:
Schematics for the examples can be found here: http://breakoutjs.com/examples/schematics.pdf
Additional command line options
There are 2 additional command line options:
-sis used to change the server port (default = 8887)
-mis used to put Breakout into a state where multiple web applications can connect to the same board. To enable it, pass
-m true. However, understand that this is not practical in many situations (since 2 or more web applications could try to access the same pin on a board for example.) it's perhaps provided more of an experiment than anything else.
Including socket.io client in your index.html file
When creating your index.html file, include
socket.io.js before the
Breakout.min.js script. This is included in all of the files in
Breakout/examples/ so use those as a reference.
There are two ways to include
- Allow the socket.io server (
breakout-server/server.js) to provide it. If you take this route, you will need to ensure that the path to
socket.io.jsis relative to where you are running the server from. For example, if your project directory has
publicfolders at the top level and your run the server from the top level of the directory (
node breakout-server/server.js -p YOUR_SERIAL_PORT) then you would use the following path when including socket.io.js in your index.html file because the project root (where you are running the server from) is one level above the
socket.io.jsfrom a cdn (for example). This is the most flexible since you don't need to worry about the path to the server, but you'll need to be sure the version is compatible. See
breakout-server/node-modules/socket.io/package.jsonfor the current version of the socket.io server. Also if you get
socket.io.jsthis way then you can use a separate webserver for your project and simply use breakout-server as a serial to websocket bridge.