Control Bitlash-enabled Arduinos with Node.js
JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
.gitignore
LICENSE
README.md
bitlash-tcp.js
bitlash-web.js
package.json
test.js
testfile

README.md

node-bitlash - Control Bitlash-enabled Arduinos with Node.js

This is a node.js library that enables PC control of a USB-connected Arduino running Bitlash. Bitlash is an interpreter that runs on the Arduino and executes commands sent over the serial port. More on Bitlash at http://bitlash.net

You can execute Bitlash commands, files of Bitlash commands, or a url whose contents contain Bitlash commands; node-bitlash returns the resulting bitlash output to your node.js code.

It's also easy to use node-bitlash without Bitlash with some small tweaks to your Arduino C program. See the section below for details.

Requirements

Installation

$ git clone http://github.com/billroy/node-bitlash
$ cd node-bitlash

For a quick test, plug in your Arduino and run:

$ node test.js

Usage

Setting up a Bitlash instance

Here is how to require the library, create and initialize a Bitlash instance, and catch the ready callback to start working with Bitlash:

var Bitlash = require('./lib/bitlash.js');
var bitlash = new Bitlash.Bitlash({}, function (readytext) {
	// ...your code here...
});

The readycallback function will be called once Bitlash is ready to accept commands. It is passed the text of the signon banner. It is not valid to call other methods on the bitlash object until the ready callback has fired.

The options object may contain these options:

  • port: serial port (auto)
  • baud: serial port baud rate (57600)
  • debug: true for debug spew (false)
  • echo: echo serial port to terminal (false)

On mac and linux the first arduino usbserial port found will be used unless you specify a different port. On windows you must specify the port.

Pass {} if you don't need to pass any options.

bitlash.exec(command [, function(reply) {}]);

Execute the given Bitlash command on the Arduino and call the callback function with the resulting Bitlash output as its first and only argument.

bitlash.exec('print millis', function(reply) {
	console.log('millis:', reply);
});

It is only valid to call bitlash.exec() after the ready callback has fired.

bitlash.stop();

Sends ^C to Bitlash to stop any looping functions.

bitlash.stop();

bitlash.sendFile(filename [, function(bigreply) {}]);

Sends a file of commands to Bitlash, one line at a time. Accumulates the output of all the commands and passes it to the (optional) callback function when complete.

If filename starts with http: or https: the contents of the url are sent to Bitlash.

bitlash.sendFile('testfile', function(reply) {
	console.log('and the output was:', reply);
});

It is only valid to call bitlash.sendFile() after the ready callback has fired.

Sample Node.js program

(See the file test.js in the distribution.)

var Bitlash = require('./lib/bitlash.js');
var run_blinky = false;

var bitlash = new Bitlash.Bitlash({}, function (readytext) {
	console.log('Banner:', readytext);

	bitlash.exec('ls', function(reply) {
		console.log('Reply 1 from bitlash:', reply);

		bitlash.exec('print millis', function(reply2) {
			console.log('Reply 2 from bitlash:', reply2);

			bitlash.exec('print random(1000)', function(reply3) {
				console.log('Reply 3 from bitlash:', reply3);

				bitlash.sendFile('testfile', function (reply4) {
					console.log('Reply 4 from bitlash:', reply4);
				});
			});
		});
	});
});

setInterval(function() {
	if (!run_blinky) return;
	bitlash.exec('d13=!d13', function(reply) {
		//console.log(reply);
	});
}, 125);

Example: bitlash-tcp.js

See this example for a simple use of the bitlash library to expose a usb-connected bitlash over tcp.

$ node bitlash-tcp.js

In another terminal:

$ nc localhost 3000

Example: bitlash-web.js

See this example for a simple use of the bitlash library to expose Bitlash as a web service. The example starts a web server on port 3000 and listens for POST requests to the url /bitlash. Post bodies should contain JSON in the format {"cmd":"print millis"}. The output generated by the Bitlash command is sent as the browser reply.

Here is how you can use curl from the command line to test the web interface:

$ curl -X POST -H 'Content-Type:application/json' -d '{"cmd":"print millis"}' localhost:3000/bitlash
234434
$

Using node-bitlash without Bitlash

It's easy to use node-bitlash with your own Arduino C program. Instead of Bitlash commands, send the commands your program expects. Bitlash expects commands to end with a newline character ('\n'), so make sure your program expects the same.

One change you need to make is to send the standard Bitlash prompt string at the end of your command's output. The standard prompt is "\n> ", or three characters, the newline '\n', the greater-than '>', and a blank ' '. This allows node-bitlash to understand when your command's execution and output are complete.

BUGS

  • BUG: catch and handle bitlash exceptions
  • move to EventEmitter model
  • test bitlash.stop