Skip to content

Latest commit

 

History

History
162 lines (104 loc) · 5.75 KB

API.md

File metadata and controls

162 lines (104 loc) · 5.75 KB
Raw

API

var mb = require('modbus-stack')

The main module for node-modbus-stack contains the low-level StreamStack subclasses: ModbusRequestStack and ModbusResponseStack, as well as various contansts related to the protocol.

mb.FUNCTION_CODES

An Object containing the defined Modbus "Function Codes", with keys in a human-readable format, intended to be used in place of the actual number of the function code in your code.

mb.FUNCTION_CODES.READ_COILS;
  // returns 1
mb.FUNCTION_CODES.READ_INPUT_REGISTERS;
  // returns 4

mb.EXCEPTION_CODES

An Object containing the defined Modbus "Exception Codes", which are used by a Slave (server) in the case of an exception occuring during execution of a Function Code request.

mb.EXCEPTION_CODES.ILLEGAL_FUNCTION;
  // returns 1

var req = new mb.ModbusRequestStack(stream)

A StreamStack subclass that handles the client-side (Master) of the Modbus protocol.

ModbusRequestStack is a low-level API for Modbus requests. It is only good for 1 single request/response interaction.

It's recommended to use mbc.createClient() for a high-level TCP-based Client API.

var socket = require('net').createConnection(502);
var req = new mb.ModbusRequestStack(socket);

req.request(functionCode, [arg1, arg2, arg3, ...], [callback])

Invokes a Modbus request on the parent Stream. "functionCode" must be the Function Code that you are invoking. The (sometimes optional) "arg" arguments are specific to the Function Code being invoked. "callback" can be an optional callback Function to invoke when either an "error" or "response" occur.

req.request(mb.FUNCTION_CODES.READ_COILS, 0, 5, function(err, res) {
  if (err) throw err;
  console.log(res);
    // [ true, false, true, false, true, true ]
});

Event: 'response'

function(response) { }

Emitted after the response has been received and parsed. "response" is an Object with properties dependant on the Function Code that was invoked. In some cases, an Array instance is returned with the return values.

Event: 'error'

function(error) { }

Emitted if the remote Modbus Slave responds with an Exception Code, rather than a successful response.

var res = new mb.ModbusResponseStack(stream)

A StreamStack subclass that handles the server-side (Slave) of the Modbus protocol.

ModbusResponseStack is a low-level API for handling Modbus requests and returning proper responses, or exceptions. It is only good for 1 single request/response interaction.

It's recommended to use mbs.createServer() for a simpler, high-level API for writing a Modbus-compliant server.

require('net').createServer(function(socket) {
  var res = new mb.ModbusResponseStack(socket);
}).listen(502);

res.writeResponse([arg1, arg2, ...])

Writes out a Modbus response after a request event has been received. The arguments passed are dependant on the Function Code being requested. Sometimes, no arguments are necessary.

var results = [4, 0, 5, 10, 2];
res.writeResponse(results);

res.writeException(exceptionCode)

Writes out a Modbus exception response after a request event has been received. "exceptionCode" must be the Exception Code you would like to return to the Master.

Event: 'request'

function(request) { }

Emitted after a Modbus request has been received and parsed. "request" is an object containing:

  • functionCode - The "Function Code" being requested.
  • transactionId - The transaction ID. Usually starts at 0 and increments by 1 for each subsequent request on a particular socket.
  • protocolVersion - The version of the Modbus protocol. This is always 0 for "Modbus/TCP".
  • unitIdentifier - The unit ID. To identify which Modbus slave to talk to. This is normally only used for serial-line Modbus, but can be useful if implementing a TCP->Serial Modbus bridge.

As well as any additional parameters relating to the Function Code being requested.

var mbc = require('modbus-stack/client')

mbc.createClient(port, [host])

Creates and return a new Client instance, which is the preferred method of MODBUS master communication over TCP. The default MODBUS port is 502. mbc.Client is a subclass of net.Socket.

var client = mbc.createClient(502, '192.168.0.1')

client.request(functionCode, [arg1, arg2, arg3, ...], [callback])

Makes a MODBUS request to the remote MODBUS slave. Same as ModusRequestStack#request(). Returns a new instance of ModbusRequestStack.

mbc.REQUESTS

An Object containing the individual handlers for each implemented Function Code, from the perspective of a Client making a Modbus request.

mbc.RESPONSES

An Object containing the individual handlers for each implemented Function Code, from the perspective of a Client receiving the response after a request.

var mbs = require('modbus-stack/server')

mbs.createServer(handlers)

Creates and returns a new Server instance, which is the preferred method of MODBUS Slave communication over TCP. handlers should be an Object with handlers for each individual Function Code your server will handle. Any Function Code requests received that doesn't have handler defined will have an Exception Code "Illegal Function" response. Or, handlers may be a single Function instance which is called for all Function Codes. Your handler function should manually call writeException() for any Function Codes you don't care about.

mbs.REQUESTS

An Object containing the individual handlers for each implemented Function Code, from the perspective of a Server receiving a request.

mbs.RESPONSES

An Object containing the individual handlers for each implemented Function Code, from the perspective of a Server responding to a previous request.