ESP-Modbus Library

This example demonstrates how to use the FreeModbus stack port implementation on ESP32-based devices to act as a Modbus Master.

As a master, the device can read and write values from slave devices connected to a Modbus segment. The example uses a data dictionary to map characteristics (names and Characteristic IDs/CIDs) to specific registers on the slave devices. It also implements a simple control algorithm: if a specific parameter (e.g., holding_data0) exceeds a limit, the master triggers an alarm (e.g., activating a relay on the slave device).

Key Concepts:

• Characteristics: Data points identified by a name and a CID (e.g., Temperature_1 with CID_INP_DATA_1).
• Data Dictionary: A mapping used by the master to know which CIDs to poll from which slave addresses.
• Multi-slave segments: The master can communicate with multiple slaves by addressing different MB_DEVICE_ADDR values.

The ESP-Modbus library supports the standard communication options defined by the Modbus specification. These include RTU, ASCII, and TCP/IP variants. Note that if a specific vendor uses a subset of these options, you can override the standard settings using the master or slave setup APIs.

RTU Communication

• 1 start bit
• 8 data bits (LSB first)
• 1 bit for even/odd parity (or no bit for no parity)
• 1 stop bit if parity is used; 2 stop bits if no parity
• Uses Cyclical Redundancy Check (CRC)

ASCII Communication

• 1 start bit
• 7-8 data bits (LSB first)
• 1 bit for even/odd parity (or no bit for no parity)
• 1 stop bit if parity is used; 2 stop bits if no parity
• Uses Longitudinal Redundancy Check (LRC)

TCP Communication

• Client (master) - server (slave) communication over TCP/IP networks
• Uses standard port 502
• No checksum calculation required (handled by lower layers)

The ESP-Modbus architecture includes a Modbus controller layer above the standard IO driver. This layer uses a Data Dictionary to abstract physical device parameters (like temperature or humidity) into Characteristic Identifiers (CID).

Instead of interacting directly with Modbus registers, upper layers (like MQTT or MESH) interact with these CIDs. This decouples the application logic from the specific Modbus register maps of the slave devices.

The Data Dictionary

The Data Dictionary is a user-defined array of mb_parameter_descriptor_t structures. Each entry links a unique CID to a specific Modbus register representation on a slave device. This mapping allows the stack to automatically handle data conversion and register addressing.

// Concept: CID -> Data Dictionary -> Modbus Register
// The Data Dictionary maps a unique CID to a physical Modbus register address/type.

The Modbus slave stack requires you to define user-provided memory structures to store Modbus parameters. You must assign these structures to the Modbus controller using the mbc_slave_set_descriptor API before starting communication.

One slave can define multiple area descriptors for each type of Modbus register area by using different start_offset values.

mb_register_area_descriptor_t Fields

Note: If a master attempts to access an area that has not been defined via a descriptor, the stack will generate a Modbus exception.

#define MB_REG_HOLD_CNT             (100)
#define MB_REG_HOLDING_START_AREA0  (0)

static void *slave_handle = NULL;
mb_register_area_descriptor_t reg_area;
uint16_t holding_reg_area[MB_REG_HOLD_CNT] = {0};

reg_area.type = MB_PARAM_HOLDING;
reg_area.start_offset = MB_REG_HOLDING_START_AREA0;
reg_area.address = (void*)&holding_reg_area[0];
reg_area.size = (sizeof(holding_reg_area) << 1); // Size in bytes
reg_area.access = MB_ACCESS_RW;
ESP_ERROR_CHECK(mbc_slave_set_descriptor(slave_handle, reg_area));

The ESP-Modbus implementation uses a Modbus Controller abstraction layer to simplify register access. It relies on two key concepts:

Characteristic Identifier (CID)

An abstraction representing a specific Modbus register on a Slave device. It encapsulates metadata such as the register name, type, and permissions. For example, CID_EX_0 might map to a specific holding register.

Data Dictionary

A list defining all Modbus registers the Master is authorized to access across the network. Each entry in the dictionary maps a CID to its corresponding Modbus registers (address, format, function code) on a Slave. This allows the application to request data by CID rather than managing raw register addresses manually.

Read/Write Lifecycle

1. mbc_master_set_descriptor(): Attaches the Data Dictionary to the master handle.
2. mbc_master_get_cid_info(): Retrieves metadata (name, type, permissions) for a specific CID from the dictionary.
3. mbc_master_get_parameter() / mbc_master_set_parameter(): Executes the actual Modbus read or write operation using the CID.