Module modbustcp

Implementation of modbus TCP, TCP/RTU and TCP/ASCII.

This module relies on the socket#socket module to handle socket configuration and actual data exchanges.

Data read and written by this module are exchanged as buffers, i.e. either strings or lists of strings. String(s) contain data as 8-bits bytes; endianness depends on what is expected/returned by the slave device. To encode such strings, it is suggested to rely on pack#pack, the binary string packing library.

Type config

config.maxsocket	to set the maximum number of socket in use. accepted value is a stricly positive integer.
config.timeout	to configure the socket timeout, in seconds. accepted value is a stricly positive integer.

Type modbus

modbus.new(cfg, mode)

Creates a new #modbusdev.

Type modbusdev

modbusdev:close()	Closes a modbus instance.
modbusdev:customRequest(req, host, port, sid, payload)	Send a custom MODBUS request, not directly supported by the API.
modbusdev:readCoils(host, port, sid, address, length)	Read a sequence of consecutive coils' content.
modbusdev:readDiscreteInputs(host, port, sid, address, length)	Read a sequence of consecutive discrete inputs' content.
modbusdev:readHoldingRegisters(host, port, sid, address, length)	Read a sequence of consecutive holding registers' content.
modbusdev:readInputRegisters(host, port, sid, address, length)	Read a sequence of consecutive input registers' content.
modbusdev:writeMultipleCoils(host, port, sid, address, nbvalues, values)	Write a sequence of consecutive coils.
modbusdev:writeMultipleRegisters(host, port, sid, address, values)	Write a sequence of consecutive registers.
modbusdev:writeSingleCoil(host, port, sid, address, value)	Write a value in a coil.
modbusdev:writeSingleRegister(host, port, sid, address, value)	Write a value in a register.

Type modbustcp

Type config

Modbus configuration table.

Field(s)

config.maxsocket

to set the maximum number of socket in use. accepted value is a stricly positive integer.

config.timeout

to configure the socket timeout, in seconds. accepted value is a stricly positive integer.

Type modbus

Field(s)

modbus.new(cfg, mode)

Creates a new #modbusdev.

Default initialization is TCP

Parameters

• cfg : an optional #config table. Default values are { maxsocket = 1, timeout = 1 }

• mode : tcp mode as a string: "TCP", "ASCII" or "RTU".
  Defaults to "TCP".

Return values

1. #modbusdev: the new #modbusdev on success

2. nil + error message

Type modbusdev

Field(s)

modbusdev:close()

Closes a modbus instance.

Return value

"ok"

modbusdev:customRequest(req, host, port, sid, payload)

Send a custom MODBUS request, not directly supported by the API.

Parameters

• req : number identifying the custom function

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : slave id

• payload : optional data bytes to send, as a string

Return values

1. the response as a buffer. Beware, it contains some error-checking bytes as a suffix.

2. nil + error message.

modbusdev:readCoils(host, port, sid, address, length)

Read a sequence of consecutive coils' content.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : starting address

• length : number of coils

Return values

1. read coil values in a buffer

2. nil + error message

modbusdev:readDiscreteInputs(host, port, sid, address, length)

Read a sequence of consecutive discrete inputs' content.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : starting address

• length : number of inputs

Return values

1. read discrete inputs contant in a buffer

2. nil + error message

modbusdev:readHoldingRegisters(host, port, sid, address, length)

Read a sequence of consecutive holding registers' content.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : starting address

• length : number of registers

Return values

1. read holding registers content in a buffer

2. nil + error message

modbusdev:readInputRegisters(host, port, sid, address, length)

Read a sequence of consecutive input registers' content.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : starting address

• length : number of inputs

Return values

1. read input registers content in a buffer

2. nil + error message

modbusdev:writeMultipleCoils(host, port, sid, address, nbvalues, values)

Write a sequence of consecutive coils.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : starting address

• nbvalues : number of coils to write

• values : values to write, as a bytes buffer (8 coil per byte)

Return values

1. "ok"

2. nil + error message

Usage:

 m = modbustcp.new()
 res,err=m:writeMultipleCoils('10.41.51.50', 502, 1, 0, 8, string.pack('x8',
 true,false,false,true,false,true,false,true)

modbusdev:writeMultipleRegisters(host, port, sid, address, values)

Write a sequence of consecutive registers.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : starting address

• values : values to write, as a word buffer (each register is a 16bits word)

Return values

1. "ok"

2. nil + error message

Usage:

 m = modbustcp.new()
 res,err=m:writeMultipleRegisters('10.41.51.50', 502, 1, 0, string.pack("<H8",21,159,357,654,852,
 357,654,852))

modbusdev:writeSingleCoil(host, port, sid, address, value)

Write a value in a coil.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : address of the coil

• value : Boolean to write in the coil

Return values

1. "ok"

2. nil + error message

modbusdev:writeSingleRegister(host, port, sid, address, value)

Write a value in a register.

Parameters

• host : ip address or resolvable hostname of server

• port : port number of server, defaults to port 502

• sid : number defining the slave id to send the request to

• address : address of the coil

• value : Short integer ([0..0xFFFF]) to write in the register

Return values

1. "ok"

2. nil + error message