Custom commands

General Description

The DFU protocol provides a set of pre-defined commands.

The user can also add custom commands and register the single handler for all custom commands at the application level. This allows to adjust use case scenarios per the product needs. The feature is enabled with CY_DFU_OPT_CUSTOM_CMD set to non-zero value in the dfu_user.h or project Makefile.

Note

Custom commands only extend the functionality of the DFU command protocol and must be issued after entering the updating state (CY_DFU_STATE_UPDATING).

The user commands area preserved in the DFU command protocol:

• CY_DFU_USER_CMD_START
• CY_DFU_USER_CMD_END

An example of the custom commands usage:

1. Add a set of the custom commands to the project.

   /* Custom Commands definition */
   #define USR_CMD_STATUS_OK       (CY_DFU_USER_CMD_START + 1U)
   #define USR_CMD_STATUS_ERR      (CY_DFU_USER_CMD_START + 2U)

2. Define the function to handle the custom commands.

   Note

   A single function is used as the handler for all custom commands.

   /* Common handler declaration for Custom Commands */
   cy_en_dfu_status_t UserCommandHandler(uint32_t command, uint8_t  *packetData, uint32_t dataSize,  uint32_t *rspSize,
                                           struct cy_stc_dfu_params_s *params, bool *noResponse);

   /* Common handler definition for Custom Commands */
   cy_en_dfu_status_t UserCommandHandler(uint32_t command, uint8_t  *packetData, uint32_t dataSize,  uint32_t *rspSize,
                                           struct cy_stc_dfu_params_s *params, bool *noResponse)
   {
       cy_en_dfu_status_t status = CY_DFU_ERROR_UNKNOWN;
   
       /* Custom Commands handling */
       switch (command)
       {
           case USR_CMD_STATUS_OK:
           {
               /* STATUS OK action here */
               (void)params;
   
               *noResponse = true;
               status = CY_DFU_SUCCESS;
           }
           break;
   
           case USR_CMD_STATUS_ERR:
           {
               if (dataSize == 1U)
               {
                   /* STATUS ERR action here */
                   packetData[0U] = 1U;
                   *rspSize = 1U;
                   status = CY_DFU_SUCCESS;
               }
               else
               {
                   status = CY_DFU_ERROR_LENGTH;
               }
           }
           break;
   
           default:
           {
               /* Error handling */
               status = CY_DFU_ERROR_CMD;
           }
           break;
       }
   
       return status;
   }

3. Register the function to handle custom commands as a callback in the DFU core before use.

       /* Common handler register for Custom Commands */
       dfuStatus = Cy_DFU_RegisterUserCommand(&dfuParams, UserCommandHandler);

4. Release the callback function when custom command handling is no longer required.

       /* Common handler unregister for Custom Commands */
       dfuStatus = Cy_DFU_UnRegisterUserCommand(&dfuParams);

Functions
cy_en_dfu_status_t	Cy_DFU_RegisterUserCommand (cy_stc_dfu_params_t *params, Cy_DFU_CustomCommandHandler handler)
	Registering user commands handler. More...
cy_en_dfu_status_t	Cy_DFU_UnRegisterUserCommand (cy_stc_dfu_params_t *params)
	Unregisters user commands handling. More...

Function Documentation

Cy_DFU_RegisterUserCommand()

cy_en_dfu_status_t Cy_DFU_RegisterUserCommand	(	cy_stc_dfu_params_t *	params,
		Cy_DFU_CustomCommandHandler	handler
	)

Registering user commands handler.

Parameters

params	The pointer to a DFU parameters structure. See cy_stc_dfu_params_t.
handler	user command handler

Returns

See cy_en_dfu_status_t

Cy_DFU_UnRegisterUserCommand()

cy_en_dfu_status_t Cy_DFU_UnRegisterUserCommand

(

cy_stc_dfu_params_t *

params

)

Unregisters user commands handling.

Parameters

params

The pointer to a DFU parameters structure. See cy_stc_dfu_params_t.

Returns

See cy_en_dfu_status_t