Command Interpreter

Introduction

The Command Interpreter provides structures and functions for parsing incoming messages.

Features:

• allows dynamic adding and removing of MessageId Table
• calls the belonging handler function

The application provides a MessageId Table which contains all supported MessageIds together with their belonging handler functions. The MessageId Table is an array of Ucs_Cmd_MsgId_t elements. Each element contains a MessageId (0x0000 .. 0xFFFE) and a pointer to the belonging handler function. The table ends with the termination entry {UCS_CMD_MSGID_TERMINATION, NULL}.

Usage

The application announces the MessageId Table with the function Ucs_Cmd_AddMsgIdTable(). The connection to the MessageId Table can be removed with the function Ucs_Cmd_RemoveMsgIdTable().

A received message is given to Ucs_Cmd_DecodeMsg(). This function retrieves the MessageId from the message and calls the belonging handler function. The handler function can return three values:

Value	Description
UCS_CMD_RET_SUCCESS	The handler function succeeded.
UCS_CMD_RET_ERR_TX_BUSY	The handler function could not send an answer because no free Tx Buffer was available.
UCS_CMD_RET_ERR_APPL	An error happened in handler function.

Example

The following code example shows how the Command Interpreter API function can be used:

Ucs_Cmd_MsgId_t App_MsgIdTable[] = 
{
    { 0x1234U,                   App_Handler_1234},
    { 0x1238U,                   App_Handler_1238},
    { UCS_CMD_MSGID_TERMINATION, NULL            } 
};


void main(uint8_t argc, char *argv[])
{
    ...
    
    Ucs_Cmd_AddMsgIdTable(ucs_inst_ptr, &App_MsgIdTable[0]);
        
    ...
    
    while(1)
    {
        Ucs_AmsRx_Msg_t *msg_rx_ptr = Ucs_AmsRx_PeekMsg(ucs_inst_ptr);
        if (msg_rx_ptr != NULL)
        {
            Ucs_Cmd_Return_t cmd_ret;

            cmd_ret = Ucs_Cmd_DecodeMsg(ucs_inst_ptr, msg_rx_ptr);
            if (cmd_ret == UCS_CMD_RET_SUCCESS)
            {
                Ucs_AmsRx_ReleaseMsg(ucs_inst_ptr);
            }
            else
            {
                /* appropriate error handling */ 
            }
        }
    }
 }

Ucs_Cmd_Return_t App_Handler_1234(Ucs_AmsRx_Msg_t *msg_rx_ptr, void *user_ptr)  
{
    uint16_t cnt;
    
    /* print source address */
    (void)printf("App_Handler_1234() called from 0x%04X.\n", msg_rx_ptr->source_address);
    
    /* print payload */
    (void)printf("  Payload: ");
    for (cnt = 0U; cnt < msg_rx_ptr->data_size; cnt++)
    {
        (void)printf("%02X ", msg_rx_ptr->data_ptr[cnt]);
    }
    (void)printf("\n");
    
    return UCS_CMD_RET_SUCCESS;
}

Ucs_Cmd_Return_t App_Handler_1238(Ucs_AmsRx_Msg_t *msg_rx_ptr, void *user_ptr)  
{
    uint16_t cnt;
    
    /* print source address */
    (void)printf("App_Handler_1238() called from 0x%04X.\n", msg_rx_ptr->source_address);
    
    /* print payload */
    (void)printf("  Payload: ");
    for (cnt = 0U; cnt < msg_rx_ptr->data_size; cnt++)
    {
        (void)printf("%02X ", msg_rx_ptr->data_ptr[cnt]);
    }
    (void)printf("\n");
    
    return UCS_CMD_RET_SUCCESS;
}