Ruff 1.0.0 Documentation


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);