Command Processor and Command Line Interface

Logicrom OpenCPU SDK provide in-built command processor and CLI with many features like user authentication and command autocomplete etc.

By default SDK provide system commands and linux like core utility commands.

Available commands

Command	Description
devinfo	Get device information
sysinfo	Get system information
loglevel	Set or get current debug loglevel
reboot	Reboot system
ntpdate	Get date time information from NTP server
df	Show information about filesystem
ls	List file(s) or directory
echo	Display line of text
free	Display free and used memory in the system
cat	Display file on standard output
mkdir	Make directory
rm	Remove file or directory
mv	Move file or directory
format	Format device/filesystem
logout	Logout current user
help	Get command help

Optional Commands

Some commands are available only when a module is used or enabled by the application.

Following is the list of Commands with modules.

Command	Module	Description
wget	Utility	Download file from web to filesystem
load	Utility	Download file on module via Console (Xmodem)
dload	Utility	Download file from module via Console (Xmodem)
gpsinfo	GPS	Get GPS realtime information
gpscmd	GPS	Send command to GPS module
gpsbaud	GPS	Change gps baudrate
btman	Blutooth	Bluetooth manager command
spifs	SPIFS	Manage SPI filesystem
fota	FOTA	Download firmware over the air
rdbg	Remote DBG	Initiate a remote debug session
ntpdate	NTP Client	Get date from NTP server and sync

Following commands are available on 4G modules only

Command	Description
ifconfig	Get network device information
ping	Send ICMP ECHO REQUEST to network host

Custom commands

Command processor APIs can be used to add new commands to the system.

Command Delimiters

Command and argument on console are seperated using following delimiters:

Comma (,)
Space ( )

Command and only first parameter can also be seperated by an equal (=) symbol. So following formats for comamnd is valid on console

$ command=parameter
$ command parameter
$ command,parameter
# multi parameter commands
$ command=param1,param2
$ command=param1 param2
$ command param1 param2
$ command,param1,param2

Parameter Escaping

To escape parameter with comma a quote can be used. For example:

$ command="param1,continued",param2

To escape quote, a backslash can be used:

$ command="param1,continued with a \"quote\"",param2

Application Example

waybyte/example-console

Command Processor API Reference

Header File

Source: include/command.h

#include <command.h>

Functions

int command_process(const char *cmd, int len, struct cmdinfo_t *info, commandproc_cb callback, void *arg)

Execute command buffer

Multiple commands can be separated by ; and will be executed by the built-in parser.

Parameters:

cmd – [in] String containing list of commands
len – [in] length of cmd string
info – [in] Command information structure
callback – [in] process callback function of type commandproc_cb, called after execution of each command in the list
arg – [in] Argument passed to callback function

Returns:

0 on success, or != 0 on error. command_ret_e

Structures

struct cmdinfo_t

Command information structure, passed to command handler function

Public Members

int src: Command source command_src_e

void *data: user data attached to command

struct cmddesc_t

Command descriptor structure

Public Members

const char *cmd: Name of command

int min_arg: Minimum arguments

int max_arg: Maximum arguments

cmd_handler_f cmdfn: Command handler function

const char *help: Short help message

const char *usage: Long help message with usage

int type: Command type flags command_type_e

Macros

CMD_MAX_ARGS: Maximum number of allowed arguments including command

CMD_ADD(_name, _minarg, _maxarg, _cmd, _help, _usage, _type)

Add new command

Parameters:

_name – Name of command
_minarg – Minimum number of arguments including command (must be >= 1)
_maxarg – Maximum number of arguments including command (must be >= 1 & <= CMD_MAX_ARGS)
_cmd – Command handler function
_help – Short help message
_usage – Long help message and usage detail
_type – Command type flag see command_type_e

Type Definitions

typedef int (*cmd_handler_f)(int argc, const char **argv, struct cmdinfo_t *info)

Command Handler function

Param argc:: Number of arguments
Param argv:: Argument list
Param info:: Command info structure
Return:: Command return type command_ret_e

typedef void (*commandproc_cb)(int result, struct cmdinfo_t *info, void *arg)

Command process callback function

Param result:: Result of command executing
Param info:: Command information structure
Param arg:: User argument

Enumerations

enum command_ret_e

Command executing return code

Values:

enumerator CMD_RET_SUCCESS: Command executed successfully

enumerator CMD_RET_FAILURE: Command executing failure

enumerator CMD_RET_PERM: Command Permission denied

enumerator CMD_RET_LOGOUT: Execute session logout

enumerator CMD_RET_USAGE: Failure, please report ‘usage’ error

enum command_src_e

Source of command used in cmdinfo_t structure

Values:

enumerator CMD_SRC_CONSOLE: Command source console

enumerator CMD_SRC_BTCONSOLE: Command source Bluetooth Console

enumerator CMD_SRC_DBG: Command source Remote debug console

enumerator CMD_SRC_SMS: Command source SMS

enumerator CMD_SRC_TCP: Command source TCP

enumerator CMD_SRC_SYS: Command source system() API

enum command_type_e

Command type flags. These flags can be ORed together.

Values:

enumerator CMD_TYPE_DEFAULT: Default command, executing allowed everywhere and can be executed by user and admin.

enumerator CMD_TYPE_HIDDEN: Hidden command, Only executed by admin user; Unless allowed by allow flags

enumerator CMD_ALLOW_SMS: Command allowed over SMS

enumerator CMD_ALLOW_TCP: Command allowed over TCP

enumerator CMD_ALLOW_DBG: Command allowed over remote debug

enumerator CMD_ALLOW_CONSOLE: Command allowed over console

enumerator CMD_ALLOW_BT_CONSOLE: Command allowed over Bluetooth console

enumerator CMD_ALLOW_SYS: Command allowed to execute via system() API

enumerator CMD_ALLOW_ALL: Command allowed from all sources

enumerator CMD_ALLOW_TCP_SMS: Command allowed over TCP and SMS

enumerator CMD_ALLOW_CONSOLE_ONLY: Command allowed over Console only

enumerator CMD_ALLOW_TCP_SMS_DBG: Command allowed over TCP, SMS and remote console

Console API Reference

Header File

Source: include/console.h

#include <console.h>

Functions

int cli_init(cliauth_f fn)

Initialize and enable Command line interface for STDIO port

Parameters:: fn – Pointer to auth function of type cliauth_f Set NULL to disable login.
Returns:: 0 on success, negative value on error

int cli_set_authfn(cliauth_f fn)

Set/Change Authentication function

Parameters:: fn – Pointer to auth function of type cliauth_f Set NULL to disable login.
Returns:: 0 on success, negative value on error

Type Definitions

typedef int (*cliauth_f)(const char *user, const char *pass)

CLI Authentication function

Param user:

Username entered on console.

For Remote debug console this value is “rdbg”.

For Bluetooth console this value is “btcli”.

Param pass:

Password

Return:

Authentication return code, see cli_auth_rc

Enumerations

enum cli_auth_rc

CLI authentication return code

Values:

enumerator AUTH_FAIL: Authentication failed

enumerator AUTH_USER: Authentication success with user credentials

enumerator AUTH_ADMIN: Authentication success with admin credentials