Ruff 0.9.0 Documentation
Table of Contents
UART#
The uart
module allows you to create your own device driver with UART output. Following line of code includes the UART module: require('uart')
.
UART driver developers may extend this module by adding more functions.
Create UART driver#
With Ruff Framework, your UART driver for a specific device probably looks like this:
var MyUart = Uart.driver({
attach: function(inputs, uv, uart) {
...
},
detach: function() {
...
},
getDevice: function(key, inputs) {
...
return this; // this line is necessary
},
exports: {
setup: function(options) {
...
},
read: function(callback) {
...
},
readSync: function(length, timeout) {
...
},
write: function(data, callback) {
...
},
writeSync: function(data) {
...
}
}
});
Export UART resource in your driver#
Driver developers should export UART resource in driver.json
. Note, minBaudRate
and maxBaudRate
fields are required.
For example:
{
"inputs": {
"device": {
"type": "string",
"args": {
"minBaudRate": {
"type": "number",
"default": 0
},
"maxBaudRate": {
"type": "number",
"default": 57600
}
}
}
},
"outputs": {
"uart": {
"type": "uart"
}
}
}
Use UART interface#
Driver developers should refer the datasheet of device and create a corresponding description file named by driver.json
.
Now suppose we have device called "foobar", it can be used to store and fetch a singel character. Moreover, "foobar" has two models, both of them provide an UART port with baudrate 19200, stop bits 1, data bits 8, no parity, no flow control.
Based the abovementioned information, the driver.json
for "foobar" probably looks like this:
{
"models": [
"foobar-model1",
"foobar-model2"
],
"inputs": {
"uart": {
"type": "uart",
"args": {
"baudRate": "19200",
"stopBits": "1",
"dataBits": "8",
"parity": "none",
"flowControl": "none"
}
}
}
}
Its implementation src/index.js
probably looks like this:
var driver = require('ruff-driver');
var TIMEOUT = 200 // milliseconds
module.exports = driver({
attach: function (inputs) {
this._uart = inputs.getRequired('uart');
},
detach: function () {
},
exports: {
storeChar: function (ch) {
var cmd = new Buffer('w' + ch);
this._uart.writeSync(cmd);
},
fetchChar: function (ch) {
var cmd = new Buffer('r');
this._uart.writeSync(cmd);
var resp = this._uart.readSync(1, TIMEOUT);
var ch = (resp.length === 1) ? resp[0] : null;
return ch;
}
}
});
API#
uart.setup(options)#
Setup communication parameters. The options
should be an object composed with five properies, i.e. baudRate
, stopBits
, dataBits
, parity
, flowControl
.
baudRate
: Baud rate. The available values are listed as follows:
0
50
75
110
134
150
200
300
600
1200
1800
2400
4800
9600
19200
38400
57600
115200
230400
stopBits
: Stop bits sent at the end of every character allow the receiving signal hardware to detect the end of a character and to resynchronise with the character stream. The available values are listed as follows:
1
(most common setting)2
dataBits
: Data bits is number of data bits in each character. The available values are listed as follows:
5
6
7
8
(most common setting)
parity
: Parity is a method of detecting errors in transmission. The available values are listed as follows:
'none'
'odd'
'even'
flowControl
: Flow control. A serial port may use signals in the interface to pause and resume the transmission of data. The available values are listed as follows:
'none'
'hardware'
'software'
Example:
uart.setup({
baudRate: 57600,
stopBits: 1,
dataBits: 8,
parity: 'even',
flowControl: 'none'
});
uart.read(callback)#
Read data in async mode. When data arrives or error occurs, the callback
will be invoked with two parameters: error
and data
. User should check whether error
is null before any data manipulation. The type of data
is a buffer.
Example:
uart.read(function(err, data) {
if (err) {
console.log(err)
return;
}
console.log(data);
});
uart.readSync(length, timeout)#
Read data in sync mode. Parameter length
is in bytes, timeout
is in millisecond, up to 25500 milliseconds (i.e. 25.5 seconds) is supported. The return type of this method is a buffer.
Example:
var data = uart.readSync(length, timeout);
console.log('data:', data);
uart.write(data, callback)#
Write data in async mode. The type of data should be either string or buffer. When the writing is finished, the corresponding callback
will be invoked with one parameter: error
. User should check whether error
is null to determine whether an error was occured while writing.
Example:
uart.write('hello', function(err) {
if (err) {
console.log(err);
return;
}
console.log('write success');
});
uart.writeSync(data)#
Write data in sync mode. The type of data should be either string or buffer.
Example:
var data = new Buffer('0xdeadbeef', 'hex');
uart.writeSync(data);