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

- 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 (6U)
| Macro to set maximum count of commands. More...

## 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 configure 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 (6U)

## 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: 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.