Skip to main content

Modbus Helpers

Modbus helper functions provide convenient Lua APIs for sending Modbus RTU and Modbus TCP requests. These functions handle protocol framing, parameter validation, and codec-specific payload formatting.

Overview​

The Modbus helpers are split into two separate APIs for RTU and TCP protocols:

  • Modbus RTU: Functions prefixed with modbus_rtu_* include slave address in payload
  • Modbus TCP: Functions prefixed with modbus_tcp_* omit slave address (handled by MBAP header)

Both APIs support 8 standard Modbus function codes covering the most common industrial automation operations:

Function CodeOperationRTU HelperTCP Helper
0x01Read Coilsmodbus_rtu_read_coils()modbus_tcp_read_coils()
0x02Read Discrete Inputsmodbus_rtu_read_discrete_inputs()modbus_tcp_read_discrete_inputs()
0x03Read Holding Registersmodbus_rtu_read_holding_registers()modbus_tcp_read_holding_registers()
0x04Read Input Registersmodbus_rtu_read_input_registers()modbus_tcp_read_input_registers()
0x05Write Single Coilmodbus_rtu_write_single_coil()modbus_tcp_write_single_coil()
0x06Write Single Registermodbus_rtu_write_single_register()modbus_tcp_write_single_register()
0x0FWrite Multiple Coilsmodbus_rtu_write_multiple_coils()modbus_tcp_write_multiple_coils()
0x10Write Multiple Registersmodbus_rtu_write_multiple_registers()modbus_tcp_write_multiple_registers()

Multi-Connection Support​

All functions accept an optional connection_id parameter to target specific connections. If omitted, messages are sent to connection 0 (default connection).

API Reference​

Modbus RTU Functions​

modbus_rtu_read_coils(slave, start, qty, delay, connection_id) → boolean​

Read coil status (function code 0x01).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • start (number) - Starting coil address (0-65535)
  • qty (number) - Number of coils to read (1-2000)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule (channel closed or error)

modbus_rtu_read_discrete_inputs(slave, start, qty, delay, connection_id) → boolean​

Read discrete input status (function code 0x02).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • start (number) - Starting input address (0-65535)
  • qty (number) - Number of inputs to read (1-2000)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_rtu_read_holding_registers(slave, start, qty, delay, connection_id) → boolean​

Read holding register values (function code 0x03).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • start (number) - Starting register address (0-65535)
  • qty (number) - Number of registers to read (1-125)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_rtu_read_input_registers(slave, start, qty, delay, connection_id) → boolean​

Read input register values (function code 0x04).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • start (number) - Starting register address (0-65535)
  • qty (number) - Number of registers to read (1-125)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_rtu_write_single_coil(slave, addr, value, delay, connection_id) → boolean​

Write a single coil value (function code 0x05).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • addr (number) - Coil address (0-65535)
  • value (boolean) - Coil value (true = ON/0xFF00, false = OFF/0x0000)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_rtu_write_single_register(slave, addr, value, delay, connection_id) → boolean​

Write a single register value (function code 0x06).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • addr (number) - Register address (0-65535)
  • value (number) - Register value (0-65535, unsigned 16-bit)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_rtu_write_multiple_coils(slave, start, values_table, delay, connection_id) → boolean​

Write multiple coil values (function code 0x0F).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • start (number) - Starting coil address (0-65535)
  • values_table (table) - Lua array of boolean values (1-2000 elements)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

Validation:

  • Table must contain 1-2000 boolean values
  • Each value must be true or false
  • Values are packed into bytes (LSB-first) per Modbus specification

modbus_rtu_write_multiple_registers(slave, start, values_table, delay, connection_id) → boolean​

Write multiple register values (function code 0x10).

Parameters:

  • slave (number) - Slave/unit ID (1-247)
  • start (number) - Starting register address (0-65535)
  • values_table (table) - Lua array of integer values (1-125 elements)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

Validation:

  • Table must contain 1-125 integer values
  • Each value must be in range 0-65535 (unsigned 16-bit)
  • Values are encoded as big-endian u16

Modbus TCP Functions​

modbus_tcp_read_coils(start, qty, delay, connection_id) → boolean​

Read coil status (function code 0x01).

Parameters:

  • start (number) - Starting coil address (0-65535)
  • qty (number) - Number of coils to read (1-2000)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

Note: Slave/unit ID is specified in the MBAP header, not in the function parameters.

modbus_tcp_read_discrete_inputs(start, qty, delay, connection_id) → boolean​

Read discrete input status (function code 0x02).

Parameters:

  • start (number) - Starting input address (0-65535)
  • qty (number) - Number of inputs to read (1-2000)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_tcp_read_holding_registers(start, qty, delay, connection_id) → boolean​

Read holding register values (function code 0x03).

Parameters:

  • start (number) - Starting register address (0-65535)
  • qty (number) - Number of registers to read (1-125)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_tcp_read_input_registers(start, qty, delay, connection_id) → boolean​

Read input register values (function code 0x04).

Parameters:

  • start (number) - Starting register address (0-65535)
  • qty (number) - Number of registers to read (1-125)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_tcp_write_single_coil(addr, value, delay, connection_id) → boolean​

Write a single coil value (function code 0x05).

Parameters:

  • addr (number) - Coil address (0-65535)
  • value (boolean) - Coil value (true = ON/0xFF00, false = OFF/0x0000)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_tcp_write_single_register(addr, value, delay, connection_id) → boolean​

Write a single register value (function code 0x06).

Parameters:

  • addr (number) - Register address (0-65535)
  • value (number) - Register value (0-65535, unsigned 16-bit)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

modbus_tcp_write_multiple_coils(start, values_table, delay, connection_id) → boolean​

Write multiple coil values (function code 0x0F).

Parameters:

  • start (number) - Starting coil address (0-65535)
  • values_table (table) - Lua array of boolean values (1-2000 elements)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

Validation:

  • Table must contain 1-2000 boolean values
  • Each value must be true or false
  • Values are packed into bytes (LSB-first) per Modbus specification

modbus_tcp_write_multiple_registers(start, values_table, delay, connection_id) → boolean​

Write multiple register values (function code 0x10).

Parameters:

  • start (number) - Starting register address (0-65535)
  • values_table (table) - Lua array of integer values (1-125 elements)
  • delay (number) - Delay in milliseconds before sending
  • connection_id (number, optional) - Target connection ID (default: 0)

Returns:

  • true - Request scheduled successfully
  • false - Failed to schedule

Validation:

  • Table must contain 1-125 integer values
  • Each value must be in range 0-65535 (unsigned 16-bit)
  • Values are encoded as big-endian u16

Validation Errors​

All Modbus helpers perform parameter validation and return false on errors:

Common Validation Constraints:

  • Coils: Quantity must be 1-2000
  • Discrete Inputs: Quantity must be 1-2000
  • Holding Registers: Quantity must be 1-125
  • Input Registers: Quantity must be 1-125
  • Register values: Must be 0-65535 (unsigned 16-bit)
  • Coil values: Must be boolean (true/false)

See Also​