Command line library - mbedOS shell. More...

Typedefs
typedef void(	cmd_print_t )(const char *, va_list)
	typedef for print functions
typedef void(	cmd_ready_cb_f )(int)
	typedef for ready cb function
typedef int(	cmd_run_cb )(int argc, char *argv[])
	Callback called when your command is run.
Functions
void	cmd_init (cmd_print_t *outf)
	Initialize cmdline class.
void	cmd_ready (int retcode)
	Command ready function for __special__ cases.
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.
void	cmd_next (int retcode)
	execute next command if any
void	cmd_free (void)
	Free cmd class.
void	cmd_reset (void)
	Reset cmdline to default values detach external commands, delete all variables and aliases.
uint8_t	cmd_history_size (uint8_t max)
	Configure command history size (default 32)
void	cmd_printf (const char *fmt,...) __attribute__((__format__(__printf__
	command line print function This function should be used when user want to print something to the console
void	cmd_vprintf (const char *fmt, va_list ap) __attribute__((__format__(__printf__
	command line print function This function should be used when user want to print something to the console with vprintf functionality
void	cmd_out_func (cmd_print_t *outf)
	Reconfigure default cmdline out function (cmd_printf)
void	cmd_ctrl_func (void(*sohf)(uint8_t c))
	Configure function, which will be called when Ctrl+A is pressed.
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.
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.
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.
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_output (void)
	Refresh output.
void	default_cmd_response_out (const char *fmt, va_list ap)
	default cmd response function, use stdout
void	cmd_init_screen (void)
	Initialize screen.
bool	cmd_echo_state (void)
	Get echo state.
void	cmd_echo_off (void)
	Echo off.
void	cmd_echo_on (void)
	Echo on.
void	cmd_char_input (int16_t u_data)
	Enter character to console.
void	cmd_add (const char name, cmd_run_cb callback, const char info, const char man)
	Add command to intepreter.
void	cmd_delete (const char *name)
	delete command from intepreter
void	cmd_exe (char *str)
	Command executer.
void	cmd_alias_add (const char alias, const char value)
	Add alias to interpreter.
void	cmd_variable_add (char variable, char value)
	Add Variable to interpreter.
int	cmd_parameter_index (int argc, char argv[], const char key)
	find command parameter index by key.
bool	cmd_has_option (int argc, char argv[], const char key)
	check if command option is present.
bool	cmd_parameter_bool (int argc, char argv[], const char key, bool *value)
	find command parameter by key.
bool	cmd_parameter_val (int argc, char argv[], const char key, char **value)
	find command parameter by key and return value (next parameter).
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.
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.
char *	cmd_parameter_last (int argc, char *argv[])
	Get last command line parameter as string.
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.

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 {
    return CMDLINE_RETCODE_INVALID_PARAMETERS;
  }
  return CMDLINE_RETCODE_SUCCESS;
 *}
 // timer cb ( pseudo-timer-code )
 void timer_ready_cb(void) {
   cmd_ready(CMDLINE_RETCODE_SUCCESS);
 }
 // 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 );
   return CMDLINE_RETCODE_EXCUTING_CONTINUE;
 }
 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.

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:

argc	argc 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.
argv	argv 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:

name	command string
callback	This function is called when command line start executing
info	Command short description which is visible in help command, or null if not in use
man	Help 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.

Definition at line 636 of file ns_cmdline.c.

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.

   cmd_alias_add("print", "echo");
   cmd_exe("print \"hello world!\""); // this is now same as "echo \"hello world!\"" .

Parameters:

alias	alias name
value	value for alias. Values can be any visible ASCII -characters.

Definition at line 1435 of file ns_cmdline.c.

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_data char to be added to console

Definition at line 1030 of file ns_cmdline.c.

void cmd_ctrl_func ( void(*)(uint8_t c) sohf )

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

Parameters:

sohf	control function which called every time when user input control keys

Definition at line 523 of file ns_cmdline.c.

void cmd_delete ( const char * name )

delete command from intepreter

Parameters:

name	command to be delete

Definition at line 654 of file ns_cmdline.c.

void cmd_echo_off ( void )

Echo off.

Definition at line 1182 of file ns_cmdline.c.

void cmd_echo_on ( void )

Echo on.

Definition at line 1186 of file ns_cmdline.c.

bool cmd_echo_state ( void )

Get echo state.

Returns:: true if echo is on otherwise false

Definition at line 572 of file ns_cmdline.c.

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:

str	command string, e.g. "help"

Definition at line 365 of file ns_cmdline.c.

void cmd_free ( void )

Free cmd class.

Definition at line 340 of file ns_cmdline.c.

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

check if command option is present.

e.g. cmd: "mycmd -c"

    bool on = cmd_has_option( argc, argv, "p" );

Parameters:

argc	argc 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.
argv	is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
key	option key to be find

Returns:: true if option found otherwise false

Definition at line 1677 of file ns_cmdline.c.

uint8_t cmd_history_size ( uint8_t max )

Configure command history size (default 32)

Parameters:

max	maximum history size max > 0 -> configure new value max = 0 -> just return current value

Returns:: current history max-size

Definition at line 560 of file ns_cmdline.c.

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.

    cmd_init( &default_cmd_response_out );

Parameters:

outf	console printing function (like vprintf)

Definition at line 267 of file ns_cmdline.c.

void cmd_init_screen ( void )

Initialize screen.

Definition at line 551 of file ns_cmdline.c.

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: *

 cmd_mutex_lock();
   for (i = 0; i < 10; i++) {
       cmd_printf("%02x ", i);
   }
   // without locking a print from another thread could happen here
   cmd_printf("\r\n);
   cmd_mutex_unlock();

Exact behaviour depends on the implementation of the configured mutex, but counting mutexes are required.

Definition at line 537 of file ns_cmdline.c.

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.

Definition at line 532 of file ns_cmdline.c.

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.

Definition at line 544 of file ns_cmdline.c.

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.

Definition at line 528 of file ns_cmdline.c.

void cmd_next ( int retcode )

execute next command if any

Parameters:

retcode last command return value

Definition at line 405 of file ns_cmdline.c.

void cmd_out_func ( cmd_print_t * outf )

Reconfigure default cmdline out function (cmd_printf)

Parameters:

outf	select console print function

Definition at line 519 of file ns_cmdline.c.

void cmd_output ( void )

Refresh output.

Definition at line 1176 of file ns_cmdline.c.

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"

  int mycmd_command(int argc, char *argv[]) {
        bool value;
        bool found = cmd_parameter_bool( argc, argv, "mykey", &value );
        if( found ) return CMDLINE_RETCODE_SUCCESS;
        else return CMDLINE_RETCODE_FAIL;
    }

Parameters:

argc	argc 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.
argv	is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
key	parameter key to be find
value	parameter 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

Definition at line 1689 of file ns_cmdline.c.

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"

     float value;
     cmd_parameter_float( argc, argv, "key", &value );

Parameters:

argc	argc 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.
argv	is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
key	parameter key to be found
value	A 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

Definition at line 1738 of file ns_cmdline.c.

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

find command parameter index by key.

e.g.

      int main(void){
            //..init cmd..
            //..
            cmd_exe("mycmd enable")
      }
      int mycmd_command(int argc, char *argv[]) {
        bool found = cmd_parameter_index( argc, argv, "enable" ) > 0;
      }

Parameters:

argc	argc 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.
argv	is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
key	option key, which index you want to find out.

Returns:: index where parameter was or -1 when not found

Definition at line 1667 of file ns_cmdline.c.

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"

     int32_t value;
     cmd_parameter_int( argc, argv, "key", &value );

Parameters:

argc	argc 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.
argv	is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
key	parameter key to be found
value	A 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

Definition at line 1719 of file ns_cmdline.c.

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

    cmd_parameter_last(argc, argv)

Parameters:

argc	argc 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.
argv	is 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.

Definition at line 1823 of file ns_cmdline.c.

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"

     uint32_t i;
     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:

argc	argc 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.
argv	is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
key	parameter key to be find
value	parameter value to be fetch, if key not found value are untouched.

Returns:: true if parameter key and value found otherwise false

Definition at line 1789 of file ns_cmdline.c.

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"

    int mycmd_command(int argc, char *argv[]) {
        char *value;
        bool found = cmd_parameter_val( argc, argv, "mykey", &value );
        if( found ) return CMDLINE_RETCODE_SUCCESS;
        else return CMDLINE_RETCODE_FAIL;
    }

Parameters:

argc	argc 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.
argv	is list of arguments. List size is given in argc parameter. Value in argv[0] is string to name of command.
key	parameter key to be find
value	pointer 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

Definition at line 1708 of file ns_cmdline.c.

void 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:

fmt	console 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:

retcode return code for command

Definition at line 380 of file ns_cmdline.c.

void cmd_reset ( void )

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

Definition at line 335 of file ns_cmdline.c.

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:

cb	callback function for command ready

Definition at line 376 of file ns_cmdline.c.

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.

   cmd_variable_add("world", "hello world!");
   cmd_exe("echo $world"); // this is now same as echo "hello world!" .

Parameters:

variable	Variable name, which will be replaced in interpreter.
value	Value for variable. Values can contains white spaces and '"' or '"' characters.

Definition at line 1472 of file ns_cmdline.c.

void 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:

fmt	The 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.
ap	list 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:

fmt	The 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.
ap	list of parameters needed by format string. This must correspond properly with the conversion specifier.

Definition at line 243 of file ns_cmdline.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	11 Oct 2018
Imports:	23
Forks:	0
Commits:	4
Dependents:	0
Dependencies:	1
Followers:	1

Important changes to repositories hosted on mbed.com

ns_cmdline.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

ns_cmdline.h File Reference

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning