Cylon.js - Browser Support

As of version 0.20.0, Cylon.js has support for running inside browser JS runtimes. This is thanks in no small part to the Browserify tool.

For the purposes of this guide, we're going to break apart browser support into a few main sections.

Platform Support, which lists the Cylon.js modules that can be used in-browser.
Browserify, which covers the basic process of getting a Cylon.js robot running in almost any browser.
Chrome Apps, which covers running robots to run inside of a Chrome app. This requires some extra setup, but allows for additional platform support through serial communication.

The Browserify section forms the base the Chrome App and Phonegap sections build on, so it's recommended to start there before continuing into the section of your choice.

Platform Support

Due to security limitations of browser JS runtimes, not all Cylon.js modules are supported in-browser. Modules that use HTTP for device communication work out-of-the-box, with no modification.

However, any module that communicates with devices over a serial port or bluetooth connection, or any other hardware link, will not work from inside a browser.

There is an exception to this, and that's Chrome Apps. When building a Chrome App, users can request permissions to communicate with serial ports and bluetooth hardware, and this increases the number of supported modules.

Here's all currently known supported modules:

Browserify and Phonegap:

cylon-force
cylon-hue
cylon-leapmotion
cylon-m2x
cylon-mqtt
cylon-nest
cylon-skynet
cylon-spark

Chrome Apps supports all of the above, plus:

cylon-firmata
cylon-sphero
cylon-neurosky

Browserify

Building Cylon.js apps for browsers and Phonegap is done using the Browserify tool.

If you don't already have it installed, it's available through NPM:

$ npm install -g browserify

With this done, you can write your Cylon.js robot as usual. For this basic example, we'll use a Leap Motion:

var Cylon = require('cylon');

Cylon.robot({
  connections: {
    leapmotion: { adaptor: 'leapmotion' }
  },

  devices: {
    leapmotion: { driver: 'leapmotion' }
  },

  work: function(my) {
    my.leapmotion.on('hand', function(hand) {
      var position = hand.palmPosition.join(',');
      console.log("Hand position: " + position);
    });
  }
});

This is a fairly simple robot, but it'll do for our purposes. Next, compile it for browser usage with Browserify:

$ browserify -r cylon-leapmotion script.js > browser_script.js

Now all we need to do is write a small HTML page (index.html) for it to run in:

<!doctype html>
<html lang="en">
  <head>
  </head>

  <body>
    <script src="browser_script.js"></script>
  </body>
</html>

Now we're all set. You can open index.html in your browser of choice, and the developer console should show Cylon running and printing data as it gets it from the LeapMotion.

For a ready-to-go example, check out our cylon-example-browserify GitHub repo.

Chrome Apps

Building a Cylon.JS app for Chrome requires a bit more packaging, but in turn gives you more functionality. With the ability to connect to serial ports, you can control even more hardware this way.

Since this does require some additional setup, we recommend using our [example repo][cylon-example-chrome], and building on that.

To get started, clone the example down into a new directory:

$ git clone [email protected]:hybridgroup/cylon-example-chrome.git ./BrowserBot
$ cd ./BrowserBot

Then, install dependencies with NPM:

$ npm install

By default, the example is set up to communicate with an Arduino using cylon-firmata, but you can always use another set of modules if you want.

There's a few key differences between this and the plain browser version, we'll go over those next:

manifest.json

This file exists to provide Chrome with important information about your app. Use it to specify the name, description, and version of your app, and to request permissions as needed.

The default manifest.json requests all permissions you should need.

For more information about the manifest.json format, check out Google's documentation.

background.js

Chrome needs a file to run when the extension starts, so we've supplied background.js. This file contains information Chrome needs on what to do when the app is launched, and can also be used to schedule cleanup tasks.

The one we've supplied creates a new window, opening index.html on launch, with a pre-set window size.

index.html

This is a simple HTML document, used to load up the robot. It also contains a #log <div> tag for the custom browser logger we've included.

browser-logger.js

This is a small custom Cylon logger we've included. It knows how to log Cylon messages directly to the page, rather than the JS console.

With these distinctions in mind, you can write your Cylon.js robots as usual.

However, packaging up your robot for Chrome requires a bit more care than usual, due to the nature of Browserify. Browserify parses the AST of your script to determine which scripts should be loaded, and this normally works fine. But due to Cylon's dynamic module loading, you need to manually specify the modules your robot uses.

To build the example app, for instance:

$ browserify -r cylon-gpio -r cylon-i2c -r cylon-firmata script.js > ./js/robot.js

For testing purposes (or just playing around), you can load your app as an unpacked extension in Chrome. This video should help explain the process:

Index