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

• Support to get a character from standard input devices.

  static uint8_t GetChar(p_shell_context_t context);

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_t *	CommandList [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

enum fun_key_status_t

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

context	The pointer to the Shell environment and runtime states.
send_cb	The pointer to call back send data function.
recv_cb	The pointer to call back receive data function.
prompt	The string prompt of Shell

int32_t SHELL_RegisterCommand

(

const shell_command_context_t *

command_context

)

Parameters

command_context

The 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

context

The pointer to the Shell environment and runtime states.

Returns

This function does not return until Shell command exit was called.