JavaScript Serial

The follwowing is an example of a web page that can interact with a serial port on a local machine (the machine displaying this page).

This software is not maintained (it probably won't even work) and NO support is provided. Email will not be returned.

source is available. It requires the Serial.jar file from Processing.org as well as RXTX.

Setting it up

There are a couple of things that have to be done in order for this to work.

First of all, it must be known that JavaScript itself is "sandboxed" so that it can not interact with hardware other than a keyboard and mouse on a local computer. In order to get around this limitation (reading and writing to a serial port being an example) we need to use some intermediary means.

In many projects of this nature (Flash to Serial communication being an example) a piece of software is typically run on the local machine which provides a socket connection to the software and and in turn exposes the local serial port. Unfortunately, with JavaScript this is difficult as JavaScript can typically only talk to servers that delivered it in the first place (the page being delivered) and second of all it can currently only speak HTTP.

Thankfully we have Java Applets. Java Applets can be run inside a web page and can interact with JavaScript running on that page.

To run a Java Applet on a page, specifically the Java Applet that allows us serial communication we need to include tags such as these:
		<script src="http://www.java.com/js/deployJava.js"></script>
		<script> 
			var attributes = { code:'JSSerial.class', archive:'JSSerial.jar',  width:100, height:100, id:'JSSerial'}; 
			var parameters = {jnlp_href: 'jsserial-applet.jnlp'}; 
			deployJava.runApplet(attributes, parameters, '1.5'); 
		</script>


Unfortunately, Java Applet's are also sandboxed. Meaning they can not typically read and write to serial ports either. To allow this to work, we need to "sign" the applet. This gives the applet permissions to access more of the machine.

You may have noticed that the applet on this page requested you to allow it to run and it was signed by me. I won't go through the details of signing, instead you can just download and use the Applet that I have already signed, JSSerial.jar for inclusion on your site (wherever your HTML/JavaScript is hosted).

Last, this Applet needs an extra library installed on your machine in order for it to work. Down the road, I plan to package this up with the Applet itself but right now that is not complete.

This library is called RXTX and it is what gives Java the capabilities to read and write from the serial port. You can download RXTX from here: http://rxtx.qbang.org/wiki/index.php/Download. I recommend getting the latest stable version as a binary: http://rxtx.qbang.org/pub/rxtx/rxtx-2.1-7-bins-r2.zip.

The installation instructions on the site aren't that great so here are some platform specific instructions:

To allow access to your serial ports you need to do a couple of things:

Mac OS X
Download and extract RXTX, find RXTXcomm.jar and librxtxSerial.jnilib and copy them to /System/Library/Java/Extensions/. You will need system administrator privelages to do this.

This next step is a bit more complicated:

Open up terminal (Applications/Utilities) and type the following commands followed by a return (after each line):
		sudo mkdir /var/lock
		sudo chmod 777 /var/lock

If that command gives you an error saying "File Exists" no worries, everything is good.

Windows
On Windows, you may have several installs of Java on your machine. Different browsers may be configured to run a different install of Java as well. It is a good idea, if you see multiple installs to copy the files into all of the directories for Java:

Copy rxtxParallel.dll to c:\Program Files\Java\jreX.XX\bin\
Copy rxtxSerial.dll to c:\Program Files\Java\jreX.XX\bin\
Copy RXTXcomm.jar to c:\Program Files\Java\jreX.XX\lib\ext\


Once that is all done, you may need to restart your browser in order to continue.

Limitations

Right now, this is known to work on Safari and Firefox on MacOS X. It is not known whether or not it works on Windows but it should.

Testing it out

Next you should be able to click this button:
and see some output here:
NOTHING YET


If you see a list of serial ports on your computer, all is well. If not, drop me an email: Shawn.Van.Every@nyu.edu

You may also want to enable the Java console so you can see and tell me what the error messages are that you see:
On the Mac, to see the Java Console go to: Applications Utilities then Java Preferences
In Java Preferences go to the "Advanced" tab and select "Show console" under the "Java console" dropdown.

The JavaScript Calls

What the above button does is that it calls a function through JavaScript that is inside the JSSerial Java Applet. The syntax is this:
document.JSSerial.listPorts()
It returns a list of which is the names of the ports available to you (comma separated). 

			function listPorts()
			{
				var serialPortList = document.JSSerial.listPorts();
				var aSerialPortList = String(serialPortList).split(',');
				var outputDiv = document.getElementById("listportsoutput");

				var outputString = "";
				for (i = 0; i < aSerialPortList.length; i++)
				{
					outputString += i + ":" + aSerialPortList[i] + '
';
				}
				outputDiv.innerHTML = outputString;
			}
The JSSerial Java class is really just a thin wrapper around Processing's Serial Object. Many of the methods detailed for that class should work here assuming you prepend "document.JSSerial" instead of the Java serial object.

Opening a serial port (this one is a bit different): document.JSSerial.startSerial(...);
It can be any of the following: 
		document.JSSerial.startSerial();
		document.JSSerial.startSerial(String name);
The rest are pretty much as documented: 
		document.JSSerial.available();
		document.JSSerial.read();
		document.JSSerial.readChar();
		document.JSSerial.readBytes();
		document.JSSerial.readBytesUntil();
		document.JSSerial.readString();
		document.JSSerial.readStringUntil();
		
		
		document.JSSerial.last();
		document.JSSerial.lastChar();
		document.JSSerial.clear();
		document.JSSerial.stop();
		document.JSSerial.list();		
		
		These are a bit different but self explanatory:
		document.JSSerial.writeInt(integer)
		document.JSSerial.writeByte(byte)
		document.JSSerial.writeString(string)
		document.JSSerial.writeBytes(byte[])

Examples


Calls: 
		function openPort()
		{
			var serialPortList = document.JSSerial.listPorts();
			var aSerialPortList = String(serialPortList).split(',');
			document.JSSerial.startSerial(aSerialPortList[0]);
		}

Calls: 
		alert(String(document.JSSerial.readString()));

Calls: 
		document.JSSerial.close();

Calls: 
		document.JSSerial.writeByte(10);

Calls: 
		document.JSSerial.writeInt(10);

Calls: 
		document.JSSerial.writeString("Hello World");

Calls: 
		document.JSSerial.writeBytes(new Array(10,11,12));

Calls: 
		startTimer(); 
		// In the button
		
		// which references this javascript:
		var timer;
		function startTimer()
		{
			timer = setInterval("timerran()",10);
		}
		
		function timerran()
		{
			var outputdivtimer = document.getElementById("outputdivtimer");
			outputdivtimer.innerHTML = document.JSSerial.readString();
		}
NOTHING YET

Your Own

You need the following files: JSSerial.jar and jsserial-applet.jnlp along with your own HTML/JavaScript.
You will have to edit the jsserial-applet.jnlp to put in your own "href" and "codebase" values depending on where you put your files.

Examples

Graph Sensor Values (JSSerial Version of: Processing Version
New Graph Sensor Values (Works better and includes Arduino code)
Moving a div
Hana's Getting Started Notes
DanO's Multiple Sensor Example with Call and Response
Using JSSerial in combination with AJAX for reading/writing from the server