View on GitHub

codebender compilerflasher

Javascript library for compiling and flashing Arduino sketches from your browser

Demos

codebender compilerflasher

codebender compilerflasher is a javascript library that enables compiling Arduino sketches, and flashing the binaries to Arduino & Arduino compatible devices through the browser using the codebender.cc plugin for Chrome & Firefox.

Dependencies

jQuery

compilerflasher uses jQuery, this powerful javascript library that makes HTML manipulation simple and easy.

Lawnchair (optional)

Lawnchair is a simple client side json storage. Compilerflasher uses it to maintain the last chosen board, programmer or port used, and autoselect it upon next page load. If you don't want to use lawnchair, it's fine! Compilerflasher can operate normally without it.

Getting Started

Step 1: Include the library

To use the library, first you have to include jQuery, and the library itself:

    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
    <script src="//codebender.cc/embed/compilerflasher.js" type="text/javascript"></script>

Step 2: Add the HTML Elements you need

Then, on your HTML add any compilerflasher elements you need to use. The full list of the supported html elements is described later. On this example we are going to create a page that compiles a basic arduino sketch. So we need the list of supported boards, the compilation button and some text ouptut:

    <select id="cb_cf_boards"></select>
    <button id="cb_cf_verify_btn">Verify code!</button>
    <p id="cb_cf_operation_output"></p>

Step 3: Create your compilerflasher

On the javacript side, we have to implement a function that returns the code we want to compile on the following format:

Object {sketch.ino: "void setup(){} void loop(){}", header.h: ""})

This is an example of such a function:

function getFiles(){
    return {"sketch.ino": "void setup(){} void loop(){}"}
    }

Finally, initialize compilerflasher:

 $(document).ready(function(){
    compilerflasher = new compilerflasher(getFiles);
    });

See some cool demos!

HTML Elements

On the app using compilerflasher.js, you can add any of the following elements:

Element Description
<select id="cb_cf_boards"></select>

A selection of supported Arduino & Arduino compatible boards. The currently supported boards can be found here.


Preselect a board

<select id="cb_cf_boards" data-board="Arduino Uno" ></select>

If your app is board-specific, you can preselect a board by using the data-board attribute. This will cause the board selection to be hidden.

<button id="cb_cf_verify_btn" ></button>

A button that compiles the source code provided to compilerflasher (see Javascript section).

<select id="cb_cf_ports"></select>

A selection of currently available ports. The ports are indentified by the aforementioned browser plugin.

<button id="cb_cf_flash_btn"></button>

A button that first compiles the code, and then uploads the binary of the source code, on the Arduino device connected on the selected port of "cb_cf_ports".

<select id="cb_cf_programmers"> </select>

A selection of supported programmers.

<button id="cb_cf_flash_with_prog_btn"></button>

Button that compiles the code, and then uploads the binary to your board using the selected programmer of "cb_cf_programmers"

<select id="cb_cf_baud_rates"></select>

Selection of supported Baud Rates for connection to the Serial Monitor.

<button id="cb_cf_serial_monitor_connect"></button>

Button that connects to the selected port of "cb_cf_ports" on the selected speed of "cb_cf_baud_rates", and opens up the serial monitor included in "cb_cf_serial_monitor" .

<div id="cb_cf_serial_monitor"></div>

Div that includes the serial monitor itself, and a textbox and button to send serial data.

<p id="cb_cf_operation_output"></p>

Generic compilerflasher text output. Any message that is generated by compilerflasher is printed here.

All those elements can be styled to your needs, using either custom stylesheets, or external plug-n-play frameworks like Bootstrap.

Javascript

In order to make use of all the loaded elements, you have to initialize the compilerflasher class. That can be done with the following line of code:

compilerflasher = new compilerflasher(File_Getter);

File_Getter is a function that you have to implement, and returns the files you want to use for compilation & flashing, on the following format:

Object {sketch.ino: "void setup(){} void loop(){}", header.h: ""})

This function is called whenever the files need to be fetched (i.e. before Verification), so you could either return static data, if you want your page to operate like so, or use a function that returns different files every time.

Events

Compilerflasher.js supports a set of events that can be hooked by your app. Callbacks for each event can be added likeso:

compilerflasher.on(eventName, callback);

Where eventName is a string included on the list mentioned later, and callback is a function that may, or may not have parameters depending on the event.

Available Events

Event Usage Description
pre_verify compilerflasher.on("pre_verify", function(){/*your code here*/});

Gets fired before the verification process, when user clicks on the "cb_cf_verify_btn" button. Callback of this event takes no parameters.

verification_succeed compilerflasher.on("verification_succeed", function(binary_size){/*your code here*/});

Gets fired upon successful verification. Callback function can take one parameter, which is the compiled binary size in bytes.

verification_failed compilerflasher.on("verification_failed", function(error_output){/*your code here*/});

Gets fired upon failed verification. Callback function can take one parameter, which is the compiler’s error output.

pre_flash compilerflasher.on("pre_flash", function(){/*your code here*/});

Gets fired before the flashing process, either when user clicks on the "cb_cf_flash_btn" button, or when user clicks on the "cb_cf_flash_with_prog_btn" button. Callback of this event takes no parameters.

mid_flash compilerflasher.on("mid_flash", function(size){/*your code here*/});

Gets fired in the middle of the flashing process, after the successful compilation of the sketch. Callback function can take one parameter, which is the compiled binary size in bytes.

flash_failed compilerflasher.on("flash_failed", function(message){/*your code here*/});

Gets fired when the flashing proccess fails. Callback can take one parameter, which is the error message.

flash_succeed compilerflasher.on("flash_succeed", function(message){/*your code here*/});

Gets fired when the flashing proccess fails. Takes no parameters.

plugin_notification compilerflasher.on("plugin_notification", function(message){/*your code here*/});

Fired to give your app a generic notification created by our browser plugin. Callback can take one parameter, which is the notification.

plugin_running compilerflasher.on("plugin_running", function(){{/*your code here*/});

Fired when plugin has finished initializing, and started running without any issues.