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

Support to get a character from standard input devices.
static shell_status_t SHELL_GetChar(shell_context_handle_t *shellContextHandle, uint8_t *ch);

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

name	The 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

command	The command string of the command. The double quotes do not need. Such as exit for "exit", help for "Help", read for "read".
descriptor	The description of the command is used for showing the command usage when "help" is typing.
callback	The callback of the command is used to handle the command line when the input command is matched.
paramCount	The 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

command The 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

enum shell_status_t

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

shellHandle	Pointer 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))];
serialHandle	The serial manager module handle pointer.
prompt	The string prompt pointer of Shell. Only the global variable can be passed.

Return values

kStatus_SHELL_Success	The shell initialization succeed.
kStatus_SHELL_Error	An error occurred when the shell is initialized.
kStatus_SHELL_OpenWriteHandleFailed	Open the write handle failed.
kStatus_SHELL_OpenReadHandleFailed	Open 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

shellHandle	The shell module handle pointer.
shellCommand	The command element.

Return values

kStatus_SHELL_Success	Successfully register the command.
kStatus_SHELL_Error	An error occurred.

shell_status_t SHELL_UnregisterCommand ( shell_command_t * shellCommand )

This function is used to unregister the shell command.

Parameters

shellCommand The command element.

Return values

kStatus_SHELL_Success Successfully 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

shellHandle	The shell module handle pointer.
buffer	Start address of the data to write.
length	Length of the data to write.

Return values

kStatus_SHELL_Success	Successfully send data.
kStatus_SHELL_Error	An 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

shellHandle	The shell module handle pointer.
formatString	Format 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

shellHandle The shell module handle pointer.

Overview

Function groups

Initialization

Advanced Feature

Shell Operation

Data Structures

Macros

Typedefs

Enumerations

Shell functional operation

Data Structure Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation