Chapter 2. API Reference
Modbus Master API Overview
The following overview describes how to setup Modbus master communication. The overview reflects a typical
programming workflow and is broken down into the sections provided below:
1. Modbus Port Initialization - Initialization of Modbus controller interface for the selected port.
2. Configuring Master Data Access - Configure data descriptors to access slave parameters.
3. Master Communication Options - Allows to setup communication options for selected port.
4. Master Communication - Start stack and sending / receiving data.
5. Modbus Master Teardown - Destroy Modbus controller and its resources.
Configuring Master Data Access The architectural approach of ESP_Modbus includes one level above standard
Modbus IO driver. The additional layer is called Modbus controller and its goal is to add an abstraction such as
CID - characteristic identifier. The CID is linked to a corresponding Modbus registers through the table called Data
Dictionary and represents device physical parameter (such as temperature, humidity, etc.) in specific Modbus slave
device. This approach allows the upper layer (e.g., MESH or MQTT) to be isolated from Modbus specifics thus
simplify Modbus integration with other protocols/networks.
The Data Dictionary is the list in the Modbus master which shall be defined by user to link each CID to its cor-
responding Modbus registers representation using Register Mapping table of the Modbus slave being used. Each
element in this data dictionary is of type mb_parameter_descriptor_t and represents the description of one
physical characteristic:
Table 7: Table 1 Modbus master Data Dictionary description
Field DescriptionDetailed information
cid Characteristic
ID
The identifier of characteristic (must be unique).
param_keyCharacteristic
Name
String description of the characteristic.
param_unitsCharacteristic
Units
Physical Units of the characteristic.
mb_slave_addrModbus
Slave
Address
The short address of the device with correspond parameter UID.
mb_param_typeModbus
Register
Type
Type of Modbus register area. MB_PARAM_INPUT, MB_PARAM_HOLDING,
MB_PARAM_COIL, MB_PARAM_DISCRETE - represents Input , Holding, Coil and
Discrete input register area accordingly;
mb_reg_startModbus
Register
Start
Relative register address of the characteristic in the register area.
mb_sizeModbus
Register
Size
Length of characteristic in registers.
param_offsetInstance
Offset
Offset to instance of the characteristic in bytes. It is used to calculate the absolute address
to the characteristic in the storage structure. It is optional field and can be set to zero if the
parameter is not used in the application.
param_typeData
Type
Specifies type of the characteristic. PARAM_TYPE_U8, PARAM_TYPE_U16,
PARAM_TYPE_U32 - Unsigned integer 8/16/32 bit type; PARAM_TYPE_FLOAT -
IEEE754 floating point format; PARAM_TYPE_ASCII - ASCII string or binary data;
param_sizeData
Size
The storage size of the characteristic (bytes).
param_optsParameter
Options
Limits, options of characteristic used during processing of alarm in user application (optional)
accessParameter
access
type
Can be used in user application to define the behavior of the characteristic dur-
ing processing of data in user application; PAR_PERMS_READ_WRITE_TRIGGER,
PAR_PERMS_READ, PAR_PERMS_READ_WRITE_TRIGGER;
Espressif Systems 624
Submit Document Feedback
Release v4.4
To Next Page
Loading...