Seriality examples

Introduction

This tutorial runs through how to use the Seriality plugin to communicate via a serial interface between your browser and circuits you have made. Normally javascript is sandboxed so cannot access local computer files or ports, but the Seriality plugin allows this to happen. This means you can use html, css, javascript (plus libraries such as jquery) and more to create interfaces for your circuits.

Most of the content here is adapted from the Seriality project pages or Neil Gershenfeld's input devices page.

Requirements

To work through these examples you will need the following:

Getting Started

Installation of the plugin differs according to operating system.

For OS X, download the installer, mount the disk image and copy the Seriality.plugin file to the Internet Plug-Ins folder as indicated.

For linux (or at least Ubuntu 12.10 which I tested this on), download the source code. Next install scons from the terminal with $ sudo apt-get install scons. Unzip the source code and navigate in terminal to /Seriality_Source_20100306/seriality/. To enable the plugin to be built, a file needs editing; use $ gedit seriality.cc, then just above #include <string> add two lines, #include <stdio.h> and #include <string.h>. Save the file and exit, then use $ scons to build the plugin. The operation should end with the line scons: done building targets. Finally, move the libseriality.so file to your browser plugin folder; I was using Firefox so used $ sudo cp libseriality.so /usr/lib/mozilla/plugins/.

Once installed, restart your browser and ensure that Seriality is listed as a plugin in your browser preferences. Note that in Ubuntu, the serial ports are protected so you need to provide permission for the browser to access them. The easiest way is to start the browser as root, eg using $ gksu firefox. This is not necessary on OS X.

Using the Plugin

The easiest way to get going with Seriality is to load up some examples and see how things work. To this end, I've written three example applications comprising pairs of html files and c programs. When the c programs are loaded on the board described above, they interact with the html files via the Seriality plugin. The examples work as follows:

The code (both javascript and c) is all commented to try and explain what is happening at each stage, so hopefully these files are self-explanatory. To program the board with a particular c program, first navigate in terminal to the folder, for instance /seriality_led/. Directions from here are for using the fabISP; if you want to use the AVRISP mkII replace usbtiny with avrisp in the commands. Also, sudo is included in the commands but is not required on OS X. It should not be necessary to set the fuses on the board as these programs use the default fuses, but if you do wish to do so you can use $ sudo make program-usbtiny-fuses. Then program with $ sudo make program-usbtiny. If programming is unsuccessful refer here. If successful, disconnect the board from the programmer and connect via the usb-serial cable. Load the corresponding web page (locally or from above) and everything should work!

If you want to use the examples with different boards, you can edit the port/pin definitions in the c programs to reflect the layout of your circuit.

Browser compatibility

These examples have been tested on the following OS/browser combinations:

Similar variations of these setups should also work. There is also the potential for the plugin to work in Chrome - see the discussion here for details.

If you establish another working setup, or develop something using this plugin, please do update this page with details.

Joel Rae - April 2013