Confusing architecture and examples (IDFGH-15438)

[wuyuanyi135]

Checklist

• Checked the issue tracker for similar issues to ensure this is not a duplicate.
• Provided a clear description of your suggestion.
• Included any relevant context or examples.

Issue or Suggestion Description

Greetings,
The ESP-IDF docs and examples have always been extremely articulate and helpful. However, I find the docs and example of esp-modbus module extremely confusing.

First, esp-idf docs stats that the modbus library is moved to esp-modbus but the example still shows the original usages. Took me a load of time to figure out where mbc_master_setup lies in.

Next, I have no idea how the library handles the underlying data (or register cache). In the example, it defines holding registers, input registers as global variables. But I don't see where those storage variables are connected to the library. I assumed that I should pass the pointer to the registers to mbc_master_create_serial. However, from the example, seems I have to write a loop to retry and get the all the registers and manually copy them into the variables. If so, why would I even assign the param_size, _offset, etc. in the first place? Shouldn't I just write a callback that handles the mapping from the modbus register to the cache memory?

Also, why do I have to specify all of parameter type, parameter size, and mb_size? with a single parameter type the rest should be inferred? right?

In addition, why would one care the display name or the unit of the variable? I think this is application specific and should be taken care by the users by simply maintaing a map from the register address to those descriptions.

Finally, the example killed me. Other than the confusing v1 and v2 examples in esp-idf and this repository, the example is also too verbose. Usually I just copy and paste the example and make my modification but this example has a lot of testing code in it.

I will write a C++ library to wrap this library. I would say metaprogramming will simplify the register map by a lot.

[wuyuanyi135]

When I specify the type as I32_ABCD, it just fails and gives me param type error. I track the source code and noticed that if CONFIG_FMB_EXT_TYPE_SUPPORT was not checked all of those types just errored out. Shouldn't there be some warning to let the developer know the type support should be checked in the menuconfig? Debug effort ++;