Mistake on this page?
Report an issue in GitHub or email us
Macros | Typedefs | Functions
ns_cmdline.h File Reference

Command line library - mbedOS shell. More...

#include <stdarg.h>
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

Go to the source code of this file.

Macros

#define CMDLINE_RETCODE_COMMAND_BUSY   2
 Command Busy. More...
 
#define CMDLINE_RETCODE_EXCUTING_CONTINUE   1
 Execution continue in background. More...
 
#define CMDLINE_RETCODE_SUCCESS   0
 Execution Success. More...
 
#define CMDLINE_RETCODE_FAIL   -1
 Execution Fail. More...
 
#define CMDLINE_RETCODE_INVALID_PARAMETERS   -2
 Command parameters was incorrect. More...
 
#define CMDLINE_RETCODE_COMMAND_NOT_IMPLEMENTED   -3
 Command not implemented. More...
 
#define CMDLINE_RETCODE_COMMAND_CB_MISSING   -4
 Command callback function missing. More...
 
#define CMDLINE_RETCODE_COMMAND_NOT_FOUND   -5
 Command not found. More...
 

Typedefs

typedef void( cmd_print_t) (const char *, va_list)
 typedef for print functions More...
 
typedef void( cmd_ready_cb_f) (int)
 typedef for ready cb function More...
 
typedef int( cmd_run_cb) (int argc, char *argv[])
 Callback called when your command is run. More...
 

Functions

void cmd_init (cmd_print_t *outf)
 Initialize cmdline class. More...
 
void cmd_ready (int retcode)
 Command ready function for special cases. More...
 
void cmd_set_ready_cb (cmd_ready_cb_f *cb)
 Configure cb which will be called after commands are executed or cmd_ready is called. More...
 
void cmd_next (int retcode)
 execute next command if any More...
 
void cmd_free (void)
 Free cmd class. More...
 
void cmd_reset (void)
 Reset cmdline to default values detach external commands, delete all variables and aliases. More...
 
uint8_t cmd_history_size (uint8_t max)
 Configure command history size (default 32) More...
 
void cmd_printf (const char *fmt,...)
 command line print function This function should be used when user want to print something to the console More...
 
void cmd_vprintf (const char *fmt, va_list ap)
 command line print function This function should be used when user want to print something to the console with vprintf functionality More...
 
void cmd_out_func (cmd_print_t *outf)
 Reconfigure default cmdline out function (cmd_printf) More...
 
void cmd_ctrl_func (void(*sohf)(uint8_t c))
 Configure function, which will be called when Ctrl+A is pressed. More...
 
void cmd_mutex_wait_func (void(*mutex_wait_f)(void))
 Configure mutex wait function By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output. More...
 
void cmd_mutex_release_func (void(*mutex_release_f)(void))
 Configure mutex wait function By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output. More...
 
void cmd_mutex_lock (void)
 Retrieve output mutex lock This can be used to retrieve the output mutex when multiple cmd_printf/cmd_vprintf calls must be guaranteed to be grouped together in a thread safe manner. More...
 
void cmd_mutex_unlock (void)
 Release output mutex lock This can be used to release the output mutex once it has been retrieved with cmd_mutex_lock() Exact behaviour depends on the implementation of the configured mutex, but counting mutexes are required. More...
 
void cmd_output (void)
 Refresh output. More...
 
void default_cmd_response_out (const char *fmt, va_list ap)
 default cmd response function, use stdout More...
 
void cmd_init_screen (void)
 Initialize screen. More...
 
bool cmd_echo_state (void)
 Get echo state. More...
 
void cmd_echo_off (void)
 Echo off. More...
 
void cmd_echo_on (void)
 Echo on. More...
 
void cmd_char_input (int16_t u_data)
 Enter character to console. More...
 
void cmd_add (const char *name, cmd_run_cb *callback, const char *info, const char *man)
 Add command to intepreter. More...
 
void cmd_delete (const char *name)
 delete command from intepreter More...
 
void cmd_exe (char *str)
 Command executer. More...
 
void cmd_alias_add (const char *alias, const char *value)
 Add alias to interpreter. More...
 
void cmd_variable_add (char *variable, char *value)
 Add Variable to interpreter. More...
 
void cmd_variable_add_int (char *variable, int value)
 Add integer variable to interpreter. More...
 
void cmd_request_screen_size (void)
 Request screen size from host Response are stored to variables: COLUMNS and LINES - as integer values. More...
 
int cmd_parameter_index (int argc, char *argv[], const char *key)
 find command parameter index by key. More...
 
bool cmd_has_option (int argc, char *argv[], const char *key)
 check if command option is present. More...
 
bool cmd_parameter_bool (int argc, char *argv[], const char *key, bool *value)
 find command parameter by key. More...
 
bool cmd_parameter_val (int argc, char *argv[], const char *key, char **value)
 find command parameter by key and return value (next parameter). More...
 
bool cmd_parameter_int (int argc, char *argv[], const char *key, int32_t *value)
 find command parameter by key and return value (next parameter) in integer. More...
 
bool cmd_parameter_float (int argc, char *argv[], const char *key, float *value)
 find command parameter by key and return value (next parameter) in float. More...
 
char * cmd_parameter_last (int argc, char *argv[])
 Get last command line parameter as string. More...
 
bool cmd_parameter_timestamp (int argc, char *argv[], const char *key, int64_t *value)
 find command parameter by key and return value (next parameter) in int64. More...
 

Detailed Description

Command line library - mbedOS shell.

Usage example:

//simple print function
void myprint(const char* fmt, va_list ap){ vprintf(fmt, ap); }
// simple ready cb, which call next command to be execute
void cmd_ready_cb(int retcode) { cmd_next( retcode ); }
// dummy command with some option
int cmd_dummy(int argc, char *argv[]){
if( cmd_has_option(argc, argv, "o") ) {
cmd_printf("This is o option");
} else {
}
}
// timer cb ( pseudo-timer-code )
void timer_ready_cb(void) {
}
// long command, which need e.g. some events to finalize command execution
int cmd_long(int argc, char *argv[] ) {
timer_start( 5000, timer_ready_cb );
}
void main(void) {
cmd_init( &myprint ); // initialize cmdline with print function
cmd_set_ready_cb( cmd_ready_cb ); // configure ready cb
cmd_add("dummy", cmd_dummy, 0, 0); // add one dummy command
cmd_add("long", cmd_long, 0, 0); // add one dummy command
//execute dummy and long commands
cmd_exe( "dymmy;long" );
}

Definition in file ns_cmdline.h.

Macro Definition Documentation

#define CMDLINE_RETCODE_COMMAND_BUSY   2

Command Busy.

Definition at line 70 of file ns_cmdline.h.

#define CMDLINE_RETCODE_COMMAND_CB_MISSING   -4

Command callback function missing.

Definition at line 76 of file ns_cmdline.h.

#define CMDLINE_RETCODE_COMMAND_NOT_FOUND   -5

Command not found.

Definition at line 77 of file ns_cmdline.h.

#define CMDLINE_RETCODE_COMMAND_NOT_IMPLEMENTED   -3

Command not implemented.

Definition at line 75 of file ns_cmdline.h.

#define CMDLINE_RETCODE_EXCUTING_CONTINUE   1

Execution continue in background.

Definition at line 71 of file ns_cmdline.h.

#define CMDLINE_RETCODE_FAIL   -1

Execution Fail.

Definition at line 73 of file ns_cmdline.h.

#define CMDLINE_RETCODE_INVALID_PARAMETERS   -2

Command parameters was incorrect.

Definition at line 74 of file ns_cmdline.h.

#define CMDLINE_RETCODE_SUCCESS   0

Execution Success.

Definition at line 72 of file ns_cmdline.h.

Typedef Documentation

typedef void( cmd_print_t) (const char *, va_list)

typedef for print functions

Definition at line 82 of file ns_cmdline.h.

typedef void( cmd_ready_cb_f) (int)

typedef for ready cb function

Definition at line 102 of file ns_cmdline.h.

typedef int( cmd_run_cb) (int argc, char *argv[])

Callback called when your command is run.

Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
argvargv is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.

Definition at line 231 of file ns_cmdline.h.

Function Documentation

void cmd_add ( const char *  name,
cmd_run_cb callback,
const char *  info,
const char *  man 
)

Add command to intepreter.

Parameters
namecommand string
callbackThis function is called when command line start executing
infoCommand short description which is visible in help command, or null if not in use
manHelp page for this command. This is shown when executing command with invalid parameters or command with –help parameter. Can be null if not in use.
void cmd_alias_add ( const char *  alias,
const char *  value 
)

Add alias to interpreter.

Aliases are replaced with values before executing a command. All aliases must be started from beginning of line. null or empty value deletes alias.

1 cmd_alias_add("print", "echo");
2 cmd_exe("print \"hello world!\""); // this is now same as "echo \"hello world!\"" .
Parameters
aliasalias name
valuevalue for alias. Values can be any visible ASCII -characters.
void cmd_char_input ( int16_t  u_data)

Enter character to console.

insert key pressess to cmdline called from main loop of application

Parameters
u_datachar to be added to console
void cmd_ctrl_func ( void(*)(uint8_t c)  sohf)

Configure function, which will be called when Ctrl+A is pressed.

Parameters
sohfcontrol function which called every time when user input control keys
void cmd_delete ( const char *  name)

delete command from intepreter

Parameters
namecommand to be delete
void cmd_echo_off ( void  )

Echo off.

void cmd_echo_on ( void  )

Echo on.

bool cmd_echo_state ( void  )

Get echo state.

Returns
true if echo is on otherwise false
void cmd_exe ( char *  str)

Command executer.

Command executer, which split&push command(s) to the buffer and start executing commands in cmd tasklet. if not, execute command directly. If command implementation returns CMDLINE_RETCODE_EXCUTING_CONTINUE, executor will wait for cmd_ready() before continue to next command.

Parameters
strcommand string, e.g. "help"
void cmd_free ( void  )

Free cmd class.

bool cmd_has_option ( int  argc,
char *  argv[],
const char *  key 
)

check if command option is present.

e.g. cmd: "mycmd -c"

1 bool on = cmd_has_option( argc, argv, "p" );
Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
keyoption key to be find
Returns
true if option found otherwise false
uint8_t cmd_history_size ( uint8_t  max)

Configure command history size (default 32)

Parameters
maxmaximum history size max > 0 -> configure new value max = 0 -> just return current value
Returns
current history max-size
void cmd_init ( cmd_print_t outf)

Initialize cmdline class.

This is command line editor without any commands. Application needs to add commands that should be enabled. usage e.g.

1 cmd_init( &default_cmd_response_out );
Parameters
outfconsole printing function (like vprintf)
void cmd_init_screen ( void  )

Initialize screen.

void cmd_mutex_lock ( void  )

Retrieve output mutex lock This can be used to retrieve the output mutex when multiple cmd_printf/cmd_vprintf calls must be guaranteed to be grouped together in a thread safe manner.

Must be released by a following call to cmd_mutex_unlock() For example:

  • 1 cmd_mutex_lock();
    2 for (i = 0; i < 10; i++) {
    3  cmd_printf("%02x ", i);
    4 }
    5 // without locking a print from another thread could happen here
    6 cmd_printf("\r\n);
    7 cmd_mutex_unlock();
    Exact behaviour depends on the implementation of the configured mutex, but counting mutexes are required.
void cmd_mutex_release_func ( void(*)(void)  mutex_release_f)

Configure mutex wait function By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.

This can be used to set a callback function that will be called after each cmd_printf call. The specific implementation is up to the application developer, but simple mutex locking is assumed.

void cmd_mutex_unlock ( void  )

Release output mutex lock This can be used to release the output mutex once it has been retrieved with cmd_mutex_lock() Exact behaviour depends on the implementation of the configured mutex, but counting mutexes are required.

void cmd_mutex_wait_func ( void(*)(void)  mutex_wait_f)

Configure mutex wait function By default, cmd_printf calls may not be thread safe, depending on the implementation of the used output.

This can be used to set a callback function that will be called before each cmd_printf call. The specific implementation is up to the application developer, but simple mutex locking is assumed.

void cmd_next ( int  retcode)

execute next command if any

Parameters
retcodelast command return value
void cmd_out_func ( cmd_print_t outf)

Reconfigure default cmdline out function (cmd_printf)

Parameters
outfselect console print function
void cmd_output ( void  )

Refresh output.

bool cmd_parameter_bool ( int  argc,
char *  argv[],
const char *  key,
bool *  value 
)

find command parameter by key.

if exists, return true, otherwise false. e.g. cmd: "mycmd enable 1"

1 int mycmd_command(int argc, char *argv[]) {
2  bool value;
3  bool found = cmd_parameter_bool( argc, argv, "mykey", &value );
4  if( found ) return CMDLINE_RETCODE_SUCCESS;
5  else return CMDLINE_RETCODE_FAIL;
6  }
Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
keyparameter key to be find
valueparameter value to be fetch, if key not found value are untouched. "1" and "on" and "true" and "enable" and "allow" are True -value, all others false.
Returns
true if parameter key and value found otherwise false
bool cmd_parameter_float ( int  argc,
char *  argv[],
const char *  key,
float *  value 
)

find command parameter by key and return value (next parameter) in float.

Only whitespaces are allowed in addition to the float to be read. e.g. cmd: "mycmd mykey myvalue"

1 float value;
2 cmd_parameter_float( argc, argv, "key", &value );
Parameters
argcargc is the count of arguments given in argv pointer list. values begin from 1 and this means that the item 0 in the list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
keyparameter key to be found
valueA pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
Returns
true if parameter key and a float found, otherwise return false
int cmd_parameter_index ( int  argc,
char *  argv[],
const char *  key 
)

find command parameter index by key.

e.g.

1 int main(void){
2  //..init cmd..
3  //..
4  cmd_exe("mycmd enable")
5 }
6 int mycmd_command(int argc, char *argv[]) {
7  bool found = cmd_parameter_index( argc, argv, "enable" ) > 0;
8 }
Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
keyoption key, which index you want to find out.
Returns
index where parameter was or -1 when not found
bool cmd_parameter_int ( int  argc,
char *  argv[],
const char *  key,
int32_t *  value 
)

find command parameter by key and return value (next parameter) in integer.

Only whitespaces are allowed in addition to the float to be read. e.g. cmd: "mycmd mykey myvalue"

1 int32_t value;
2 cmd_parameter_int( argc, argv, "key", &value );
Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the item 0 in the list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
keyparameter key to be found
valueA pointer to a variable where to write the converted number. If value cannot be converted, it is not touched.
Returns
true if parameter key and an integer is found, otherwise return false
char* cmd_parameter_last ( int  argc,
char *  argv[] 
)

Get last command line parameter as string.

e.g. cmd: "mycmd hello world" cmd_parameter_last -> "world" cmd: "mycmd" cmd_parameter_last() -> NULL

1 cmd_parameter_last(argc, argv)
Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
Returns
pointer to last parameter or NULL when there is no any parameters.
bool cmd_parameter_timestamp ( int  argc,
char *  argv[],
const char *  key,
int64_t *  value 
)

find command parameter by key and return value (next parameter) in int64.

e.g. cmd: "mycmd mykey myvalue"

1 uint32_t i;
2 cmd_parameter_timestamp( argc, argv, "mykey", &i );

Supports following formats: number -> direct conversion 11:22:33:44:55:66:77:88 -> converts to number seconds,tics -> converts thread type timestamp to int64

Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
keyparameter key to be find
valueparameter value to be fetch, if key not found value are untouched.
Returns
true if parameter key and value found otherwise false
bool cmd_parameter_val ( int  argc,
char *  argv[],
const char *  key,
char **  value 
)

find command parameter by key and return value (next parameter).

if exists, return parameter pointer, otherwise null. e.g. cmd: "mycmd mykey myvalue"

1 int mycmd_command(int argc, char *argv[]) {
2  char *value;
3  bool found = cmd_parameter_val( argc, argv, "mykey", &value );
4  if( found ) return CMDLINE_RETCODE_SUCCESS;
5  else return CMDLINE_RETCODE_FAIL;
6 }
Parameters
argcargc is the count of arguments given in argv pointer list. value begins from 1 and this means that the 0 item in list argv is a string to name of command.
argvis list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
keyparameter key to be find
valuepointer to pointer, which will point to cli input data when key and value found. if key or value not found this parameter are untouched.
Returns
true if parameter key and value found otherwise false
void cmd_printf ( const char *  fmt,
  ... 
)

command line print function This function should be used when user want to print something to the console

Parameters
fmtconsole print function (like printf)
void cmd_ready ( int  retcode)

Command ready function for special cases.

This need to be call if command implementation return CMDLINE_RETCODE_EXECUTING_CONTINUE because there is some background stuff ongoing before command is finally completed. Normally there is some event, which call cmd_ready().

Parameters
retcodereturn code for command
void cmd_request_screen_size ( void  )

Request screen size from host Response are stored to variables: COLUMNS and LINES - as integer values.

Note: Require terminal that handle request codes, like screen.

void cmd_reset ( void  )

Reset cmdline to default values detach external commands, delete all variables and aliases.

void cmd_set_ready_cb ( cmd_ready_cb_f cb)

Configure cb which will be called after commands are executed or cmd_ready is called.

Parameters
cbcallback function for command ready
void cmd_variable_add ( char *  variable,
char *  value 
)

Add Variable to interpreter.

Variables are replaced with values before executing a command. To use variables from cli, use dollar ($) -character so that interpreter knows user want to use variable in that place. null or empty value deletes variable.

1 cmd_variable_add("world", "hello world!");
2 cmd_exe("echo $world"); // this is now same as echo "hello world!" .
Parameters
variableVariable name, which will be replaced in interpreter.
valueValue for variable. Values can contains white spaces and '"' or '"' characters.
void cmd_variable_add_int ( char *  variable,
int  value 
)

Add integer variable to interpreter.

Variables are replaced with values before executing a command.

1 cmd_variable_add_int("world", 2);
2 cmd_exe("echo $world"); // this is now same as 'echo 2' .
Parameters
variableVariable name, which will be replaced in interpreter.
valueValue for variable
void cmd_vprintf ( const char *  fmt,
va_list  ap 
)

command line print function This function should be used when user want to print something to the console with vprintf functionality

Parameters
fmtThe format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives.
aplist of parameters needed by format string. This must correspond properly with the conversion specifier.
void default_cmd_response_out ( const char *  fmt,
va_list  ap 
)

default cmd response function, use stdout

Parameters
fmtThe format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives.
aplist of parameters needed by format string. This must correspond properly with the conversion specifier.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.