Module modbus

Implementation of modbus RTU, ASCII master.

This module relies on the serial#serial module to handle port 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/decode such strings, it is suggested to rely on pack, the binary string packing library.

Type modbus

modbus.new(port, cfg, mode)

Creates a new #modbusdev.

Type modbusdev

modbusdev:close()

Closes a modbus instance.
modbusdev:customRequest(req, sid, payload)

Send a custom MODBUS request, not directly supported by the API.
modbusdev:readCoils(sid, address, length)

Read a sequence of consecutive coils' content.
modbusdev:readDiscreteInputs(sid, address, length)

Read a sequence of consecutive discrete inputs' content.
modbusdev:readHoldingRegisters(sid, address, length)

Read a sequence of consecutive holding registers' content.
modbusdev:readInputRegisters(sid, address, length)

Read a sequence of consecutive input registers' content.
modbusdev:writeMultipleCoils(sid, address, nbvalues, values)

Write a sequence of consecutive coils.
modbusdev:writeMultipleRegisters(sid, address, values)

Write a sequence of consecutive registers.
modbusdev:writeSingleCoil(sid, address, value)

Write a value in a coil.
modbusdev:writeSingleRegister(sid, address, value)

Write a value in a register.

Type modbus

Field(s)

modbus.new(port, cfg, mode)

Creates a new #modbusdev.

Default initialization is "/dev/ttyS0", 115200, "none", "RTU", 10

Parameters

  • port : the serial port on which modbus operates. As for serial#serial.open, it can be given as a port number, or as a file path (POSIX operating systems only). Defaults to port 0, i.e. "/dev/ttyS0" on POSIX.

  • cfg : an optional serial device config table, see serial#serial.config for details on accepted fields.
    Same default values as in serial#serial.open. An additional field 'timeout' can be put in cfg as an integer to configure modbus timeout in seconds.

  • mode : serial mode as a string: "ASCII" or "RTU".
    Defaults to "RTU".

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, sid, payload)

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

Parameters

  • req : number identifying the custom function

  • 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(sid, address, length)

Read a sequence of consecutive coils' content.

Parameters

  • 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 string buffer

  2. nil + error message

Usage:

 local m = modbus.new('/dev/ttyS0')
 local data = m:readCoils(1, 40, 1)
 local _, bool = string.unpack(data,"x8")
modbusdev:readDiscreteInputs(sid, address, length)

Read a sequence of consecutive discrete inputs' content.

Parameters

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

  • address : starting address

  • length : number of inputs

Return values

  1. read discrete inputs content in a string buffer

  2. nil + error message

Usage:

 local m = modbus.new('/dev/ttyS0')
 local data = m:readDiscreteInputs(1, 40, 1)
 local _, bool = string.unpack(data,"x8")
modbusdev:readHoldingRegisters(sid, address, length)

Read a sequence of consecutive holding registers' content.

Parameters

  • 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 string buffer

  2. nil + error message

Usage:

 local m = modbus.new('/dev/ttyS0')
 local data = m:readHoldingRegisters(1, 40, 1)
 local _, value = string.unpack(data,"<H")
modbusdev:readInputRegisters(sid, address, length)

Read a sequence of consecutive input registers' content.

Parameters

  • 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 string buffer

  2. nil + error message

Usage:

 local m = modbus.new('/dev/ttyS0')
 local data = m:readInputRegisters(1, 40, 1)
 local _, value = string.unpack(data,"<H")
modbusdev:writeMultipleCoils(sid, address, nbvalues, values)

Write a sequence of consecutive coils.

Parameters

  • 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 coils per byte)

Return values

  1. "ok"

  2. nil + error message

Usage:

 local m = modbus.new('/dev/ttyS0')
 local res, err = m:writeMultipleCoils(1, 0, 8, string.pack('x8',
 true,false,false,true,false,true,false,true))
modbusdev:writeMultipleRegisters(sid, address, values)

Write a sequence of consecutive registers.

Parameters

  • 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:

 local m = modbus.new('/dev/ttyS0')
 local res, err = m:writeMultipleRegisters(1, 90, string.pack("<H8",21,159,357,654,852,
 357,654,852))
modbusdev:writeSingleCoil(sid, address, value)

Write a value in a coil.

Parameters

  • 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

Usage:

 local m = modbus.new('/dev/ttyS0')
 local res, err = m:writeSingleCoil(1, 0, true)
modbusdev:writeSingleRegister(sid, address, value)

Write a value in a register.

Parameters

  • 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

Usage:

 local m = modbus.new('/dev/ttyS0')
 local res, err = m:writeSingleRegister(1, 0, 60)