MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Shell

Overview

This section describes the programming interface of the Shell middleware.

Shell controls MCUs by commands via the specified communication peripheral based on the debug console driver.

Function groups

Initialization

To initialize the Shell middleware, call the SHELL_Init() function with these parameters. This function automatically enables the middleware.

shell_status_t SHELL_Init(shell_handle_t shellHandle, serial_handle_t serialHandle, char *prompt);

Then, after the initialization was successful, call a command to control MCUs.

This example shows how to call the SHELL_Init() given the user configuration structure.

SHELL_Init(s_shellHandle, s_serialHandle, "Test@SHELL>");

Advanced Feature

Commands Description
help List all the registered commands.
exit Exit program.

Shell Operation

SHELL_Init(s_shellHandle, s_serialHandle, "Test@SHELL>");
SHELL_Task((s_shellHandle);

Data Structures

struct  shell_command_t
 User command data configuration structure. More...
 

Macros

#define SHELL_NON_BLOCKING_MODE   SERIAL_MANAGER_NON_BLOCKING_MODE
 Whether use non-blocking mode. More...
 
#define SHELL_AUTO_COMPLETE   (1U)
 Macro to set on/off auto-complete feature. More...
 
#define SHELL_BUFFER_SIZE   (64U)
 Macro to set console buffer size. More...
 
#define SHELL_MAX_ARGS   (8U)
 Macro to set maximum arguments in command. More...
 
#define SHELL_HISTORY_COUNT   (3U)
 Macro to set maximum count of history commands. More...
 
#define SHELL_IGNORE_PARAMETER_COUNT   (0xFF)
 Macro to bypass arguments check.
 
#define SHELL_HANDLE_SIZE   (520U)
 The handle size of the shell module. More...
 
#define SHELL_USE_COMMON_TASK   (1U)
 Macro to determine whether use common task. More...
 
#define SHELL_TASK_PRIORITY   (2U)
 Macro to set shell task priority. More...
 
#define SHELL_TASK_STACK_SIZE   (1000U)
 Macro to set shell task stack size. More...
 
#define SHELL_HANDLE_DEFINE(name)   uint32_t name[((SHELL_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]
 Defines the shell handle. More...
 
#define SHELL_COMMAND_DEFINE(command, descriptor, callback, paramCount)
 Defines the shell command structure. More...
 
#define SHELL_COMMAND(command)   &g_shellCommand##command
 Gets the shell command pointer. More...
 

Typedefs

typedef void * shell_handle_t
 The handle of the shell module.
 
typedef shell_status_t(* cmd_function_t )(shell_handle_t shellHandle, int32_t argc, char **argv)
 User command function prototype. More...
 

Enumerations

enum  shell_status_t {
  kStatus_SHELL_Success = kStatus_Success,
  kStatus_SHELL_Error = MAKE_STATUS(kStatusGroup_SHELL, 1),
  kStatus_SHELL_OpenWriteHandleFailed = MAKE_STATUS(kStatusGroup_SHELL, 2),
  kStatus_SHELL_OpenReadHandleFailed = MAKE_STATUS(kStatusGroup_SHELL, 3)
}
 Shell status. More...
 

Shell functional operation

shell_status_t SHELL_Init (shell_handle_t shellHandle, serial_handle_t serialHandle, char *prompt)
 Initializes the shell module. More...
 
shell_status_t SHELL_RegisterCommand (shell_handle_t shellHandle, shell_command_t *shellCommand)
 Registers the shell command. More...
 
shell_status_t SHELL_UnregisterCommand (shell_command_t *shellCommand)
 Unregisters the shell command. More...
 
shell_status_t SHELL_Write (shell_handle_t shellHandle, char *buffer, uint32_t length)
 Sends data to the shell output stream. More...
 
int SHELL_Printf (shell_handle_t shellHandle, const char *formatString,...)
 Writes formatted output to the shell output stream. More...
 
void SHELL_Task (shell_handle_t shellHandle)
 The task function for Shell. More...
 

Data Structure Documentation

struct shell_command_t

Data Fields

const char * pcCommand
 The command that is executed. More...
 
char * pcHelpString
 String that describes how to use the command. More...
 
const cmd_function_t pFuncCallBack
 A pointer to the callback function that returns the output generated by the command. More...
 
uint8_t cExpectedNumberOfParameters
 Commands expect a fixed number of parameters, which may be zero. More...
 
list_element_t link
 link of the element
 

Field Documentation

const char* shell_command_t::pcCommand

For example "help". It must be all lower case.

char* shell_command_t::pcHelpString

It should start with the command itself, and end with "\r\n". For example "help: Returns a list of all the commands\r\n".

const cmd_function_t shell_command_t::pFuncCallBack
uint8_t shell_command_t::cExpectedNumberOfParameters

Macro Definition Documentation

#define SHELL_NON_BLOCKING_MODE   SERIAL_MANAGER_NON_BLOCKING_MODE
#define SHELL_AUTO_COMPLETE   (1U)
#define SHELL_BUFFER_SIZE   (64U)
#define SHELL_MAX_ARGS   (8U)
#define SHELL_HISTORY_COUNT   (3U)
#define SHELL_HANDLE_SIZE   (520U)

It is the sum of the SHELL_HISTORY_COUNT * SHELL_BUFFER_SIZE + SHELL_BUFFER_SIZE + SERIAL_MANAGER_READ_HANDLE_SIZE + SERIAL_MANAGER_WRITE_HANDLE_SIZE

#define SHELL_USE_COMMON_TASK   (1U)
#define SHELL_TASK_PRIORITY   (2U)
#define SHELL_TASK_STACK_SIZE   (1000U)
#define SHELL_HANDLE_DEFINE (   name)    uint32_t name[((SHELL_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]

This macro is used to define a 4 byte aligned shell handle. Then use "(shell_handle_t)name" to get the shell handle.

The macro should be global and could be optional. You could also define shell handle by yourself.

This is an example,

* SHELL_HANDLE_DEFINE(shellHandle);
*
Parameters
nameThe name string of the shell handle.
#define SHELL_COMMAND_DEFINE (   command,
  descriptor,
  callback,
  paramCount 
)
Value:
\
shell_command_t g_shellCommand##command = { \
(#command), (descriptor), (callback), (paramCount), {0}, \
}

This macro is used to define the shell command structure shell_command_t. And then uses the macro SHELL_COMMAND to get the command structure pointer. The macro should not be used in any function.

This is a example,

* SHELL_COMMAND_DEFINE(exit, "\r\n\"exit\": Exit program\r\n", SHELL_ExitCommand, 0);
* SHELL_RegisterCommand(s_shellHandle, SHELL_COMMAND(exit));
*
Parameters
commandThe command string of the command. The double quotes do not need. Such as exit for "exit", help for "Help", read for "read".
descriptorThe description of the command is used for showing the command usage when "help" is typing.
callbackThe callback of the command is used to handle the command line when the input command is matched.
paramCountThe max parameter count of the current command.
#define SHELL_COMMAND (   command)    &g_shellCommand##command

This macro is used to get the shell command pointer. The macro should not be used before the macro SHELL_COMMAND_DEFINE is used.

Parameters
commandThe command string of the command. The double quotes do not need. Such as exit for "exit", help for "Help", read for "read".

Typedef Documentation

typedef shell_status_t(* cmd_function_t)(shell_handle_t shellHandle, int32_t argc, char **argv)

Enumeration Type Documentation

Enumerator
kStatus_SHELL_Success 

Success.

kStatus_SHELL_Error 

Failed.

kStatus_SHELL_OpenWriteHandleFailed 

Open write handle failed.

kStatus_SHELL_OpenReadHandleFailed 

Open read handle failed.

Function Documentation

shell_status_t SHELL_Init ( shell_handle_t  shellHandle,
serial_handle_t  serialHandle,
char *  prompt 
)

This function must be called before calling all other Shell functions. Call operation the Shell commands with user-defined settings. The example below shows how to set up the Shell and how to call the SHELL_Init function by passing in these parameters. This is an example.

* static SHELL_HANDLE_DEFINE(s_shellHandle);
* SHELL_Init((shell_handle_t)s_shellHandle, (serial_handle_t)s_serialHandle, "Test@SHELL>");
*
Parameters
shellHandlePointer to point to a memory space of size SHELL_HANDLE_SIZE allocated by the caller. The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. You can define the handle in the following two ways: SHELL_HANDLE_DEFINE(shellHandle); or uint32_t shellHandle[((SHELL_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))];
serialHandleThe serial manager module handle pointer.
promptThe string prompt pointer of Shell. Only the global variable can be passed.
Return values
kStatus_SHELL_SuccessThe shell initialization succeed.
kStatus_SHELL_ErrorAn error occurred when the shell is initialized.
kStatus_SHELL_OpenWriteHandleFailedOpen the write handle failed.
kStatus_SHELL_OpenReadHandleFailedOpen the read handle failed.
shell_status_t SHELL_RegisterCommand ( shell_handle_t  shellHandle,
shell_command_t shellCommand 
)

This function is used to register the shell command by using the command configuration shell_command_config_t. This is a example,

* SHELL_COMMAND_DEFINE(exit, "\r\n\"exit\": Exit program\r\n", SHELL_ExitCommand, 0);
* SHELL_RegisterCommand(s_shellHandle, SHELL_COMMAND(exit));
*
Parameters
shellHandleThe shell module handle pointer.
shellCommandThe command element.
Return values
kStatus_SHELL_SuccessSuccessfully register the command.
kStatus_SHELL_ErrorAn error occurred.
shell_status_t SHELL_UnregisterCommand ( shell_command_t shellCommand)

This function is used to unregister the shell command.

Parameters
shellCommandThe command element.
Return values
kStatus_SHELL_SuccessSuccessfully unregister the command.
shell_status_t SHELL_Write ( shell_handle_t  shellHandle,
char *  buffer,
uint32_t  length 
)

This function is used to send data to the shell output stream.

Parameters
shellHandleThe shell module handle pointer.
bufferStart address of the data to write.
lengthLength of the data to write.
Return values
kStatus_SHELL_SuccessSuccessfully send data.
kStatus_SHELL_ErrorAn error occurred.
int SHELL_Printf ( shell_handle_t  shellHandle,
const char *  formatString,
  ... 
)

Call this function to write a formatted output to the shell output stream.

Parameters
shellHandleThe shell module handle pointer.
formatStringFormat string.
Returns
Returns the number of characters printed or a negative value if an error occurs.
void SHELL_Task ( shell_handle_t  shellHandle)

The task function for Shell; The function should be polled by upper layer. This function does not return until Shell command exit was called.

Parameters
shellHandleThe shell module handle pointer.