| Table of Contents |
|---|
Before going into an example of µC/Shell usage, a few design concepts have to be explained. Since µC/Shell is not associated with any particular product, modules in need of a shell facility (such as µC/TELNETs) interact with it by means of an application callback function. This way, those modules are able to use or not to use the shell in a totally transparent manner.
...
µC/Shell commands (i.e., commands placed in a ‘command table’) all have this prototype:
where ‘ argc ’ is a count of the arguments supplied and ‘ argv ’, an array of pointers to the strings which are those arguments. As for the return value, it is command specific, and will be used as the return value for the Shell_Exec() function. However, in case of an error, SHELL_EXEC_ERR should be returned.
Commands are also defined by the SHELL_CMD_FNCT data type:
s mentioned in the preceding section, each command is responsible for responding to its requester, and this is done with the help of the last parameter: the pointer to the output function. This function has the following prototype:
where ‘pbuf’ is a pointer to a response buffer having a length of ‘buf_len’. The third parameter, ‘popt’, is an optional argument used to provide implementation specific information (port number, UART identification, etc.). As for the return value, it is suggested to return the number of data octets transmitted, SHELL_OUT_RTN_CODE_CONN_CLOSED if the link has been closed, and SHELL_OUT_ERR for any other error.
The output function is also defined by a data type, SHELL_OUT_FNCT:
Finally the ‘ pcmd_param ’ is used to pass additional information to the command. The current implementation has provision for the current working directory, as well as an option parameter used by the output function:
Note that future implementation could add members to this structure to support more parameters.
µC/Shell Startup Code
We provide you with an example (i.e the application code) use of µC/Shell which is found in app.c and it was written to provide a startup example on how to use the capabilities of the µC/Shell module. app.c simply initializes µC/OS?II, µC/TCP-IP and µC/Shell, and creates a few tasks and other kernel objects that will give the user information about the state of the system. Note that you DO NOT need an RTOS like µC/OS?II or a TCP/IP stack like µC/TCP-IP to use µC/Shell.
...
This section of the manual will give you some examples of the above steps. Note that some sections of the source code have been removed or modified to help focus on the µC/Shell module use.
µC/Shell Example Use
Listing 3-4 - Example use
void App_TestShell (void)
{
SHELL_ERR err;
SHELL_CMD_PARAM cmd_param;
#if APP_FS_EN
FS_DIR *pdir;
#endif
APP_TRACE_DEBUG(("Testing Shell, executing command ...\n\r"));
#if APP_FS_EN
pdir = FS_OpenDir("");
cmd_param.pcur_working_dir = (void *)pdir;
#else
cmd_param.pcur_working_dir = (void *)0;
#endif
cmd_param.pout_opt = (void *)0;
Shell_Exec( "App_test -a -b -c", &App_TestShellOut, &err); (1)
switch (err) {
case SHELL_ERR_NONE:
APP_TRACE_DEBUG(("Command executed, no error.\n\r"));
break;
case SHELL_ERR_NULL_PTR:
APP_TRACE_DEBUG(("Error, NULL pointer passed.\n\r"));
break;
case SHELL_ERR_CMD_NOT_FOUND:
APP_TRACE_DEBUG(("Error, command NOT found.\n\r"));
break;
case SHELL_ERR_CMD_SEARCH:
APP_TRACE_DEBUG(("Error, searching command.\n\r"));
break;
case SHELL_ERR_ARG_TBL_FULL:
APP_TRACE_DEBUG(("Error, too many arguments\n\r"));
break;
default:
break;
}
}
L3-4(1) Invoke Once μC/Shell has been initialized, the only thing left to do it to call the Shell_Exec() function responsible for parsing and calling the specified command. In this case, passing ‘App_Test’ will result in the function App_TestCmd() to be called (see L2?3(1)).
...
, like depicted above.
µC/Shell Module Configuration
The µC/Shell module has to be configured according to your specific needs. A template configuration file (shell_cfg.h) is included in the module package (see Chapter 1, Directories and Files), and this file should be copied and added to your project. Here is the list of the values and description for each of the configuration variable. However, keep in mind that future releases of this module might include more configuration options.
...