The mbc_serial_master_start() function checks the mbm_param_descriptor_size before initialization. Descriptor size validation is performed on uninitialized memory. (EPROT-18)

[brabema]

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

Expected behavior

When starting the Modbus master, the code must not validate uninitialized memory (i.e., it must not check a descriptor table size that has not yet been set). The mbm_param_descriptor_size field should be initialized deterministically or the descriptor check should be skipped if no descriptor table has been registered.

Actual behavior (suspected bug)

mbc_serial_master_start() checks mbm_param_descriptor_size before it is initialized. Since this field contains uninitialized memory at the time of the check, the result is undefined. Sometimes the start completes successfully (if the random memory value happens to be ≥ 1), and sometimes it fails with ESP_ERR_INVALID_ARG. This means the Modbus master startup behavior depends on whatever garbage value was present in that memory location, causing inconsistent and unreliable initialization.

Error logs or terminal output

Steps to reproduce the behavior

1. Take the standard Modbus master serial example from ESP-IDF (no modifications).
2. Run it through a debugger or add a temporary log file, then stop it inside the mbc_serial_master_start() function.
3. Check the value of mbm_opts->mbm_param_descriptor_size.
4. Unless mbc_master_set_descriptor() has been called before mbc_master_start(), you will observe that this field contains uninitialized memory.
5. In the current API usage model and examples, mbc_master_set_descriptor() is typically called after the Modbus controller has been started. This means that the mbm_param_descriptor_size field may not contain a valid value when the program starts up.
6. The initial result depends entirely on the random contents of that memory location because mbc_serial_master_start() performs a descriptor size validation at this stage. Sometimes the validation succeeds and sometimes it fails. This is completely unrelated to the actual Modbus configuration.

Project release version

main

System architecture

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

Operating system

Linux

Operating system version

openSUSE Leap 15.6

Shell

ZSH

Additional context

In many designs, it is valid and necessary for the Modbus master to start before any descriptor table is defined. The controller should be able to initialize and operate using raw Modbus frames without parameter descriptors.

Currently, the startup procedure is implicitly tied to the state of the descriptor table. Since the descriptor size field is uninitialized at that time, the outcome of startup becomes non-deterministic. The underlying problem is not the use of descriptors themselves, but rather that the controller’s initialization depends on memory that has not been intentionally set.

A cleaner API model would be:

The Modbus master can start independently of the descriptor table.

Descriptor validation would only occur when descriptor-based APIs are invoked.

If no descriptor table has been registered, the relevant functions return a clear error (e.g., ESP_ERR_NOT_SUPPORTED).

This decouples raw Modbus communication from descriptor-based parameter mapping. It supports both usage patterns cleanly and removes the undefined behavior caused by reading uninitialized memory during startup.

[alisitsyn]

@brabema ,

Thanks for the issue.

In the current API usage model and examples, mbc_master_set_descriptor() is typically called after the Modbus controller has been started. This means that the mbm_param_descriptor_size field may not contain a valid value when the program starts up.

Check the value of mbm_opts->mbm_param_descriptor_size.
Unless mbc_master_set_descriptor() has been called before mbc_master_start(), you will observe that this field contains uninitialized memory.

The serial master example has incorrect order of the API calls. The start mbc_master_start() is called before the mbc_master_set_descriptor(). The function must be called on stack initialization step to properly setup the instance before start and using. The documentation clearly explains this:

Examples Of Mapping.

This will be fixed in the example accordingly.

Currently, the startup procedure is implicitly tied to the state of the descriptor table. Since the descriptor size field is uninitialized at that time, the outcome of startup becomes non-deterministic. The underlying problem is not the use of descriptors themselves, but rather that the controller’s initialization depends on memory that has not been intentionally set.

Please note that descriptor based API are primary functionality of the stack! The mbc_master_start verifies that the data dictionary size before start of master and returns the error otherwise. This does not prevent to use the stack as described in the documentation calling the mbc_master_set_descriptor then start the stack.

Descriptor validation would only occur when descriptor-based APIs are invoked.
If no descriptor table has been registered, the relevant functions return a clear error (e.g., ESP_ERR_NOT_SUPPORTED).
This decouples raw Modbus communication from descriptor-based parameter mapping. It supports both usage patterns cleanly and removes the undefined behavior caused by reading uninitialized memory during startup.

I can understand that the primary interface is not what you are using in your projects. I will try to find the good solution for this later to avoid future complains.

[brabema]

@alisitsyn

Its primary behavior is clear, and I don’t think it conflicts with my project conceptually. However, due to real-world constraints, I cannot currently use the descriptor table in a convenient or productive way. In order to make it work, I would need to duplicate most of the data structures and perform repeated full reinitializations, which would be impractical and unstable.

In many practical systems, including mine, the descriptor table cannot be fully defined at startup. For example:

• Slave devices may be discovered dynamically on the bus.
• Some devices announce their parameters later during runtime.
• The RS485 line can temporarily support a different protocol (e.g., DMX) before Modbus polling resumes.

For this reason, I would like to use the descriptor interface. However, I need the descriptor table to be as follows:

• It can be initialized with size = 0 and extended later as devices are discovered.
• It is reconfigurable at runtime without requiring a full teardown and restart of the stack.
• It is allowed to start without a descriptor and remain functional until descriptors are added.

The documentation says:

“The Data Dictionary can be initialized from SD card, MQTT or other source before start of stack.”

However, in real deployments, this information is often unavailable at the beginning, and is instead collected dynamically after communication begins.
Therefore, the current API ordering requirement prevents the descriptor system from being used in the intended "data-driven" way.

I would be very happy to use the descriptor-based workflow if the descriptor table could be:

• Allocated or registered with a size of 0.
• Dynamically expanded (or reallocated) later.
• Without forcing a stack restart.

Additionally, regardless of the API design, I believe it is important that the memory fields used during initialization always be in a defined state. Currently, mbm_param_descriptor_size is read before it is guaranteed to be initialized. It would improve robustness if the stack ensured the deterministic initialization of all internal fields. This is simply a matter of safety; using uninitialized memory should not affect startup behavior.

I am happy to open a separate ticket to discuss the descriptor API, if necessary. My main concern is that the current descriptor handling model is limiting for dynamic use cases. Making it more flexible would enable the primary descriptor workflow and dynamic runtime scenarios to coexist seamlessly.

[alisitsyn]

Dear @brabema,

thank you for this input and clear description of what you are expecting from the stack. Please find my answers below:

In order to make it work, I would need to duplicate most of the data structures and perform repeated full reinitializations, which would be impractical and unstable.

Slave devices may be discovered dynamically on the bus. Some devices announce their parameters later during runtime.
It is reconfigurable at runtime without requiring a full teardown and restart of the stack.
It can be initialized with size = 0 and extended later as devices are discovered.
It is reconfigurable at runtime without requiring a full teardown and restart of the stack.
It is allowed to start without a descriptor and remain functional until descriptors are added.

It was expected that this can be performed on the user layer with the current stack and a small workaround. It is doable.

The RS485 line can temporarily support a different protocol (e.g., DMX) before Modbus polling resumes.

You need to take into account that it is hard to address all possible use cases (have a huge list of them already) and keep component maintainable and testable. Your use cases are very different from normal Modbus workflow (DMX and Modbus devices on one bus). I believe you can handle this with the current stack, but I cannot guarantee this functionality and stability of the stack in these cases.

However, in real deployments, this information is often unavailable at the beginning, and is instead collected dynamically after communication begins.

As I said, the dynamic discovery of devices is possible, and it is possible to update the device description at run time and then do polling.

Thank you for clarification of the requirements for your projects and what you are expecting from Modbus standpoint. Please create a separate issue regarding the API interface, and we can discuss it there. Also, it is possible to create the topic on the discussions page. In this case other users can add their expectations as well. I will try to address the expectations that are doable and testable in the current test infrastructure but cannot guarantee that they all will be covered for obvious reasons. Also, please note that I try to keep interface unchanged when possible to keep component maintainable and provide the support regardless of the component version.

Additionally, regardless of the API design, I believe it is important that the memory fields used during initialization always be in a

I can agree; initialization of some option fields can be improved to not depend on the initialization sequence even if it is clearly documented.

[brabema]

@alisitsyn

Thank you very much for your detailed reply and for addressing each point so carefully.

I understand your position on maintainability and test coverage. I don't intend to complicate the component; rather, I want to make it more flexible for dynamic or mixed-protocol environments without disrupting existing functionality.

I’m glad to hear that dynamic descriptor updates and runtime reconfiguration are possible with minor adjustments. That's precisely the functionality I was hoping to confirm. I also appreciate your acknowledgment that some option fields could be initialized more robustly and independently of the initialization sequence.

I plan to create a new discussions focused on API flexibility and dynamic descriptor handling. This will allow us to continue the discussion in a more structured way when time permits. Hopefully, we can design an approach that maintains interface stability while supporting more adaptive and dynamic use cases.

As I said, the dynamic discovery of devices is possible, and it is possible to update the device description at run time and then do polling.

You mentioned this in September 2024 (see discussion #68), but considering the current implementation, I’m not sure how it could work dynamically in practice. From my point of view, it appears somewhat contradictory: on one hand, dynamic discovery and updates are said to be possible, but on the other hand, the current design and initialization flow seem to prevent safe runtime descriptor updates.

This design idea came from the start and was defined as a requirement. The typical use case for Modbus master is: 1. setup the objects and network then 2. start communication. For the esp-modbus v1.0.x serial the mbc_master_set_descriptor is relatively simple and can update the object dictionary run time but it may cause issues. Note that the modbus task has access to data dictionary means if the data dictionary is updated when the stack is active it may cause serious problems such as memory leaks and even crash. In this case the access to the data dictionary should be protected by mutex to use it safely by synchronization task and modbus task.

Note: the esp-modbus v2.0 tcp stack uses smarter logic to check the object dictionary with conjunction with address table. It can not be changed simply run time.

Regarding dynamic updates, I’d like to highlight a few practical limitations of the current implementation:

• To add a device, the entire descriptor table must be rebuilt and swapped. This leads to high peak RAM usage, potential fragmentation, and additional reinitialization steps.
• There’s no way to append or replace a single CID entry — only full-table replacement is supported, which forces complete copies during discovery.
• The function does not track previous table size or version, so the stack cannot detect whether the descriptor set grew or shrank.
• The controller keeps a borrowed pointer to the descriptor; ownership and lifetime remain with the application, which can become brittle during live updates.

These issues make runtime descriptor management possible only with heavy duplication and manual reinitialization, which can be challenging on memory-constrained systems.

Thanks again for your openness and for maintaining this component so actively

[alisitsyn]

You mentioned this in September 2024 (see #68 (comment)), but considering the current implementation, I’m not sure how it could work dynamically in practice. From my point of view, it appears somewhat contradictory: on one hand, dynamic discovery and updates are said to be possible, but on the other hand, the current design and initialization flow seem to prevent safe runtime descriptor updates.

What was mentioned means the discovery and dynamic updates should be performed carefully. As I said before, the device discovery is possible in the current implementation. I will try to be more specific to avoid misunderstanding. Please consider the below simplified algorithm for the serial communication cycle, including device discovery:

The Modbus master communication session:

Let us assume that devices will contain, for example, two physical parameters to read (humidity and temperature), but the mapping of these parameters depends on the device manual and is different.

Assumptions and dependencies:

Before the start of the session, the master must know all possible supported slaves that will be connected and handled during the communication session. This is regular Modbus workflow; otherwise, the master cannot communicate correctly with the slaves. The supported slave devices may not appear on the bus when the master starts the session and can be detected during discovery. However, the mapping table of supported slaves must be known. The discovery algorithm will be used to detect the slaves that are connected to the bus in the scope of addresses using their UID.

Serial discovery algorithm:

1. Create a master instance with specific communication parameters. Create a device description linked list or array of structures that will keep the device description information.

2. Reallocate space for the data description table and initialize it with one CID needed for slave detection (can include more CIDs to detect devices on the bus reading several fields). This CID may describe the device (device string, HW version, SW version, device baud, etc.) and will be used for device discovery requests. It can use the "REPORT_SLAVE_ID" or just "READ_HOLDING_REGISTERS" commands to get the descriptor fields from the device as a whole structure or get separate fields from the device.

3. Register the data descriptor table with a call to mbc_master_set_descriptor().

4. Start the master instance using the mbc_master_start.

5. The mb_discovery() function will be used to send a device discovery request to the bus for every slave in the range of supported UIDs. The function mbc_master_get_parameter_with can be used to send the probe to each slave. Once the response is received, the read device description information is kept in the allocated description entry structure, including the initialized device_is_alive flag. The data dictionary will be appended with the predefined CIDs of type mb_parameter_descriptor_t for the corresponding device (comes from the slave mapping table and corresponds to humidity and temperature in our example), and the start CID index and number of CIDs are kept in the device descriptor structure. The structure is appended to the device description linked list. The "param_opts" fields can be used to link to the device descriptor entry using its UID. At the end of the discovery, the device description list is filled with device information and links to the start CID of the device information.

6. Start the task, which is doing the polling cycle reading or writing corresponding parameters for each device according to the device description table and linked CIDs from the data dictionary. During the polling cycle the device alive flag in the device descriptor is updated according to read errors, and if it is not alive during the maximum number of cycles, the flag will be cleared and may stop the instance and trigger the mb_discovery(). This can also be repeated after timeout. If devices have different communication parameters, they can be read on the device discovery cycle, and the UART speed can be reinitialized for each device in the device descriptor table using regular UART set speed functions before the request of any CID.

7. If the project needs to change some fields in the data dictionary runtime, the data dictionary has to be changed inside the critical section using mbc_master_lock() and mbc_master_unlock() functions.

8. The master is destroyed on some condition as required and destroys all allocated objects as necessary.

Similar approach can be used to form the device description from the json format as example and create the table for each device on the fly then start polling. The descriptor changes shall be protected with critical section as described above.

For the TCP device discovery it is possible to use the delegate name mb_tcp_segment to get the linked list of addresses for all registered modbus instances in the segment and then iterate over them sending the discovery requests to them and form the device list as described above. The corresponded example will be added to the examples folder to demonstrate device discovery feature.

To add a device, the entire descriptor table must be rebuilt and swapped. This leads to high peak RAM usage, potential fragmentation, and additional re-initialization steps.
There’s no way to append or replace a single CID entry — only full-table replacement is supported, which forces complete copies during discovery.
The function does not track previous table size or version, so the stack cannot detect whether the descriptor set grew or shrank.
The controller keeps a borrowed pointer to the descriptor; ownership and lifetime remain with the application, which can become brittle during live updates.

A little modifications of the discovery and polling algorithm are possible:

• The data descriptor table (mapping table of slave) for each device type is kept in the constant array of type mb_parameter_descriptor_t in flash memory (required to communicate with certain supported slaves).

• The device type is determined from the response of the slave to the probe frame and initialized in the device descriptor entry structure of type mb_device_descriptor_t. This structure includes a data descriptor pointer and size, which will be initialized to the start of the mapping table for the concrete device type. The device descriptor also keeps the UID of the actual detected device for later usage.

• Before the start of polling for each device, the data descriptor table is set using the call mbc_master_set_descriptor() with the initialized device descriptor pointer and constant size. If the device uses different communication settings, they also can be overridden according to the device descriptor settings. The changes of master data descriptor are pretty safe when the communication is performed from one polling task and performed before each iteration.

• Once the descriptor is set, it is possible to iterate through the characteristics using the regular API (mbc_serial_master_get_cid_info). The polling cycle is performed using the mbc_master_get_parameter_with, mbc_master_set_parameter_with with overridden UID taken from the device descriptor entry structure. The polling can iterate from one device descriptor to another and read/write characteristics according to the data description table (linked list or simple array of type mb_device_descriptor_t).