cs-modbus
v1.1.2
Published
Modbus TCP/ASCII/RTU master for Control Solutions products
Downloads
37
Maintainers
Readme
cs-modbus
A command line utility implementing a Modbus TCP/ASCII/RTU master for node.js. This module is based on h5.modbus.
Prerequisites
Install nodejs for your platform (http://nodejs.org)
This will make the node
and npm
executables available.
Installing the utility
From a terminal window, use the command
npm install -g cs-modbus
The utility is now available as a terminal command. To see the available options, use
mb -h
.
You can list the available serial ports on your system by using the
mb -l
command.
Configuration
Configuration (for example, how the programs communicate with the target devices) can be controlled in multiple ways. These are listed in order of priority (command line options have precedence over environment variables have precedence over the config file).
Command line options
Options can be specified in the terminal when executing the utility. For available options, see mb -h'. For example:
mb read slave --port=COM1`
Reads the attached slave id using serial port COM1
Environment variables
Using environment variables allows you to set the configuration in each terminal window, so it does not have to be specified on each command. The method to set environment variables depends on your operating system. For example, on Windows you can use
set MODBUS_PORT=COM1
On Mac or Linux, you can use
export MODBUS_PORT=/dev/cu.usbserial
See mb -h
for the available environment variables
Configuration file
If neither the command line option nor environment variable is specified, the configuration stored in a local file is used (it is called config.json, in the installation folder).
Rather than editing this file directly, you can use the --save command line option, which will save the actual configuration to the config.json file. For example,
mb --port=COM2 --save
Will save COM2 as the default serial port.
Command examples
Refer to mb -h
for a full list of commands. Some examples to get you started:
Format of the config file
For advanced configuration options, you can edit the config.json file directly. It must be a properly-formatted JSON file:
{
"port" : {
"name" : "COM1",
"options" : {
"baudrate": 19200,
"rts": false,
"dtr" : false
}
},
"master" : {
"transport": {
"type": "RTU",
"slaveId" : 127,
"connection": {
"type": "serial",
"serialPort": null
}
},
"suppressTransactionErrors": true,
"retryOnException": false,
"maxConcurrentRequests": 1,
"defaultUnit": 1,
"defaultMaxRetries": 1,
"defaultTimeout": 1000
}
}
The "port" object is used to configure a serial port connection. It has the following settings:
- name the operating system name for the hardware serial port. To find the available ports, check your operating system device manager, or use the
node examples/ports.js
example program to list available ports. - options control how the port operates, and are taken from the options offered by the nodejs serialport module:
- baudrate: defaults to 9600. Should be one of: 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600, 300, 200, 150, 134, 110, 75, or 50. Custom rates as allowed by hardware is supported.
- dataBits: Data Bits, defaults to 8. Must be one of: 8, 7, 6, or 5.
- stopBits: Stop Bits, defaults to 1. Must be one of: 1 or 2.
- parity: Parity, defaults to 'none'. Must be one of: 'none', 'even', 'mark', 'odd', 'space'
The "websocket" object controls the behavior of a "websocket" type connection. It has the following settings:
- url the websocket URL to connect
- reconnection whether to reconnect automatically (true)
- reconnectionAttempts (Infinity) before giving up
- reconnectionDelay how long to initially wait before attempting a new reconnection (1000). Affected by +/- randomizationFactor, for example the default initial delay will be between 500 to 1500ms.
- reconnectionDelayMax maximum amount of time to wait between reconnections (5000). Each attempt increases the reconnection delay by 2x along with a randomization as above randomizationFactor (0.5), 0 <= randomizationFactor <= 1
- timeout connection timeout before a connect_error and connect_timeout events are emitted (20000)
The "master" object controls the behavior of the MODBUS master. It has the following options:
transport: Determines how messages will be framed and encoded for transport over the connection. rtu for (standard) MODBUS RTU, ascii for (standard) MODBUS ASCII, ip for (standard) MODBUS TCP/IP, and tunnel for (Control Solutions proprietary) tunneling of MODBUS commands over an RTU-based network. Using tunnel allows cs-modbus to act like a master, even as it participates on the physical network as a slave. This setting requires the 'real' MODBUS master to implement SLAVE_COMMAND polling, as defined in CS document DOC0003824A-SRS-A ** slaveId is only used for the tunnel transport; it defines the slave address that cs-modbus will monitor for SLAVE_COMMAND messages. ** eofTimeout: the timeout in milliseconds used to detect the end-of-frame in RTU and tunnel connections. These transports do not have an explicit end of message indicator; it is provided by measuring idle time on the bus. This value should be at least 3.5 character times, at the chosen baud rate. For example, at 19200 this value should be about 20. ** connection defines the physical connection that will be used to communicate with the MODBUS network. *** type: The types of supported connections are: tcp, udp, serial. *** serialPort: (required for serial connections). Set to an instance of the node-serialport module. *** TCP and UDP connections require additional parameters that are not detailed here; refer to lib/connnections/TcpConnection.js and lib/connections/UdpConnection.js for additional details.
suppressTransactionErrors: (boolean) determines whether errors detected at the transaction level will throw exceptions (which must be caught by the application code) or not.
retryOnException: (boolean) determines whether the master will retry the message if the slave returns an exception code, or simply fail the message.
maxConcurrentRequests: (integer) determines how many transactions may be attempted simultaneously. This should be '1' for serial connections using RTU or ASCII transport. A value of '2' provides an efficiency boost for TUNNEL transport over serial. TCP and UDP connections can support a higher number of simultaneous transactions. Note: the application may submit multiple requests to the master without concern for this maximum; additional requests will simply be queued until the connection is able to accept them.
defaultUnit: (integer): the default MODBUS unit identifier to transmit messages to. Can be overridden on a message-by-message basis.
defaultMaxRetries: (integer) the number of times to retry an unsuccessful transaction before failing it. Can be overridden on a message-by-message basis
defaultTimeout: (integer) the number of milliseconds to wait for a response from the slave. This can be tweaked to maximize performance of a given system depending on the connection speed, etc. Can be overridden on a message-by-message basis.
mb Utility
The mb utility allows simple MODBUS interactions with an attached slave. After configuring the connection, run the mb utility.
node mb -h
shows the available command line options
node mb read holding 0 3
reads three registers starting at address 0
node mb read holding 0 3 -v
reads the same three registers and outputs verbose diagnostic information, including the exact bytes transmitted and received over the link.
If the cs-modbus package is installed 'globally':
npm install csllc/cs-modbus.git -g
the mb
utility will be available at any terminal prompt, regardless of folder. In this case, it is simplest to use the environment variable configurations rather than edit the config.json file. For example:
set MODBUS_PORT=COM1
set MODBUS_SLAVE=10
set MODBUS_BAUD=19200
(notice 'set' is used on Windows platforms, 'export' is the Mac equivalent)
Using cs-modbus to build an application
Create a new folder and navigate there in a command prompt.
Add the MODBUS module to your nodejs project
npm install csllc/cs-modbus.git
If you intend to use a serial-port based MODBUS connection, you need
npm install serialport
Basic Use
Create a new file (demo.js) in your project folder and insert the following into it:
// Include the module
var modbus = require('cs-modbus');
// Include the serial port handler, and open /dev/ttyAMA0
// (replace the port name with an appropriate one for your
// system)
var SerialPort = require('serialport').SerialPort;
var serialPort = new SerialPort('/dev/ttyAMA0', {
baudRate: 9600
});
// Configure the master
// In this case we set up for MODBUS-RTU over the serial port
// we just declared.
var master = modbus.createMaster({
transport: {
type: 'rtu',
connection: {
type: 'serial',
serialPort: serialPort
}
},
});
// When the master is initialized..
master.once('connected', function()
{
// Read a set of discrete inputs from the slave device with address 1
// (the parameters of this command will depend on what
// kind of slave you are connected to)
var t1 = master.readDiscreteInputs(0x0000, 8, {
unit: 1
});
// The following hooks the transaction complete event, and prints out the result
t1.on('complete', function(err, response)
{
if (err)
{
console.error('[Error] %s', err.message);
}
else
{
console.log(response);
}
});
});
The examples or utility programs may be helpful in understanding how to interface to the library.
In order to run the examples, refer to the configuration instructions above (eg config.json)
Ports lists all of the serial ports present on the system - which may help identify the correct port to use for the connection.
Inspect USB is a straightforward approach to opening a serial port connection and querying the device's ID information (ReportSlaveId message). The various events are hooked to show the progression of a typical message.
Development
Clone or fork the repository, and edit the files to make the necessary changes.
Units tests are provided and should be updated for any code changes:
npm test
The tests include linting the code with JSHINT, running all unit tests, and producing test coverage reports.
Style
The module does not at this point use a consistent code style; please follow the convention in the file you are editing, and/or the style as enforced by JSHINT.
Test Coverage
npm test
includes generation of code coverage reports. To view them, review the build/coverage/lcov-report/index.html file.
License
This project is released under the MIT License.