Serial master uses uninitialized descriptor size when no descriptor table is configured (EPROT-86) #187

Checklist

• Checked the issue tracker for similar issues to ensure this is not a duplicate
• Read the documentation to confirm the issue is not addressed there and your configuration is set correctly
• Tested with the latest version to ensure the issue hasn't been fixed

How often does this bug occurs?

often

Expected behavior

When using the serial Modbus master with the raw mbc_master_send_request() API, the Modbus master should be able to start without configuring a parameter descriptor table, since mbc_master_send_request() does not use the descriptor table.

If a descriptor table is required by design, the descriptor-related state should at least be initialized deterministically so that startup behavior does not depend on the heap contents.

Actual behavior (suspected bug)

mbc_serial_master_start() checks:

MB_RETURN_ON_FALSE((mbm_opts->mbm_param_descriptor_size >= 1),
ESP_ERR_INVALID_ARG, TAG,
"mb descriptor table size is incorrect.");

However, mb_master_options_t is allocated using malloc() during controller creation, and mbm_param_descriptor_size is not explicitly initialized.

When no descriptor table is configured, this value therefore contains an indeterminate value.

As a result, mbc_master_start() can behave intermittently depending on the state of the heap before Modbus initialization. Other components such as Wi-Fi and MQTT can change the heap allocation pattern and therefore influence whether the problem occurs.

The problem can be avoided by configuring a dummy descriptor before calling mbc_master_start():

mbc_master_set_descriptor(modbus_master_handle,
&dummy_descriptor,
1);

This explicitly sets:

mbm_opts->mbm_param_descriptor_size = 1;

After this, mbc_master_start() succeeds and mbc_master_send_request() works normally.

The actual Modbus communication uses the raw request API and does not otherwise use the descriptor table.

Error logs or terminal output

When the problem occurs:

E (...) mbc_serial.master: mbc_serial_master_start(...): mb descriptor table size is incorrect.
E (...) MB_CONTROLLER_MASTER: mbc_master_start(...): Master start failure, error=(0x102) (ESP_ERR_INVALID_ARG).
E (...) EQSP32CE: mbc_master_start(): 0x00000102 (ESP_ERR_INVALID_ARG)

E (...) MB_CONTROLLER_MASTER: mbc_master_send_request(...): Master interface is not correctly configured.
E (...) EQSP32CE: mbc_master_send_request(): 0x00000103 (ESP_ERR_INVALID_STATE)

The issue is intermittent. The same application can start successfully under different heap conditions.

Configuring a single dummy descriptor before mbc_master_start() makes the problem disappear.

Steps to reproduce the behavior

Create a serial Modbus master using mbc_master_create_serial().
Do not configure a parameter descriptor table.
Configure the UART for RS485.
Call mbc_master_start().
Observe that startup may fail with:
mb descriptor table size is incorrect.
The failure can depend on what other components have initialized before Modbus, such as Wi-Fi and MQTT.
Configure a single dummy descriptor using mbc_master_set_descriptor(..., 1) before mbc_master_start().
Call mbc_master_start() again.
Observe that the master starts successfully.
Use mbc_master_send_request() for direct Modbus requests; communication works normally.

Project release version

ESP-Modbus managed component used with: ESP-IDF v5.3.1

System architecture

other (details in Additional context)

Operating system

MacOS

Operating system version

26.5.2 (25F84)

Shell

ZSH

Additional context

ESP32-S3

Modbus RTU master over RS485

UART2, 4800 baud, 8N1