Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS

MODBUS transport protocol API. More...

Data Structures

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

Macros

#define MODBUS_MBAP_LENGTH   7
 
#define MODBUS_MBAP_AND_FC_LENGTH   (MODBUS_MBAP_LENGTH + 1)
 

Typedefs

typedef int(* modbus_raw_cb_t) (const int iface, const struct modbus_adu *adu)
 ADU raw callback function signature. More...
 

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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
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) More...
 
int modbus_iface_get_by_name (const char *iface_name)
 Get Modbus interface index according to interface name. More...
 
int modbus_init_server (const int iface, struct modbus_iface_param param)
 Configure Modbus Interface as raw ADU server. More...
 
int modbus_init_client (const int iface, struct modbus_iface_param param)
 Configure Modbus Interface as raw ADU client. More...
 
int modbus_disable (const uint8_t iface)
 Disable Modbus Interface. More...
 
int modbus_raw_submit_rx (const int iface, const struct modbus_adu *adu)
 Submit raw ADU. More...
 
void modbus_raw_put_header (const struct modbus_adu *adu, uint8_t *header)
 Put MBAP header into a buffer. More...
 
void modbus_raw_get_header (struct modbus_adu *adu, const uint8_t *header)
 Get MBAP header from a buffer. More...
 
void modbus_raw_set_server_failure (struct modbus_adu *adu)
 Set Server Device Failure exception. More...
 
int modbus_raw_backend_txn (const int iface, struct modbus_adu *adu)
 Use interface as backend to send and receive ADU. More...
 

Detailed Description

MODBUS transport protocol API.

Macro Definition Documentation

◆ MODBUS_MBAP_AND_FC_LENGTH

#define MODBUS_MBAP_AND_FC_LENGTH   (MODBUS_MBAP_LENGTH + 1)

#include <include/modbus/modbus.h>

Length of MBAP Header plus function code

◆ MODBUS_MBAP_LENGTH

#define MODBUS_MBAP_LENGTH   7

#include <include/modbus/modbus.h>

Length of MBAP Header

Typedef Documentation

◆ modbus_raw_cb_t

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

#include <include/modbus/modbus.h>

ADU raw callback function signature.

Parameters
ifaceModbus RTU interface index
aduPointer to the RAW ADU struct to send
Return values
0If transfer was successful

Enumeration Type Documentation

◆ modbus_mode

#include <include/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 <include/modbus/modbus.h>

Disable Modbus Interface.

This function is called to disable Modbus interface.

Parameters
ifaceModbus interface index
Return values
0If the function was successful

◆ modbus_iface_get_by_name()

int modbus_iface_get_by_name ( const char *  iface_name)

#include <include/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_nameModbus interface name
Return values
Modbusinterface index or negative error value.

◆ modbus_init_client()

int modbus_init_client ( const int  iface,
struct modbus_iface_param  param 
)

#include <include/modbus/modbus.h>

Configure Modbus Interface as raw ADU client.

Parameters
ifaceModbus RTU interface index
paramConfiguration parameter of the client interface
Return values
0If the function was successful

◆ modbus_init_server()

int modbus_init_server ( const int  iface,
struct modbus_iface_param  param 
)

#include <include/modbus/modbus.h>

Configure Modbus Interface as raw ADU server.

Parameters
ifaceModbus RTU interface index
paramConfiguration parameter of the server interface
Return values
0If the function was successful

◆ modbus_raw_backend_txn()

int modbus_raw_backend_txn ( const int  iface,
struct modbus_adu adu 
)

#include <include/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
ifaceModbus client interface index
aduPointer to the RAW ADU struct
Return values
0If transfer was successful

◆ modbus_raw_get_header()

void modbus_raw_get_header ( struct modbus_adu adu,
const uint8_t header 
)

#include <include/modbus/modbus.h>

Get MBAP header from a buffer.

Parameters
aduPointer to the RAW ADU struct
headerPointer to the buffer containing MBAP header
Return values
0If transfer was successful

◆ modbus_raw_put_header()

void modbus_raw_put_header ( const struct modbus_adu adu,
uint8_t header 
)

#include <include/modbus/modbus.h>

Put MBAP header into a buffer.

Parameters
aduPointer to the RAW ADU struct
headerPointer to the buffer in which MBAP header will be placed.
Return values
0If transfer was successful

◆ modbus_raw_set_server_failure()

void modbus_raw_set_server_failure ( struct modbus_adu adu)

#include <include/modbus/modbus.h>

Set Server Device Failure exception.

This function modifies ADU passed by the pointer.

Parameters
aduPointer to the RAW ADU struct

◆ modbus_raw_submit_rx()

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

#include <include/modbus/modbus.h>

Submit raw ADU.

Parameters
ifaceModbus RTU interface index
aduPointer to the RAW ADU struct that is received
Return values
0If 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 <include/modbus/modbus.h>

Coil read (FC01)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrCoil starting address
coil_tblPointer 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_coilsQuantity of coils to read
Return values
0If 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 <include/modbus/modbus.h>

Read discrete inputs (FC02)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrDiscrete input starting address
di_tblPointer 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_diQuantity of discrete inputs to read
Return values
0If 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 <include/modbus/modbus.h>

Read holding registers (FC03)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrRegister starting address
reg_bufIs 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_regsQuantity of registers to read
Return values
0If 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 <include/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
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrRegister starting address
reg_bufIs 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_regsQuantity of registers to read
Return values
0If 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 <include/modbus/modbus.h>

Read input registers (FC04)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrRegister starting address
reg_bufIs 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_regsQuantity of registers to read
Return values
0If the function was successful

◆ 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 <include/modbus/modbus.h>

Read diagnostic (FC08)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
sfuncDiagnostic sub-function code
dataSub-function data
data_outPointer to the data value
Return values
0If 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 <include/modbus/modbus.h>

Write single coil (FC05)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
coil_addrCoils starting address
coil_stateIs the desired state of the coil
Return values
0If 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 <include/modbus/modbus.h>

Write coils (FC15)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrCoils starting address
coil_tblPointer 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_coilsQuantity of coils to write
Return values
0If 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 <include/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
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrCoils starting address
reg_valDesired value of the holding register
Return values
0If 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 <include/modbus/modbus.h>

Write holding registers (FC16)

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

Parameters
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrRegister starting address
reg_bufIs 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_regsQuantity of registers to write
Return values
0If 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 <include/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
ifaceModbus interface index
unit_idModbus unit ID of the server
start_addrRegister starting address
reg_bufIs 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_regsQuantity of registers to write
Return values
0If the function was successful