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.
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>");
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".
uint8_t shell_command_t::cExpectedNumberOfParameters |
#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_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,
- 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". |
Enumerator |
---|
kStatus_SHELL_Success |
Success.
|
kStatus_SHELL_Error |
Failed.
|
kStatus_SHELL_OpenWriteHandleFailed |
Open write handle failed.
|
kStatus_SHELL_OpenReadHandleFailed |
Open read handle failed.
|
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.
*
SHELL_Init(s_shellHandle, s_serialHandle,
"Test@SHELL>");
*
- Parameters
-
shellHandle | Pointer to point to a memory space of size SHELL_HANDLE_SIZE allocated by the caller. |
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. |
This function is used to register the shell command by using the command configuration #shell_command_config_t. This is a example,
- Parameters
-
shellHandle | The shell module handle pointer. |
command | The command element. |
- Return values
-
kStatus_SHELL_Success | Successfully register the command. |
kStatus_SHELL_Error | An error occurred. |
This function is used to unregister the shell command.
- Parameters
-
command | The command element. |
- Return values
-
kStatus_SHELL_Success | Successfully unregister the command. |
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.
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. |