README
node-backchat
Backchat is a chat handler for managing conversations (command/response) with simple serial devices. These might be (for example) devices that support the Hayes AT command set or similar line-oriented text exhange interactions. Backchat isn't suitable for establishing modem links (there's no way to hand off to the data stream) but will work in other cases such as SMS messaging on some GSM modems or for managing a Zigbee Coordinator.
Basic features
Abstracts connection layer to support both local (serial) devices and tcp sockets (uses a URI form to specify the device so the calling interface is the same regardles of network or serial port).
Response buffering (line by line) with an event dispatcher that allows multi-line responses to be collected and dispatched together via EventEmitter.
A rate limiter to prevent flooding the device with multiple asynchronous requests (device access is locked on each write and a 'writeDelay' enforced to enable the rate of command writing to be throttled).
How it works
Say you are writing a script to chat to a device which accepts text commands
(e.g. the "AT" command set) and returns responses to your commands with defined
prompts. The approach taken with Backchat is that the lines are buffered until
it finds a string (coming back from the device) that matches one of those
specified in "eventTriggers", then it emits an event with the entire response
buffer for proceessing asynchronously by your event handler. The names of the
events raised are derived from the commands you send the device, with some
basic pre-processing (just to remove any trailing arguments, and lowercase the
result). This means that for example, if you routinely issue COMMAND:A
,
COMMAND:B
and COMMAND:C
, you could tell Backchat to strip off the ':'
character and trailing text, and have it emit a 'command' event which you use
to process the buffered results from those commands.
For example, you might issue a command ATCOMMAND:WITH,SOME,ARGS\r
, and the
device executes your command, issues a number of lines of text in response,
and then finishes with an OK
or ERROR:CODE
response. To use Backchat with
this stream you'd configure 'OK' and 'ERROR' as prompts to trigger an event
and buffer flush, and specify ':' as a character used to strip trailing
arguments. Then when either of 'OK' or 'ERROR' are encountered, the first line
of the buffer is processed, and an event 'atcommand' is raised.
Specifying the device URI
Serial Devices
example: serial:///dev/ttyS0?baudrate=57600&databits=8&parity=none&stopbits=1
Note that any parameters supported by the Node.js serialport library can be supplied.
Defaults:
var serialSettings = {
baudrate: 19200,
databits: 8,
parity: 'none',
stopbits: 1,
flowcontrol: false,
parser: ser.parsers.readline("\r\n") // take care of line buffering
};
Network Sockets
example: tcp://hostname:port
Sample Use
The following simple example opens a serial device at /dev/ttyUSB0 at 19200 baud, with a writeDelay of 50 milliseconds. The eventTriggers array specifies strings in the response stream that trigger an event to be emitted (at which point the read buffer is sent). The eventNameStrip array specifies the characters which will be used to strip off trailing characters from the first line of the read buffer to generate the event name.
var Backchat = require('backchat');
var mySerialHandler = new Backchat({
eventTriggers: [
{ "match": "OK", "exact": true },
{ "match": "ACK", "exact": false },
{ "match": "NACK", "exact": false },
{ "match": "ERROR", "exact": false },
],
eventNameStrip: [':','?','=']
});
mySerialHandler.connect({deviceUrl: 'serial:///dev/ttyUSB0?baudrate=19200', writeDelay: 50 },
function() {
mySerialHandler.write('ATI\r');
mySerialHandler.on('ati', function(stream) {
// stream is passed in here as an array of lines, the first line
// being the 'ATI' command, the last being the 'OK' or 'ERROR'
// that triggered the buffer flush.
console.log(JSON.stringify(stream));
});
}
);