Confusing architecture and examples (IDFGH-15438) #122

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.