1. Introduction

MB2HAL is a generic non-realtime HAL component to communicate with one or more Modbus devices. So far, there are two options to communicate with a Modbus device:

  1. One option is to create a HAL component as a driver see VFD Modbus.

  2. Another option is to use Classic Ladder which has Modbus built in, see ClassicLadder.

  3. Now there is a third option that consists of a "generic" driver configured by text file, this is called MB2HAL.

Why MB2HAL? Consider using MB2HAL if:

  • You have to write a new driver and you don’t know anything about programming.

  • You need to use Classic Ladder "only" to manage the Modbus connections.

  • You have to discover and configure first time the Modbus transactions. MB2HAL have debug levels to facilitate the low level protocol debug.

  • You have more than one device to connect. MB2HAL is very efficiently managing multiple devices, transactions and links. Currently I am monitoring two axis drivers using a Rs232 port, a VFD driver using another Rs232 port, and a remote I/O using TCP/IP.

  • You want a protocol to connect your Arduino to HAL. Look the included sample configuration file, sketch and library for Arduino Modbus.

2. Usage

  1. Create a config file from the example below

    1. Set component name (optional)

      Set HAL_MODULE_NAME=mymodule (default HAL_MODULE_NAME=mb2hal)

    2. Load the modbus HAL non-realtime component

  2. Default component name: loadusr -W mb2hal config=config_file.ini

  3. Custom component name: loadusr -Wn mymodule mb2hal config=config_file.ini

3. Options

3.1. Init Section

[MB2HAL_INIT]

Value Type Required Description

INIT_DEBUG

Integer

No

Debug level of init and INI file parsing.
0 = silent
1 = error messages (default)
2 = OK confirmation messages
3 = debugging messages
4 = maximum debugging messages (only in transactions)

VERSION

String

No

Version number in the format N.N[NN]. Defaults to 1.0.

HAL_MODULE_NAME

String

No

HAL module (component) name. Defaults to "mb2hal".

SLOWDOWN

Float

No

Insert a delay of "FLOAT seconds" between transactions in order to not to have a lot of logging and facilitate the debugging. Useful when using DEBUG=3 (NOT INIT_DEBUG=3). It affects ALL transactions. Use "0.0" for normal activity.

TOTAL_TRANSACTIONS

Integer

Yes

The number of total Modbus transactions. There is no maximum.

3.2. Transaction Sections

One transaction section is required per transaction, starting at [TRANSACTION_00] and counting up sequentially. If there is a new link (not transaction), you must provide the REQUIRED parameters 1st time. Warning: Any OPTIONAL parameter not specified are copied from the previous transaction.

Value Type Required Description

LINK_TYPE

String

Yes

You must specify either a "serial" or "tcp" link for the first transaction. Later transactions will use the previous transaction link if not specified.

TCP_IP

IP address

If LINK_TYPE=tcp

The Modbus slave device IP address. Ignored if LINK_TYPE=serial.

TCP_PORT

Integer

No

The Modbus slave device TCP port. Defaults to 502. Ignored if LINK_TYPE=serial.

SERIAL_PORT

String

If LINK_TYPE=serial

The serial port. For example "/dev/ttyS0". Ignored if LINK_TYPE=tcp.

SERIAL_BAUD

Integer

If LINK_TYPE=serial

The baud rate. Ignored if LINK_TYPE=tcp.

SERIAL_BITS

Integer

If LINK_TYPE=serial

Data bits. One of 5, 6, 7, 8. Ignored if LINK_TYPE=tcp.

SERIAL_PARITY

String

If LINK_TYPE=serial

Data parity. One of: even, odd, none. Ignored if LINK_TYPE=tcp.

SERIAL_STOP

Integer

If LINK_TYPE=serial

Stop bits. One of 1, 2. Ignored if LINK_TYPE=tcp.

SERIAL_DELAY_MS

Integer

If LINK_TYPE=serial

Serial port delay between transactions of this section only. In ms. Defaults to 0. Ignored if LINK_TYPE=tcp.

MB_SLAVE_ID

Integer

Yes

Modbus slave number.

FIRST_ELEMENT

Integer

Yes

The first element address.

NELEMENTS

Integer

Unless PIN_NAMES is specified

The number of elements. It is an error to specify both NELEMENTS and PIN_NAMES. The pin names will be sequential numbers, e.g. mb2hal.plcin.01.

PIN_NAMES

List

Unless NELEMENTS is specified

A list of element names. These names will be used for the pin names, e.g. mb2hal.plcin.cycle_start.
NOTE: There must be no white space characters in the list. Example: PIN_NAMES=cycle_start,stop,feed_hold

MB_TX_CODE

String

Yes

Modbus transaction function code (see specifications):

• fnct_01_read_coils
• fnct_02_read_discrete_inputs
• fnct_03_read_holding_registers
• fnct_04_read_input_registers
• fnct_05_write_single_coil
• fnct_06_write_single_register
• fnct_15_write_multiple_coils
• fnct_16_write_multiple_registers

MB_RESPONSE_TIMEOUT_MS

Integer

No

Response timeout for this transaction. In ms. Defaults to 500 ms. This is how much to wait for 1st byte before raise an error.

MB_BYTE_TIMEOUT_MS

Integer

No

Byte timeout for this transaction. In ms. Defaults to 500 ms. This is how much to wait from byte to byte before raise an error.

HAL_TX_NAME

String

No

Instead of giving the transaction number, use a name. Example: mb2hal.00.01 could become mb2hal.plcin.01. The name must not exceed 28 characters. NOTE: when using names be careful that you don’t end up with two transactions using the same name.

MAX_UPDATE_RATE

Float

No

Maximum update rate in Hz. Defaults to 0.0 (0.0 = as soon as available = infinite). NOTE: This is a maximum rate and the actual rate may be lower. If you want to calculate it in ms use (1000 / required_ms). Example: 100 ms = MAX_UPDATE_RATE=10.0, because 1000.0 ms / 100.0 ms = 10.0 Hz.

DEBUG

String

No

Debug level for this transaction only. See INIT_DEBUG parameter above.

3.3. Error codes

While debugging transactions, note the returned "ret[]" value correspond to:

Modbus protocol exceptions:

  • 0x01 - ILLEGAL_FUNCTION - the FUNCTION code received in the query is not allowed or invalid.

  • 0x02 - ILLEGAL_DATA_ADDRESS - the DATA ADDRESS received in the query is not an allowable address for the slave or is invalid.

  • 0x03 - ILLEGAL_DATA_VALUE - a VALUE contained in the data query field is not an allowable value or is invalid.

  • 0x04 - SLAVE_DEVICE_FAILURE - SLAVE (or MASTER) device unrecoverable FAILURE while attempting to perform the requested action.

  • 0x04 - SERVER_FAILURE - (see above).

  • 0x05 - ACKNOWLEDGE - This response is returned to PREVENT A TIMEOUT in the master. A long duration of time is required to process the request in the slave.

  • 0x06 - SLAVE_DEVICE_BUSY - The slave (or server) is BUSY. Retransmit the request later.

  • 0x06 - SERVER_BUSY - (see above).

  • 0x07 - NEGATIVE_ACKNOWLEDGE - Unsuccessful programming request using function code 13 or 14.

  • 0x08 - MEMORY_PARITY_ERROR - SLAVE parity error in MEMORY.

  • 0x0A (-10) - GATEWAY_PROBLEM_PATH - Gateway path(s) not available.

  • 0x0B (-11) - GATEWAY_PROBLEM_TARGET - The target device failed to respond (generated by master, not slave).

Program or connection:

  • 0x0C (-12) - COMM_TIME_OUT

  • 0x0D (-13) - PORT_SOCKET_FAILURE

  • 0x0E (-14) - SELECT_FAILURE

  • 0x0F (-15) - TOO_MANY_DATAS

  • 0x10 (-16) - INVALID_CRC

  • 0x11 (-17) - INVALID_EXCEPTION_CODE

4. Example config file

Click here to download.

#This .INI file is also the HELP, MANUAL and HOW-TO file for mb2hal.

#Load the Modbus HAL userspace module as the examples below,
#change to match your own HAL_MODULE_NAME and INI file name
#Using HAL_MODULE_NAME=mb2hal or nothing (default): loadusr -W mb2hal config=config_file.ini
#Using HAL_MODULE_NAME=mymodule: loadusr -Wn mymodule mb2hal config=config_file.ini

# ++++++++++++++++++++++++
# Common section
# ++++++++++++++++++++++++
[MB2HAL_INIT]

#OPTIONAL: Debug level of init and INI file parsing.
# 0 = silent.
# 1 = error messages (default).
# 2 = OK confirmation messages.
# 3 = debugging messages.
# 4 = maximum debugging messages (only in transactions).
INIT_DEBUG=3

#OPTIONAL: Set to 1.1 to enable the new functions:
# - fnct_01_read_coils
# - fnct_05_write_single_coil
# - changed pin names (see https://linuxcnc.org/docs/2.9/html/drivers/mb2hal.html#_pins).
VERSION=1.1

#OPTIONAL: HAL module (component) name. Defaults to "mb2hal".
HAL_MODULE_NAME=mb2hal

#OPTIONAL: Insert a delay of "FLOAT seconds" between transactions in order
#to not to have a lot of logging and facilitate the debugging.
#Useful when using DEBUG=3 (NOT INIT_DEBUG=3)
#It affects ALL transactions.
#Use "0.0" for normal activity.
SLOWDOWN=0.0

#REQUIRED: The number of total Modbus transactions. There is no maximum.
TOTAL_TRANSACTIONS=9

# ++++++++++++++++++++++++
# Transactions
# ++++++++++++++++++++++++
#One transaction section is required per transaction, starting at 00 and counting up sequentially.
#If there is a new link (not transaction), you must provide the REQUIRED parameters 1st time.
#Warning: Any OPTIONAL parameter not specified are copied from the previous transaction.
[TRANSACTION_00]

#REQUIRED: You must specify either a "serial" or "tcp" link for the first transaction.
#Later transaction will use the previous transaction link if not specified.
LINK_TYPE=tcp

#if LINK_TYPE=tcp then REQUIRED (only 1st time): The Modbus slave device ip address.
#if LINK_TYPE=serial then IGNORED
TCP_IP=192.168.2.10

#if LINK_TYPE=tcp then OPTIONAL.
#if LINK_TYPE=serial then IGNORED
#The Modbus slave device tcp port. Defaults to 502.
TCP_PORT=502

#if LINK_TYPE=serial then REQUIRED (only 1st time).
#if LINK_TYPE=tcp then IGNORED
#The serial port.
SERIAL_PORT=/dev/ttyS0

#if LINK_TYPE=serial then REQUIRED (only 1st time).
#if LINK_TYPE=tcp then IGNORED
#The baud rate.
SERIAL_BAUD=115200

#if LINK_TYPE=serial then REQUIRED (only 1st time).
#if LINK_TYPE=tcp then IGNORED
#Data bits. One of 5,6,7,8.
SERIAL_BITS=8

#if LINK_TYPE=serial then REQUIRED (only 1st time).
#if LINK_TYPE=tcp then IGNORED
#Data parity. One of: even, odd, none.
SERIAL_PARITY=none

#if LINK_TYPE=serial then REQUIRED (only 1st time).
#if LINK_TYPE=tcp then IGNORED
#Stop bits. One of 1, 2.
SERIAL_STOP=2

#if LINK_TYPE=serial then OPTIONAL:
#if LINK_TYPE=tcp then IGNORED
#Serial port delay between for this transaction only.
#In ms. Defaults to 0.
SERIAL_DELAY_MS=10

#REQUIRED (only 1st time).
#Modbus slave number.
MB_SLAVE_ID=1

#REQUIRED: The first element address (decimal integer).
FIRST_ELEMENT=0

#REQUIRED unless PIN_NAMES is specified: The number of elements.
#It is an error to specify both NELEMENTS and PIN_NAMES
#The pin names will be sequential numbers e.g mb2hal.plcin.01
#NELEMENTS=4

#REQUIRED unless NELEMENTS is specified: A list of element names.
#these names will be used for the pin names, e.g mb2hal.plcin.cycle_start
#NOTE: there must be no white space characters in the list
PIN_NAMES=cycle_start,stop,feed_hold

#REQUIRED: Modbus transaction function code (see www.modbus.org specifications).
#    fnct_01_read_coils               (01 = 0x01) (new in 1.1)
#    fnct_02_read_discrete_inputs     (02 = 0x02)
#    fnct_03_read_holding_registers   (03 = 0x03)
#    fnct_04_read_input_registers     (04 = 0x04)
#    fnct_05_write_single_coil        (05 = 0x05) (new in 1.1)
#    fnct_06_write_single_register    (06 = 0x06)
#    fnct_15_write_multiple_coils     (15 = 0x0F)
#    fnct_16_write_multiple_registers (16 = 0x10)
#
# Created pins:
# fnct_01_read_coils:
# fnct_02_read_discrete_inputs:
#     mb2hal.m.n.bit     (output)
#     mb2hal.m.n.bit-inv (output)
# fnct_03_read_holding_registers:
# fnct_04_read_input_registers:
#     mb2hal.m.n.float   (output)
#     mb2hal.m.n.int     (output)
# fnct_05_write_single_coil:
#     mb2hal.m.n.bit     (input)
#         NELEMENTS needs to be 1 or PIN_NAMES must contain just one name.
# fnct_06_write_single_register:
#     mb2hal.m.n.float   (input)
#     mb2hal.m.n.int     (input)
#     NELEMENTS needs to be 1 or PIN_NAMES must contain just one name.
#     Both pin values are added and limited to 65535 (UINT16_MAX). Normally use one and let the other open (read as 0).
# fnct_15_write_multiple_coils:
#     mb2hal.m.n.bit     (input)
# fnct_16_write_multiple_registers:
#     mb2hal.m.n.float   (input)
#     mb2hal.m.n.int     (input)
#     Both pin values are added and limited to 65535 (UINT16_MAX). Normally use one and let the other open (read as 0).
#
# m = HAL_TX_NAME or transaction number if not set, n = element number (NELEMENTS) or name from PIN_NAMES
# Example: mb2hal.00.01.<type> (transaction=00, second register=01 (00 is the first one))
#          mb2hal.TxName.01.<type> (HAL_TX_NAME=TxName, second register=01 (00 is the first one))
MB_TX_CODE=fnct_03_read_holding_registers

#OPTIONAL: Response timeout for this transaction. In INTEGER ms. Defaults to 500 ms.
#This is how much to wait for 1st byte before raise an error.
MB_RESPONSE_TIMEOUT_MS=500

#OPTIONAL: Byte timeout for this transaction. In INTEGER ms. Defaults to 500 ms.
#This is how much to wait from byte to byte before raise an error.
MB_BYTE_TIMEOUT_MS=500

#OPTIONAL: Instead of giving the transaction number, use a name.
#Example: mb2hal.00.01 could become mb2hal.plcin.01
#The name must not exceed 28 characters.
#NOTE: when using names be careful that you dont end up with two transactions
#using the same name.
HAL_TX_NAME=remoteIOcfg

#OPTIONAL: Maximum update rate in HZ. Defaults to 0.0 (0.0 = as soon as available = infinite).
#NOTE: This is a maximum rate and the actual rate may be lower.
#If you want to calculate it in ms use (1000 / required_ms).
#Example: 100 ms = MAX_UPDATE_RATE=10.0, because 1000.0 ms / 100.0 ms = 10.0 Hz
MAX_UPDATE_RATE=0.0

#OPTIONAL: Debug level for this transaction only.
#See INIT_DEBUG parameter above.
DEBUG=2

#While DEBUGGING transactions note the returned "ret[]" value correspond to:
#/* Modbus protocol exceptions */
#ILLEGAL_FUNCTION        -0x01 the FUNCTION code received in the query is not allowed or invalid.
#ILLEGAL_DATA_ADDRESS    -0x02 the DATA ADDRESS received in the query is not an allowable address for the slave or is invalid.
#ILLEGAL_DATA_VALUE      -0x03 a VALUE contained in the data query field is not an allowable value or is invalid.
#SLAVE_DEVICE_FAILURE    -0x04 SLAVE (or MASTER) device unrecoverable FAILURE while attempting to perform the requested action.
#SERVER_FAILURE          -0x04 (see above).
#ACKNOWLEDGE             -0x05 This response is returned to PREVENT A TIMEOUT in the master.
#                              A long duration of time is required to process the request in the slave.
#SLAVE_DEVICE_BUSY       -0x06 The slave (or server) is BUSY. Retrasmit the request later.
#SERVER_BUSY             -0x06 (see above).
#NEGATIVE_ACKNOWLEDGE    -0x07 Unsuccessful programming request using function code 13 or 14.
#MEMORY_PARITY_ERROR     -0x08 SLAVE parity error in MEMORY.
#GATEWAY_PROBLEM_PATH    -0x0A (-10) Gateway path(s) not available.
#GATEWAY_PROBLEM_TARGET  -0x0B (-11) The target device failed to repond (generated by master, not slave).
#/* Program or connection */
#COMM_TIME_OUT           -0x0C (-12)
#PORT_SOCKET_FAILURE     -0x0D (-13)
#SELECT_FAILURE          -0x0E (-14)
#TOO_MANY_DATAS          -0x0F (-15)
#INVALID_CRC             -0x10 (-16)
#INVALID_EXCEPTION_CODE  -0x11 (-17)

[TRANSACTION_01]
MB_TX_CODE=fnct_01_read_coils
FIRST_ELEMENT=1024
NELEMENTS=24
HAL_TX_NAME=remoteIOin
MAX_UPDATE_RATE=0.0
DEBUG=1

[TRANSACTION_02]
MB_TX_CODE=fnct_02_read_discrete_inputs
FIRST_ELEMENT=1280
NELEMENTS=8
HAL_TX_NAME=readStatus
MAX_UPDATE_RATE=0.0

[TRANSACTION_03]
MB_TX_CODE=fnct_05_write_single_coil
FIRST_ELEMENT=100
NELEMENTS=1
HAL_TX_NAME=setEnableout
MAX_UPDATE_RATE=0.0

[TRANSACTION_04]
MB_TX_CODE=fnct_15_write_multiple_coils
FIRST_ELEMENT=150
NELEMENTS=10
HAL_TX_NAME=remoteIOout
MAX_UPDATE_RATE=0.0

[TRANSACTION_05]
LINK_TYPE=serial
SERIAL_PORT=/dev/ttyS0
SERIAL_BAUD=115200
SERIAL_BITS=8
SERIAL_PARITY=none
SERIAL_STOP=2
SERIAL_DELAY_MS=50
MB_SLAVE_ID=1
MB_TX_CODE=fnct_03_read_holding_registers
FIRST_ELEMENT=1
NELEMENTS=2
HAL_TX_NAME=XDrive01
MAX_UPDATE_RATE=0.0
DEBUG=1

[TRANSACTION_06]
MB_TX_CODE=fnct_04_read_input_registers
FIRST_ELEMENT=12
NELEMENTS=3
HAL_TX_NAME=XDrive02
MAX_UPDATE_RATE=10.0
DEBUG=1

[TRANSACTION_07]
MB_TX_CODE=fnct_06_write_single_register
FIRST_ELEMENT=20
NELEMENTS=1
HAL_TX_NAME=XDrive03
MAX_UPDATE_RATE=0.0
DEBUG=1

[TRANSACTION_08]
MB_TX_CODE=fnct_16_write_multiple_registers
FIRST_ELEMENT=55
NELEMENTS=8
HAL_TX_NAME=XDrive04
MAX_UPDATE_RATE=10.0
DEBUG=1

5. Pins

Note

Yellow = New in MB2HAL 1.1 (LinuxCNC 2.9) To use these new features you have to set VERSION = 1.1.

m = Value of HAL_TX_NAME if set or transaction number
n = Element number (NELEMENTS) or name from PIN_NAMES

Example:

  • mb2hal.00.01.int (TRANSACTION_00, second register)

  • mb2hal.readStatus.01.bit (HAL_TX_NAME=readStatus, first bit)

5.1. fnct_01_read_coils

  • mb2hal.m.n.bit bit out

  • mb2hal.m.n.bit-inv bit out

5.2. fnct_02_read_discrete_inputs

  • mb2hal.m.n.bit bit out

  • mb2hal.m.n.bit-inv bit out

5.3. fnct_03_read_holding_registers

  • mb2hal.m.n.float float out

  • mb2hal.m.n.int s32 out

5.4. fnct_04_read_input_registers

  • mb2hal.m.n.float float out

  • mb2hal.m.n.int s32 out

5.5. fnct_05_write_single_coil

  • mb2hal.m.n.bit bit in

NELEMENTS needs to be 1 or PIN_NAMES must contain just one name.

5.6. fnct_06_write_single_register

  • mb2hal.m.n.float float in

  • mb2hal.m.n.int s32 in

NELEMENTS needs to be 1 or PIN_NAMES must contain just one name. Both pin values are added and limited to 65535 (UINT16_MAX). Use one and let the other open (read as 0).

5.7. fnct_15_write_multiple_coils

  • mb2hal.m.n.bit bit in

5.8. fnct_16_write_multiple_registers

  • mb2hal.m.n.float float in

  • mb2hal.m.n.int s32 in

Both pin values are added and limited to 65535 (UINT16_MAX). Use one and let the other open (read as 0).