mbc_master_start(modbus) fails with error 258 ESP_ERR_INVALID_ARG (IDFGH-15441)

[kotyara12]

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?

always

Actual behavior (suspected bug)

Today I needed to add some new options to the firmware of my automatic greenhouse. After the OTA update, all the sensors suddenly stopped working, because rs485/modbus stopped working. Even visually, requests stopped being sent via the RS485 adapter.

Reason: Modbus initialization error [mbc_master_start]: 258 (ESP_ERR_INVALID_ARG)

Moreover, the SAME code worked perfectly before!

The reason is here!!!!
BUT I DON'T NEED A TABLE OF DESCRIPTORS!!!!!!!!!!!!!!!!!!!!!!! I DON'T USE IT

Error logs or terminal output

Modbus initialization error [mbc_master_start]: 258 (ESP_ERR_INVALID_ARG)

Steps to reproduce the behavior

void sensorsInitModbus()
{
rlog_i(logTAG, "Modbus initialization");
// Config master serial mode
mb_communication_info_t config;
memset(&config, 0, sizeof(config));
config.mode = SENSOR_MODBUS_MODE;
// config.common_opts.mode = SENSOR_MODBUS_MODE;
// config.common_opts.port = SENSOR_MODBUS_PORT;
// config.common_opts.response_tout_ms = SENSOR_MODBUS_TIMEOUT;
config.ser_opts.mode = SENSOR_MODBUS_MODE;
config.ser_opts.port = SENSOR_MODBUS_PORT;
config.ser_opts.response_tout_ms = SENSOR_MODBUS_TIMEOUT;
config.ser_opts.baudrate = SENSOR_MODBUS_SPEED;
config.ser_opts.data_bits = SENSOR_MODBUS_DATA_BITS;
config.ser_opts.stop_bits = SENSOR_MODBUS_STOP_BITS;
config.ser_opts.parity = SENSOR_MODBUS_PARITY;

esp_err_t err = mbc_master_create_serial(&config, &_modbus);
if (err != ESP_OK) {
tgSend(MK_SERVICE, MP_HIGH, true, CONFIG_TELEGRAM_DEVICE, "Ошибка инициализации Modbus [mbc_master_create_serial]: %d (%s)", err, esp_err_to_name(err));
return;
};
// Set UART pins
err = uart_set_pin(SENSOR_MODBUS_PORT, SENSOR_MODBUS_PIN_TXD, SENSOR_MODBUS_PIN_RXD, SENSOR_MODBUS_PIN_RTS, SENSOR_MODBUS_PIN_CTS);
if (err != ESP_OK) {
tgSend(MK_SERVICE, MP_HIGH, true, CONFIG_TELEGRAM_DEVICE, "Ошибка инициализации Modbus [uart_set_pin]: %d (%s)", err, esp_err_to_name(err));
return;
};
// Set UART mode
err = uart_set_mode(SENSOR_MODBUS_PORT, UART_MODE_RS485_HALF_DUPLEX);
if (err != ESP_OK) {
tgSend(MK_SERVICE, MP_HIGH, true, CONFIG_TELEGRAM_DEVICE, "Ошибка инициализации Modbus [uart_set_mode]: %d (%s)", err, esp_err_to_name(err));
return;
};
// Start Modbus
err = mbc_master_start(_modbus);
if (err != ESP_OK) {
tgSend(MK_SERVICE, MP_HIGH, true, CONFIG_TELEGRAM_DEVICE, "Ошибка инициализации Modbus [mbc_master_start]: %d (%s)", err, esp_err_to_name(err));
return;
};
return;
}

Project release version

2.0.2

System architecture

Intel/AMD 64-bit (modern PC, older Mac)

Operating system

Windows

Operating system version

Windows 10

Shell

CMD

Additional context

No response

[alisitsyn]

@kotyara12 ,

Thanks for the issue. Unfortunately, I can not confirm this as a bug because the main interface of esp-modbus is data dictionary based (through mbc_xxx_master_get_parameter(), mbc_xxx_master_set_parameter()). This is why the length of the required data dictionary is checked in the function.

BUT I DON'T NEED A TABLE OF DESCRIPTORS!!!!!!!!!!!!!!!!!!!!!!! I DON'T USE IT

Even if you don't use this interface, I propose you register a dummy data dictionary with just one simple characteristic before starting the Modbus interface. This procedure should solve your issue.

[kotyara12]

But I still think it's a MISTAKE!

Because YOU DEPRIVE users of a normal, simple development method, and instead offer incredibly complex and useless nonsense. It's not only complicated and confusing, but also blocks adding modbus, for example, to pluggable device drivers.

You yourself forced me to switch to 2.0.2, after you broke 1.0.17. And now you offer crutches.

[brabema]

I would like to add that this limitation negatively affects the development of real projects as well.

In many real-world setups, the RS485 bus is not exclusively used for Modbus. In my system, for example, the same UART/RS485 line may be used for DMX or vendor-specific frame formats, depending on the active module. This requires stopping the Modbus master, reconfiguring the UART, and sometimes restarting the Modbus master. In these cases, forcing a static descriptor table adds unnecessary configuration overhead and introduces instability because:

• The descriptor table must be recreated after each Modbus master reinitialization.

• Device addresses and parameters are often not all known at startup because some devices announce themselves later. This means the descriptor table would need to be dynamically rebuilt or extended, which is error-prone and fragile.

• The purpose of using raw Modbus requests is to avoid fixed parameter mapping and allow flexible device probing and dynamic discovery.

Therefore, requiring a descriptor table when the descriptor-based API is not used blocks valid development workflows.

Therefore, there may be a configuration option (e.g., CONFIG_MODBUS_REQUIRE_DESCRIPTOR_TABLE). If this is disabled, the mbc_master_start() function must skip descriptor validation and allow the controller to operate with direct Modbus request functions.

This would:

• Preserve compatibility for users who rely on the parameter table API.

• It would also restore flexibility for projects that use dynamic or topology-driven device discovery or multiplex RS485 for multiple protocols.

• It would also avoid forcing developers to maintain a descriptor table that their architecture does not need.

This is not about refusing the descriptor system — it is about allowing both development models to coexist cleanly.

One thing I still don’t understand about the current design is:

Why is the presence of the descriptor table validated during mbc_master_start() instead of only when the descriptor-based API (mbc_master_get_parameter()/mbc_master_set_parameter()) is called?

From an architectural perspective, the current behavior means:

If the descriptor table is missing, the Modbus master is completely disabled, even if the application does not use the descriptor-based API.

Wouldn’t it be more reasonable to allow the master to start normally, and only return an error when the descriptor-dependent functions are called?

If there is a design or technical constraint that requires the validation to be done during initialization, I would really appreciate clarification on the reasoning behind it. Understanding the intention would help in adjusting or proposing a proper contribution if needed.