MODBUS

MODBUS transport protocol API. More...

Data Structures
struct	modbus_adu
	Frame struct used internally and for raw ADU support. More...
struct	modbus_user_callbacks
	Modbus Server User Callback structure. More...
struct	modbus_serial_param
	Modbus serial line parameter. More...
struct	modbus_server_param
	Modbus server parameter. More...
struct	modbus_raw_cb
struct	modbus_iface_param
	User parameter structure to configure Modbus interface as client or server. More...

Macros
#define	MODBUS_MBAP_LENGTH   7
	Length of MBAP Header.
#define	MODBUS_MBAP_AND_FC_LENGTH   (MODBUS_MBAP_LENGTH + 1)
	Length of MBAP Header plus function code.
#define	MODBUS_CUSTOM_FC_DEFINE(name, user_cb, user_fc, userdata)
	INTERNAL_HIDDEN.

Typedefs
typedef int(*	modbus_raw_cb_t) (const int iface, const struct modbus_adu *adu, void *user_data)
	ADU raw callback function signature.
typedef bool(*	modbus_custom_cb_t) (const int iface, const struct modbus_adu *const rx_adu, struct modbus_adu *const tx_adu, uint8_t *const excep_code, void *const user_data)
	Custom function code handler function signature.

Enumerations
enum	modbus_mode { MODBUS_MODE_RTU , MODBUS_MODE_ASCII , MODBUS_MODE_RAW }
	Modbus interface mode. More...

Functions
int	modbus_read_coils (const int iface, const uint8_t unit_id, const uint16_t start_addr, uint8_t *const coil_tbl, const uint16_t num_coils)
	Coil read (FC01)
int	modbus_read_dinputs (const int iface, const uint8_t unit_id, const uint16_t start_addr, uint8_t *const di_tbl, const uint16_t num_di)
	Read discrete inputs (FC02)
int	modbus_read_holding_regs (const int iface, const uint8_t unit_id, const uint16_t start_addr, uint16_t *const reg_buf, const uint16_t num_regs)
	Read holding registers (FC03)
int	modbus_read_input_regs (const int iface, const uint8_t unit_id, const uint16_t start_addr, uint16_t *const reg_buf, const uint16_t num_regs)
	Read input registers (FC04)
int	modbus_write_coil (const int iface, const uint8_t unit_id, const uint16_t coil_addr, const bool coil_state)
	Write single coil (FC05)
int	modbus_write_holding_reg (const int iface, const uint8_t unit_id, const uint16_t start_addr, const uint16_t reg_val)
	Write single holding register (FC06)
int	modbus_request_diagnostic (const int iface, const uint8_t unit_id, const uint16_t sfunc, const uint16_t data, uint16_t *const data_out)
	Read diagnostic (FC08)
int	modbus_write_coils (const int iface, const uint8_t unit_id, const uint16_t start_addr, uint8_t *const coil_tbl, const uint16_t num_coils)
	Write coils (FC15)
int	modbus_write_holding_regs (const int iface, const uint8_t unit_id, const uint16_t start_addr, uint16_t *const reg_buf, const uint16_t num_regs)
	Write holding registers (FC16)
int	modbus_read_holding_regs_fp (const int iface, const uint8_t unit_id, const uint16_t start_addr, float *const reg_buf, const uint16_t num_regs)
	Read floating-point holding registers (FC03)
int	modbus_write_holding_regs_fp (const int iface, const uint8_t unit_id, const uint16_t start_addr, float *const reg_buf, const uint16_t num_regs)
	Write floating-point holding registers (FC16)
int	modbus_iface_get_by_name (const char *iface_name)
	Get Modbus interface index according to interface name.
int	modbus_init_server (const int iface, struct modbus_iface_param param)
	Configure Modbus Interface as raw ADU server.
int	modbus_init_client (const int iface, struct modbus_iface_param param)
	Configure Modbus Interface as raw ADU client.
int	modbus_disable (const uint8_t iface)
	Disable Modbus Interface.
int	modbus_raw_submit_rx (const int iface, const struct modbus_adu *adu)
	Submit raw ADU.
void	modbus_raw_put_header (const struct modbus_adu *adu, uint8_t *header)
	Put MBAP header into a buffer.
void	modbus_raw_get_header (struct modbus_adu *adu, const uint8_t *header)
	Get MBAP header from a buffer.
void	modbus_raw_set_server_failure (struct modbus_adu *adu)
	Set Server Device Failure exception.
int	modbus_raw_backend_txn (const int iface, struct modbus_adu *adu)
	Use interface as backend to send and receive ADU.
int	modbus_register_user_fc (const int iface, struct modbus_custom_fc *custom_fc)
	Register a user-defined function code handler.

Modbus exception codes
#define	MODBUS_EXC_NONE   0
	No exception.
#define	MODBUS_EXC_ILLEGAL_FC   1
	Illegal function code.
#define	MODBUS_EXC_ILLEGAL_DATA_ADDR   2
	Illegal data address.
#define	MODBUS_EXC_ILLEGAL_DATA_VAL   3
	Illegal data value.
#define	MODBUS_EXC_SERVER_DEVICE_FAILURE   4
	Server device failure.
#define	MODBUS_EXC_ACK   5
	Acknowledge.
#define	MODBUS_EXC_SERVER_DEVICE_BUSY   6
	Server device busy.
#define	MODBUS_EXC_MEM_PARITY_ERROR   8
	Memory parity error.
#define	MODBUS_EXC_GW_PATH_UNAVAILABLE   10
	Gateway path unavailable.
#define	MODBUS_EXC_GW_TARGET_FAILED_TO_RESP   11
	Gateway target device failed to respond.

Detailed Description

MODBUS transport protocol API.

Macro Definition Documentation

MODBUS_CUSTOM_FC_DEFINE

#define MODBUS_CUSTOM_FC_DEFINE	(		name,
			user_cb,
			user_fc,
			userdata
	)

#include <zephyr/modbus/modbus.h>

Value:

        static struct modbus_custom_fc modbus_cfg_##name = {            \
                .cb = user_cb,                                          \
                .user_data = userdata,                                  \
                .fc = user_fc,                                          \
                .excep_code = MODBUS_EXC_NONE,                          \
        }

INTERNAL_HIDDEN.

Helper macro for initializing custom function code structs

MODBUS_EXC_ACK

#define MODBUS_EXC_ACK   5

#include <zephyr/modbus/modbus.h>

Acknowledge.

MODBUS_EXC_GW_PATH_UNAVAILABLE

#define MODBUS_EXC_GW_PATH_UNAVAILABLE   10

#include <zephyr/modbus/modbus.h>

Gateway path unavailable.

MODBUS_EXC_GW_TARGET_FAILED_TO_RESP

#define MODBUS_EXC_GW_TARGET_FAILED_TO_RESP   11

#include <zephyr/modbus/modbus.h>

Gateway target device failed to respond.

MODBUS_EXC_ILLEGAL_DATA_ADDR

#define MODBUS_EXC_ILLEGAL_DATA_ADDR   2

#include <zephyr/modbus/modbus.h>

Illegal data address.

MODBUS_EXC_ILLEGAL_DATA_VAL

#define MODBUS_EXC_ILLEGAL_DATA_VAL   3

#include <zephyr/modbus/modbus.h>

Illegal data value.

MODBUS_EXC_ILLEGAL_FC

#define MODBUS_EXC_ILLEGAL_FC   1

#include <zephyr/modbus/modbus.h>

Illegal function code.

MODBUS_EXC_MEM_PARITY_ERROR

#define MODBUS_EXC_MEM_PARITY_ERROR   8

#include <zephyr/modbus/modbus.h>

Memory parity error.

MODBUS_EXC_NONE

#define MODBUS_EXC_NONE   0

#include <zephyr/modbus/modbus.h>

No exception.

MODBUS_EXC_SERVER_DEVICE_BUSY

#define MODBUS_EXC_SERVER_DEVICE_BUSY   6

#include <zephyr/modbus/modbus.h>

Server device busy.

MODBUS_EXC_SERVER_DEVICE_FAILURE

#define MODBUS_EXC_SERVER_DEVICE_FAILURE   4

#include <zephyr/modbus/modbus.h>

Server device failure.

MODBUS_MBAP_AND_FC_LENGTH

#define MODBUS_MBAP_AND_FC_LENGTH   (MODBUS_MBAP_LENGTH + 1)

#include <zephyr/modbus/modbus.h>

Length of MBAP Header plus function code.

MODBUS_MBAP_LENGTH

#define MODBUS_MBAP_LENGTH   7

#include <zephyr/modbus/modbus.h>

Length of MBAP Header.

Typedef Documentation

modbus_custom_cb_t

typedef bool(* modbus_custom_cb_t) (const int iface, const struct modbus_adu *const rx_adu, struct modbus_adu *const tx_adu, uint8_t *const excep_code, void *const user_data)

#include <zephyr/modbus/modbus.h>

Custom function code handler function signature.

Modbus allows user defined function codes which can be used to extend the base protocol. These callbacks can also be used to implement function codes currently not supported by Zephyr's Modbus subsystem.

If an error occurs during the handling of the request, the handler should signal this by setting excep_code to a modbus exception code.

User data pointer can be used to pass state between subsequent calls to the handler.

Parameters

iface	Modbus interface index
rx_adu	Pointer to the received ADU struct
tx_adu	Pointer to the outgoing ADU struct
excep_code	Pointer to possible exception code
user_data	Pointer to user data

Return values

true	If response should be sent, false otherwise

modbus_raw_cb_t

typedef int(* modbus_raw_cb_t) (const int iface, const struct modbus_adu *adu, void *user_data)

#include <zephyr/modbus/modbus.h>

ADU raw callback function signature.

Parameters

iface	Modbus RTU interface index
adu	Pointer to the RAW ADU struct to send
user_data	Pointer to the user data

Return values

0	If transfer was successful

Enumeration Type Documentation

modbus_mode

enum modbus_mode

#include <zephyr/modbus/modbus.h>

Modbus interface mode.

Enumerator
MODBUS_MODE_RTU	Modbus over serial line RTU mode.
MODBUS_MODE_ASCII	Modbus over serial line ASCII mode.
MODBUS_MODE_RAW	Modbus raw ADU mode.

Function Documentation

modbus_disable()

int modbus_disable

(

const uint8_t

iface

)

#include <zephyr/modbus/modbus.h>

Disable Modbus Interface.

This function is called to disable Modbus interface.

Parameters

iface

Modbus interface index

Return values

0	If the function was successful

modbus_iface_get_by_name()

int modbus_iface_get_by_name

(

const char *

iface_name

)

#include <zephyr/modbus/modbus.h>

Get Modbus interface index according to interface name.

If there is more than one interface, it can be used to clearly identify interfaces in the application.

Parameters

iface_name

Modbus interface name

Return values

Modbus

interface index or negative error value.

modbus_init_client()

int modbus_init_client	(	const int	iface,
		struct modbus_iface_param	param
	)

#include <zephyr/modbus/modbus.h>

Configure Modbus Interface as raw ADU client.

Parameters

iface	Modbus RTU interface index
param	Configuration parameter of the client interface

Return values

0	If the function was successful

modbus_init_server()

int modbus_init_server	(	const int	iface,
		struct modbus_iface_param	param
	)

#include <zephyr/modbus/modbus.h>

Configure Modbus Interface as raw ADU server.

Parameters

iface	Modbus RTU interface index
param	Configuration parameter of the server interface

Return values

0	If the function was successful

modbus_raw_backend_txn()

int modbus_raw_backend_txn	(	const int	iface,
		struct modbus_adu *	adu
	)

#include <zephyr/modbus/modbus.h>

Use interface as backend to send and receive ADU.

This function overwrites ADU passed by the pointer and generates exception responses if backend interface is misconfigured or target device is unreachable.

Parameters

iface	Modbus client interface index
adu	Pointer to the RAW ADU struct

Return values

0	If transfer was successful

modbus_raw_get_header()

void modbus_raw_get_header	(	struct modbus_adu *	adu,
		const uint8_t *	header
	)

#include <zephyr/modbus/modbus.h>

Get MBAP header from a buffer.

Parameters

adu	Pointer to the RAW ADU struct
header	Pointer to the buffer containing MBAP header

modbus_raw_put_header()

void modbus_raw_put_header	(	const struct modbus_adu *	adu,
		uint8_t *	header
	)

#include <zephyr/modbus/modbus.h>

Put MBAP header into a buffer.

Parameters

adu	Pointer to the RAW ADU struct
header	Pointer to the buffer in which MBAP header will be placed.

modbus_raw_set_server_failure()

void modbus_raw_set_server_failure

(

struct modbus_adu *

adu

)

#include <zephyr/modbus/modbus.h>

Set Server Device Failure exception.

This function modifies ADU passed by the pointer.

Parameters

adu	Pointer to the RAW ADU struct

modbus_raw_submit_rx()

int modbus_raw_submit_rx	(	const int	iface,
		const struct modbus_adu *	adu
	)

#include <zephyr/modbus/modbus.h>

Submit raw ADU.

Parameters

iface	Modbus RTU interface index
adu	Pointer to the RAW ADU struct that is received

Return values

0	If transfer was successful

modbus_read_coils()

int modbus_read_coils	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		uint8_t *const	coil_tbl,
		const uint16_t	num_coils
	)

#include <zephyr/modbus/modbus.h>

Coil read (FC01)

Sends a Modbus message to read the status of coils from a server.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Coil starting address
coil_tbl	Pointer to an array of bytes containing the value of the coils read. The format is: MSB LSB B7 B6 B5 B4 B3 B2 B1 B0 ------------------------------------- coil_tbl[0] #8 #7 #1 coil_tbl[1] #16 #15 #9 : : Note that the array that will be receiving the coil values must be greater than or equal to: (num_coils - 1) / 8 + 1
num_coils	Quantity of coils to read

Return values

0	If the function was successful

modbus_read_dinputs()

int modbus_read_dinputs	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		uint8_t *const	di_tbl,
		const uint16_t	num_di
	)

#include <zephyr/modbus/modbus.h>

Read discrete inputs (FC02)

Sends a Modbus message to read the status of discrete inputs from a server.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Discrete input starting address
di_tbl	Pointer to an array that will receive the state of the discrete inputs. The format of the array is as follows: MSB LSB B7 B6 B5 B4 B3 B2 B1 B0 ------------------------------------- di_tbl[0] #8 #7 #1 di_tbl[1] #16 #15 #9 : : Note that the array that will be receiving the discrete input values must be greater than or equal to: (num_di - 1) / 8 + 1
num_di	Quantity of discrete inputs to read

Return values

0	If the function was successful

modbus_read_holding_regs()

int modbus_read_holding_regs	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		uint16_t *const	reg_buf,
		const uint16_t	num_regs
	)

#include <zephyr/modbus/modbus.h>

Read holding registers (FC03)

Sends a Modbus message to read the value of holding registers from a server.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Register starting address
reg_buf	Is a pointer to an array that will receive the current values of the holding registers from the server. The array pointed to by 'reg_buf' needs to be able to hold at least 'num_regs' entries.
num_regs	Quantity of registers to read

Return values

0	If the function was successful

modbus_read_holding_regs_fp()

int modbus_read_holding_regs_fp	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		float *const	reg_buf,
		const uint16_t	num_regs
	)

#include <zephyr/modbus/modbus.h>

Read floating-point holding registers (FC03)

Sends a Modbus message to read the value of floating-point holding registers from a server unit.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Register starting address
reg_buf	Is a pointer to an array that will receive the current values of the holding registers from the server. The array pointed to by 'reg_buf' needs to be able to hold at least 'num_regs' entries.
num_regs	Quantity of registers to read

Return values

0	If the function was successful

modbus_read_input_regs()

int modbus_read_input_regs	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		uint16_t *const	reg_buf,
		const uint16_t	num_regs
	)

#include <zephyr/modbus/modbus.h>

Read input registers (FC04)

Sends a Modbus message to read the value of input registers from a server.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Register starting address
reg_buf	Is a pointer to an array that will receive the current value of the holding registers from the server. The array pointed to by 'reg_buf' needs to be able to hold at least 'num_regs' entries.
num_regs	Quantity of registers to read

Return values

0	If the function was successful

modbus_register_user_fc()

int modbus_register_user_fc	(	const int	iface,
		struct modbus_custom_fc *	custom_fc
	)

#include <zephyr/modbus/modbus.h>

Register a user-defined function code handler.

The Modbus specification allows users to define standard function codes missing from Zephyr's Modbus implementation as well as add non-standard function codes in the ranges 65 to 72 and 100 to 110 (decimal), as per specification.

This function registers a new handler at runtime for the given function code.

Parameters

iface	Modbus client interface index
custom_fc	User defined function code and callback pair

Return values

0	on success

modbus_request_diagnostic()

int modbus_request_diagnostic	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	sfunc,
		const uint16_t	data,
		uint16_t *const	data_out
	)

#include <zephyr/modbus/modbus.h>

Read diagnostic (FC08)

Sends a Modbus message to perform a diagnostic function of a server unit.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
sfunc	Diagnostic sub-function code
data	Sub-function data
data_out	Pointer to the data value

Return values

0	If the function was successful

modbus_write_coil()

int modbus_write_coil	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	coil_addr,
		const bool	coil_state
	)

#include <zephyr/modbus/modbus.h>

Write single coil (FC05)

Sends a Modbus message to write the value of single coil to a server.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
coil_addr	Coils starting address
coil_state	Is the desired state of the coil

Return values

0	If the function was successful

modbus_write_coils()

int modbus_write_coils	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		uint8_t *const	coil_tbl,
		const uint16_t	num_coils
	)

#include <zephyr/modbus/modbus.h>

Write coils (FC15)

Sends a Modbus message to write to coils on a server unit.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Coils starting address
coil_tbl	Pointer to an array of bytes containing the value of the coils to write. The format is: MSB LSB B7 B6 B5 B4 B3 B2 B1 B0 ------------------------------------- coil_tbl[0] #8 #7 #1 coil_tbl[1] #16 #15 #9 : : Note that the array that will be receiving the coil values must be greater than or equal to: (num_coils - 1) / 8 + 1
num_coils	Quantity of coils to write

Return values

0	If the function was successful

modbus_write_holding_reg()

int modbus_write_holding_reg	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		const uint16_t	reg_val
	)

#include <zephyr/modbus/modbus.h>

Write single holding register (FC06)

Sends a Modbus message to write the value of single holding register to a server unit.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Coils starting address
reg_val	Desired value of the holding register

Return values

0	If the function was successful

modbus_write_holding_regs()

int modbus_write_holding_regs	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		uint16_t *const	reg_buf,
		const uint16_t	num_regs
	)

#include <zephyr/modbus/modbus.h>

Write holding registers (FC16)

Sends a Modbus message to write to integer holding registers to a server unit.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Register starting address
reg_buf	Is a pointer to an array containing the value of the holding registers to write. Note that the array containing the register values must be greater than or equal to 'num_regs'
num_regs	Quantity of registers to write

Return values

0	If the function was successful

modbus_write_holding_regs_fp()

int modbus_write_holding_regs_fp	(	const int	iface,
		const uint8_t	unit_id,
		const uint16_t	start_addr,
		float *const	reg_buf,
		const uint16_t	num_regs
	)

#include <zephyr/modbus/modbus.h>

Write floating-point holding registers (FC16)

Sends a Modbus message to write to floating-point holding registers to a server unit.

Parameters

iface	Modbus interface index
unit_id	Modbus unit ID of the server
start_addr	Register starting address
reg_buf	Is a pointer to an array containing the value of the holding registers to write. Note that the array containing the register values must be greater than or equal to 'num_regs'
num_regs	Quantity of registers to write

Return values

0	If the function was successful