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.

void SHELL_Init(p_shell_context_t context, send_data_cb_t send_cb, recv_data_cb_t recv_cb, 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(&user_context, SHELL_SendDataCallback, SHELL_ReceiveDataCallback, "SHELL>> ");

Advanced Feature

Commands Description
Help Lists all commands which are supported by Shell.
Exit Exits the Shell program.
strCompare Compares the two input strings.
Input character Description
A Gets the latest command in the history.
B Gets the first command in the history.
C Replaces one character at the right of the pointer.
D Replaces one character at the left of the pointer.
Run AutoComplete function

Run cmdProcess function
Clears a command.

Shell Operation

SHELL_Init(&user_context, SHELL_SendDataCallback, SHELL_ReceiveDataCallback, "SHELL>> ");
SHELL_Main(&user_context);

Data Structures

struct  p_shell_context_t
 Data structure for Shell environment. More...
 
struct  shell_command_context_t
 User command data structure. More...
 
struct  shell_command_context_list_t
 Structure list command. More...
 

Macros

#define SHELL_USE_HISTORY   (0U)
 Macro to set on/off history feature. More...
 
#define SHELL_SEARCH_IN_HIST   (1U)
 Macro to set on/off history feature. More...
 
#define SHELL_USE_FILE_STREAM   (0U)
 Macro to select method stream. 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_HIST_MAX   (3U)
 Macro to set maximum count of history commands. More...
 
#define SHELL_MAX_CMD   (20U)
 Macro to set maximum count of commands. More...
 
#define SHELL_OPTIONAL_PARAMS   (0xFF)
 Macro to bypass arguments check.
 

Typedefs

typedef void(* send_data_cb_t )(uint8_t *buf, uint32_t len)
 Shell user send data callback prototype. More...
 
typedef void(* recv_data_cb_t )(uint8_t *buf, uint32_t len)
 Shell user receiver data callback prototype. More...
 
typedef int(* printf_data_t )(const char *format,...)
 Shell user printf data prototype. More...
 
typedef int32_t(* cmd_function_t )(p_shell_context_t context, int32_t argc, char **argv)
 User command function prototype. More...
 

Enumerations

enum  fun_key_status_t {
  kSHELL_Normal = 0U,
  kSHELL_Special = 1U,
  kSHELL_Function = 2U
}
 A type for the handle special key. More...
 

Shell functional operation

void SHELL_Init (p_shell_context_t context, send_data_cb_t send_cb, recv_data_cb_t recv_cb, printf_data_t shell_printf, char *prompt)
 Enables the clock gate and configures the Shell module according to the configuration structure. More...
 
int32_t SHELL_RegisterCommand (const shell_command_context_t *command_context)
 Shell register command. More...
 
int32_t SHELL_Main (p_shell_context_t context)
 Main loop for Shell. More...
 

Data Structure Documentation

struct shell_context_struct

Data Fields

char * prompt
 Prompt string.
 
enum _fun_key_status stat
 Special key status.
 
char line [SHELL_BUFFER_SIZE]
 Consult buffer.
 
uint8_t cmd_num
 Number of user commands.
 
uint8_t l_pos
 Total line position.
 
uint8_t c_pos
 Current line position.
 
send_data_cb_t send_data_func
 Send data interface operation.
 
recv_data_cb_t recv_data_func
 Receive data interface operation.
 
uint16_t hist_current
 Current history command in hist buff.
 
uint16_t hist_count
 Total history command in hist buff.
 
char hist_buf [SHELL_HIST_MAX][SHELL_BUFFER_SIZE]
 History buffer.
 
bool exit
 Exit Flag.
 
struct shell_command_context_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...
 

Field Documentation

const char* shell_command_context_t::pcCommand

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

char* shell_command_context_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_context_t::pFuncCallBack
uint8_t shell_command_context_t::cExpectedNumberOfParameters
struct shell_command_context_list_t

Data Fields

const shell_command_context_tCommandList [SHELL_MAX_CMD]
 The command table list.
 
uint8_t numberOfCommandInList
 The total command in list.
 

Macro Definition Documentation

#define SHELL_USE_HISTORY   (0U)
#define SHELL_SEARCH_IN_HIST   (1U)
#define SHELL_USE_FILE_STREAM   (0U)
#define SHELL_AUTO_COMPLETE   (1U)
#define SHELL_BUFFER_SIZE   (64U)
#define SHELL_MAX_ARGS   (8U)
#define SHELL_HIST_MAX   (3U)
#define SHELL_MAX_CMD   (20U)

Typedef Documentation

typedef void(* send_data_cb_t)(uint8_t *buf, uint32_t len)
typedef void(* recv_data_cb_t)(uint8_t *buf, uint32_t len)
typedef int(* printf_data_t)(const char *format,...)
typedef int32_t(* cmd_function_t)(p_shell_context_t context, int32_t argc, char **argv)

Enumeration Type Documentation

Enumerator
kSHELL_Normal 

Normal key.

kSHELL_Special 

Special key.

kSHELL_Function 

Function key.

Function Documentation

void SHELL_Init ( p_shell_context_t  context,
send_data_cb_t  send_cb,
recv_data_cb_t  recv_cb,
printf_data_t  shell_printf,
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 middleware Shell and how to call the SHELL_Init function by passing in these parameters. This is an example.

* shell_context_struct user_context;
* SHELL_Init(&user_context, SendDataFunc, ReceiveDataFunc, "SHELL>> ");
*
Parameters
contextThe pointer to the Shell environment and runtime states.
send_cbThe pointer to call back send data function.
recv_cbThe pointer to call back receive data function.
promptThe string prompt of Shell
int32_t SHELL_RegisterCommand ( const shell_command_context_t command_context)
Parameters
command_contextThe pointer to the command data structure.
Returns
-1 if error or 0 if success
int32_t SHELL_Main ( p_shell_context_t  context)

Main loop for Shell; After this function is called, Shell begins to initialize the basic variables and starts to work.

Parameters
contextThe pointer to the Shell environment and runtime states.
Returns
This function does not return until Shell command exit was called.