independent instance command handling using lists, fixes as per review and test

Author: alisitsyn

CMakeLists.txt

@@ -1,6 +1,7 @@
 # The following five lines of boilerplate have to be in your project's
 # CMakeLists in this exact order for cmake to work correctly
 set(srcs
+    "mb_controller/common/esp_modbus_common.c"
     "mb_controller/common/esp_modbus_master.c"
     "mb_controller/common/esp_modbus_slave.c"
     "mb_controller/common/esp_modbus_master_serial.c"
@@ -13,6 +14,7 @@ set(srcs
     "mb_controller/tcp/mbc_tcp_slave.c"
     "mb_objects/mb_master.c"
     "mb_objects/mb_slave.c"
+    "mb_objects/functions/mbfunc_handling.c"
     "mb_objects/functions/mbfunccoils_master.c"
     "mb_objects/functions/mbfunccoils.c"
     "mb_objects/functions/mbfuncdiag.c"

Kconfig

@@ -224,18 +224,9 @@ menu "Modbus configuration"
                 otherwise the only legacy types are supported. The extended types include
                 integer, float, double types with different endianness and size.
 
-    config FMB_CONTROLLER_SLAVE_ID_MAX_SIZE
-        int "Modbus Slave ID maximum buffer size (bytes)"
-        range 4 255
-        default 32
-        depends on FMB_CONTROLLER_SLAVE_ID_SUPPORT
-        help
-                Modbus slave ID buffer size used to store vendor specific ID information
-                for the <Report Slave ID> command.
-
     config FMB_FUNC_HANDLERS_MAX
         int "Maximum number of Modbus function handlers"
-        range 16 64
+        range 16 255
         default 16
         help
                 This option defines the maximum number of Modbus command handlers for Modbus master and slave.

docs/en/applications_and_references.rst

@@ -48,11 +48,11 @@ The examples below demonstrate the library port for serial, TCP slave and master
 
 .. _example_mb_tcp_master:
 
-- `Modbus TCP master example <https://github.com/espressif/esp-modbus/tree/main/examples/tcp/mb_tcp_slave>`__
+- `Modbus TCP master example <https://github.com/espressif/esp-modbus/tree/main/examples/tcp/mb_tcp_master>`__
 
 .. _example_mb_tcp_slave:
 
-- `Modbus TCP slave example <https://github.com/espressif/esp-modbus/tree/main/examples/tcp/mb_tcp_master>`__
+- `Modbus TCP slave example <https://github.com/espressif/esp-modbus/tree/main/examples/tcp/mb_tcp_slave>`__
 
 Please refer to the specific example README.md for details.
 

docs/en/master_api_overview.rst

@@ -313,38 +313,56 @@ Master Customize Function Handlers
 
 The Master object contains the command handling tables to define the specific handling functionality for each supported Modbus command. The default handling functions in this table support most common Modbus commands. However, the list of commands can be extended by adding the new command into handling table with its custom handling behavior. It is also possible overriding the function handler for the specific command. The below described API functions allow using this behavior for master objects.
 
-:cpp:func:`mbc_master_set_handler`
+:cpp:func:`mbc_set_handler`
 
-:cpp:func:`mbc_master_get_handler`
+The function adds new handler for the function or overrides the existing handler for the function.
 
-The example code to overide the handler routine for command `0x04 - Read Input Registers`:
+:cpp:func:`mbc_get_handler`
+
+The function returns the handler for the specified function code from handling table. Allows to keep and use the predefined handlers for standard functions.
+
+:cpp:func:`mbc_delete_handler`
+
+The function allows to delete the handler for specified command and free the handler table entry for this.
+
+:cpp:func:`mbc_get_handler_count`
+
+The function returns the actual number of command handlers registered for the object reffered by parameter.
+
+The example code to override the handler routine for the command `<0x04 - Read Input Registers>` is below. This example allows to perform a custom action and then calls the standard handler, which maps the device data to the command buffer from the actual parameter. This is just recommended behavior for handling functions, but users can change the order of the calls if absolutely required. Please refer to the existing handler :cpp:func:`mbm_fn_read_inp_reg` for more information.
 
 .. code:: c
 
     static void *master_handle = NULL;  // Pointer to allocated interface structure
-    uint8_t override_command = 0x04;
+    const uint8_t override_command = 0x04;
+    mb_fn_handler_fp pstandard_handler = NULL;
     ....
-    // Define the custom function handler for the command.
-    // The handler body must be short and don't use any unpredictable logic. The handler 
-    // is executed in the context of modbus controller event task.
+    // This is the custom function handler for the command.
+    // The handler is executed from the context of modbus controller event task and should be as simple as possible.
+    // Parameters: frame_ptr - the pointer to the incoming ADU frame from slave starting from function code,
+    // plen - the pointer to length of the frame. After return from the handler the modbus object will 
+    // handle the end of transaction according to the exception returned.
     mb_exception_t my_custom_fc04_handler(void *pinst, uint8_t *frame_ptr, uint16_t *plen)
     {
-        MB_RETURN_ON_FALSE(frame_ptr && plen, MB_EX_CRITICAL, TAG,
-                                "incorrect frame buffer length");
-        // This error handler will be executed to check the request for the command 0x04
-        // See the default handler in the file `esp-modbus//modbus/mb_objects/functions/mbfuncinput_master.c` for more information.
-        // The pframe is pointer to command buffer, plen - is pointer to length of the buffer
-        return MB_EX_CRITICAL;
+        mb_exception_t exception = MB_EX_CRITICAL;
+        MB_RETURN_ON_FALSE(frame_ptr && plen, exception, TAG, "incorrect frame buffer length");
+        // It is the possible place for the custom behavior
+        if (pstandard_handler) {
+            exception = pstandard_handler(pinst, frame_ptr, plen); // invoke standard behavior with mapping
+        }
+        return exception;
     }
     ....
-    err = mbc_master_set_handler(master_handle, override_command, NULL);
+    // Get the standard handler for the command to use it in the handler.
+    err = mbc_get_handler(master_handle, custom_command, &pstandard_handler);
     MB_RETURN_ON_FALSE((err == ESP_OK), ESP_ERR_INVALID_STATE, TAG,
-                        "could not override handler, returned (0x%x).", (int)err);
-    err = mbc_master_set_handler(master_handle, override_command, my_custom_fc04_handler);
+                            "could not get handler for command %d, returned (0x%x).", (int)custom_command, (int)err);
+    // This call overrides the handler for the standard command.
+    err = mbc_set_handler(master_handle, override_command, my_custom_fc04_handler);
     MB_RETURN_ON_FALSE((err == ESP_OK), ESP_ERR_INVALID_STATE, TAG,
                         "could not override handler, returned (0x%x).", (int)err);
 
-.. note:: The custom handler set by the function :cpp:func:`mbc_master_set_handler` should be as short as possible and should contain simple and safe logic to not break the normal functionality of the stack. This is user application responsibility to handle the command appropriately.
+.. note:: The custom handler set by the function :cpp:func:`mbc_set_handler` should be as short as possible and should contain simple and safe logic to not break the normal functionality of the stack. This is user application responsibility to handle the command appropriately.
 
 The example code to handle custom vendor specific command is below. This example sends the 'Master' string to slave and gets the response from slave with the string being appended from slave. It is just a simple echo example to demonstrate the approach.
 
@@ -355,33 +373,29 @@ The example code to handle custom vendor specific command is below. This example
     static void *master_handle = NULL;  // Pointer to allocated interface structure
 
     // This is the custom function handler to process incoming slave response.
-    // Refer the function handler examples in `esp-modbus/modbus/mb_objects/functions/mbfuncinput_master.c` for more information.
-    // Parameters: pframe: is pointer to incoming frame buffer, plen: is pointer to length including the function code
-    // In spite of logging showed here, try to use just simple functionality here.
+    // Parameters: frame_ptr: is a pointer to incoming frame buffer, plen: is pointer to length including the function code
+    // In spite of logging showed here, try to use just simple functionality in the handler.
     mb_exception_t my_custom_fc_handler(void *pinst, uint8_t *frame_ptr, uint16_t *plen)
     {
-        MB_RETURN_ON_FALSE((frame_ptr && plen && *plen && *plen < (MB_CUST_DATA_LEN - 1)), MB_EX_CRITICAL, TAG,
+        MB_RETURN_ON_FALSE((frame_ptr && plen && *plen && *plen < (MB_CUST_DATA_LEN - 1)), MB_EX_ILLEGAL_DATA_VALUE, TAG,
                                 "incorrect custom frame buffer");
-        ESP_LOGW(TAG, "Custom handler, Frame ptr: %p, len: %u", frame_ptr, *plen);
+        ESP_LOGI(TAG, "Custom handler, Frame ptr: %p, len: %u", frame_ptr, *plen);
         strncpy((char *)&my_custom_data[0], (char *)&frame_ptr[1], MB_CUST_DATA_LEN);
-        ESP_LOG_BUFFER_HEXDUMP("CUSTOM_DATA", &my_custom_data[0], (*plen - 1), ESP_LOG_WARN);
+        ESP_LOG_BUFFER_HEXDUMP("CUSTOM_DATA", &my_custom_data[0], (*plen - 1), ESP_LOG_INFO);
         return MB_EX_NONE;
     }
     ....
     // The setup of the master object is completed and the master_handle is already actual
 
     // Add custom command handler
-    uint8_t custom_command = 0x41; // the function code for the request
-    // Reset the handler for the command if already set
-    err = mbc_master_set_handler(master_handle, custom_command, NULL);
-    MB_RETURN_ON_FALSE((err == ESP_OK || err == ESP_ERR_INVALID_STATE), ESP_ERR_INVALID_STATE, TAG,
-                        "could not override handler, returned (0x%x).", (int)err);
-    err = mbc_master_set_handler(master_handle, custom_command, my_custom_fc_handler);
+    const uint8_t custom_command = 0x41; // the function code for the request
+    // Override or add new handler entry.
+    err = mbc_set_handler(master_handle, custom_command, my_custom_fc_handler);
     MB_RETURN_ON_FALSE((err == ESP_OK), ESP_ERR_INVALID_STATE, TAG,
                             "could not override handler, returned (0x%x).", (int)err);
     mb_fn_handler_fp phandler = NULL;
     // Make sure the handler is updated correctly
-    err = mbc_master_get_handler(master_handle, custom_command, &phandler);
+    err = mbc_get_handler(master_handle, custom_command, &phandler);
     MB_RETURN_ON_FALSE((err == ESP_OK && phandler == my_custom_fc_handler), ESP_ERR_INVALID_STATE, TAG,
                             "could not get handler for command %d, returned (0x%x).", (int)custom_command, (int)err);
 
@@ -394,14 +408,18 @@ The example code to handle custom vendor specific command is below. This example
     };
 
     // Send the request with custom command (vendor speciic)
+    // This function supports sending of even number of bytes
+    // as instructed by req.reg_size (Modbus register = 2 bytes)
     err = mbc_master_send_request(master_handle, &req, pcustom_string);
     if (err != ESP_OK) {
         ESP_LOGE("CUSTOM_DATA", "Send custom request fail.");
     } else {
-    // The request is processed correctly and the `my_custom_data[]` contains the sent string with appended slave string
-    ...
+        // The request is processed correctly and the `my_custom_data[]` contains the sent string with appended slave string
+        ...
     }
 
+Refer to :ref:`example Serial master <example_mb_master>` for more information.
+
 .. _modbus_api_master_start_communication:
 
 Master Communication

docs/en/slave_api_overview.rst

@@ -167,46 +167,66 @@ Example to get the actual slave identificator:
 Slave Customize Function Handlers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Slave object contains the command handling tables to define the specific handling functionality for each supported Modbus command. The default handling functions in this table support most useful Modbus commands. However, the list of commands can be extended by adding the new command into handling table with its custom handling behavior. It is also possible overriding the function handler for the specific command. The below described API functions allow using this behavior slave objects.
+The Slave object contains the command handling tables to define the specific handling functionality for each supported Modbus command. The default handling functions in this table support most useful Modbus commands. However, the list of commands can be extended by adding the new command into handling table with its custom handling behavior. It is also possible overriding the function handler for the specific command. The below described API functions allow using this behavior for slave objects.
 
-:cpp:func:`mbc_slave_set_handler`
+:cpp:func:`mbc_set_handler`
 
-:cpp:func:`mbc_slave_get_handler`
+The function adds new handler for the function or overrides the existing handler for the function.
 
-The following example allows to override the standard command to read input registers. Refer to examples for more information on how to handle custom commands.
+:cpp:func:`mbc_get_handler`
+
+The function returns the handler for the specified function code from handling table. Allows to keep and use the predefined handlers for standard functions.
+
+:cpp:func:`mbc_delete_handler`
+
+The function allows to delete the handler for specified command and free the handler table entry for this.
+
+:cpp:func:`mbc_get_handler_count`
+
+The function returns the actual number of command handlers registered for the object reffered by parameter.
+
+The following example allows to override the standard command to read input registers. Refer to standard handler function :cpp:func:`mbs_fn_read_input_reg` for more information on how to handle custom commands.
 
 .. code:: c
 
     static void *slave_handle = NULL;  // Pointer to allocated interface structure (must be actual)
+    mb_fn_handler_fp pstandard_handler = NULL;
     ....
-    // The custom function handler for the function returns exception code for now
-    // Please place your custom handling behavior here.
-    // This error handler will be executed to check the request for the command 0x04
-    // See the default handler in the file `esp-modbus//modbus/mb_objects/functions/mbfuncinput_slave.c` for more information.
-    // The pframe is pointer to command buffer, plen - is pointer to the variable with the length of the buffer
+    // This is the custom function handler for the command.
+    // The handler is executed from the context of modbus controller event task and should be as simple as possible.
+    // Parameters: frame_ptr - the pointer to the incoming ADU request frame from master starting from function code,
+    // plen - the pointer to length of the frame. The handler body can override the buffer and return the length of data.
+    // After return from the handler the modbus object will handle the end of transaction according to the exception returned,
+    // then builds the response frame and send it back to the master. If the whole transaction time including the response
+    // latency exceeds the configured slave response time set in the master configuration the master will ignore the transaction.
     mb_exception_t my_custom_fc04_handler(void *pinst, uint8_t *frame_ptr, uint16_t *plen)
     {
-        MB_RETURN_ON_FALSE(frame_ptr && plen, MB_EX_CRITICAL, TAG,
-                                "incorrect frame buffer length");
-        return MB_EX_CRITICAL;
+        MB_RETURN_ON_FALSE(frame_ptr && plen, MB_EX_CRITICAL, TAG, "incorrect frame buffer length");
+        // Place the custom behavior to process the buffer here
+        if (pstandard_handler) {
+            exception = pstandard_handler(pinst, frame_ptr, plen); // invoke standard behavior with mapping
+        }
+        return exception;
     }
     ...
-    uint8_t override_command = 0x04;
-    // Reset the existing handler for the command
-    esp_err_t err = mbc_slave_set_handler(slave_handle, override_command, NULL);
-    MB_RETURN_ON_FALSE((err == ESP_OK), ;, TAG,
-                          "could not reset handler, returned (0x%x).", (int)err);
+    const uint8_t override_command = 0x04;
+    // Get the standard handler for the command to use it in the handler.
+    err = mbc_get_handler(master_handle, override_command, &pstandard_handler);
+    MB_RETURN_ON_FALSE((err == ESP_OK), ESP_ERR_INVALID_STATE, TAG,
+                            "could not get handler for command %d, returned (0x%x).", (int)override_command, (int)err);
     // Set the custom handler function for the command
-    err = mbc_slave_set_handler(slave_handle, override_command, my_custom_fc04_handler);
+    err = mbc_set_handler(slave_handle, override_command, my_custom_fc04_handler);
     MB_RETURN_ON_FALSE((err == ESP_OK), ;, TAG,
                         "could not override handler, returned (0x%x).", (int)err);
     mb_fn_handler_fp phandler = NULL;
-    // Get the actual handler for the command
-    err = mbc_slave_get_handler(slave_handle, override_command, &phandler);
+    // Check the actual handler for the command
+    err = mbc_get_handler(slave_handle, override_command, &phandler);
     MB_RETURN_ON_FALSE((err == ESP_OK && phandler == my_custom_fc04_handler), ;, TAG,
                           "could not get handler, returned (0x%x).", (int)err);
 
-.. note:: The custom handlers set by the function :cpp:func:`mbc_slave_set_handler` should be as short as possible and should contain simple logic to not break the normal functionality of the stack. This is user application responsibility to handle the command appropriately.
+Refer to :ref:`example Serial slave <example_mb_slave>` for more information.
+
+.. note:: The custom handlers set by the function :cpp:func:`mbc_set_handler` should be as short as possible, contain simple and safe logic and avoid blocking calls to not break the normal functionality of the stack. The possible latency in this handler may prevent to respond properly to the master request which waits for response during the slave response time configured in the configuration structure. If the slave does not respond to the master during the slave response time the master will report timeout failure and ignores the late response. This is user application responsibility to handle the command appropriately.
 
 .. _modbus_api_slave_communication: