Command Executor¶
Introduction¶
Command handler provides a common command line interface. CLI is available for the following remote access methods:
- Serial
- Telnet
- Websockets
By default, CLI is disabled. Enable CLI by calling “commandProcessing” on the appropriate access class object, e.g:
Serial.commandProcessing(true)
Commands can be added to and removed from the command handler. Each command will trigger a defined Delegate.
A welcome message may be shown when a user connects and end of line character may be defined. An automatic “help” display is available.
Build Variables¶
-
ENABLE_CMD_EXECUTOR
¶ Default: 1 (ON)
This feature enables execution of certain commands by registering token handlers for text received via serial, websocket or telnet connection. If this feature is not used additional RAM/Flash can be obtained by setting
ENABLE_CMD_EXECUTOR=0
. This will save ~1KB RAM and ~3KB of flash memory.
API Documentation¶
-
typedef Delegate<void(String commandLine, CommandOutput *commandOutput)>
CommandFunctionDelegate
¶ Command delegate function.
- Note
- CommandFunctionDelegate defines the structure of a function that handles individual commands
- Note
- Can use standard print functions on commandOutput
- Parameters
commandLine
: Command line entered by user at CLI, including command and parameterscommandOutput
: Pointer to the CLI print stream
-
typedef CommandFunctionDelegate
commandFunctionDelegate
¶
-
CommandHandler
commandHandler
¶ Global instance of CommandHandler.
-
class
CommandDelegate
¶ - #include <CommandDelegate.h>
Command delegate class.
Public Functions
-
CommandDelegate
(String reqName, String reqHelp, String reqGroup, CommandFunctionDelegate reqFunction)¶ Instantiate a command delegate
- Parameters
reqName
: Command name - the text a user types to invoke the commandreqHelp
: Help message shown by CLI “help” commandreqGroup
: The command group to which this command belongsreqFunction
: Delegate that should be invoked (triggered) when the command is entered by a user
-
~CommandDelegate
()¶
-
-
class
CommandHandler
¶ - #include <CommandHandler.h>
Command handler class.
Public Functions
-
CommandHandler
()¶ Instantiate a CommandHandler.
-
~CommandHandler
()¶
-
bool
registerCommand
(CommandDelegate reqDelegate)¶ Add a new command to the command handler.
- Note
- If command already exists, it will not be replaced and function will fail. Call unregisterCommand first if you want to replace a command.
- Parameters
reqDelegate
: Command delegate to register
- Return Value
bool
: True on success
-
bool
unregisterCommand
(CommandDelegate reqDelegate)¶ Remove a command from the command handler.
reqDelegate Delegate to remove from command handler
-
void
registerSystemCommands
()¶ Register default system commands.
- Note
- Adds the following system commmands to the command handler
- status
- echo
- help
- debugon
- debugoff
- command
-
CommandDelegate
getCommandDelegate
(const String &commandString)¶ Get the command delegate for a command.
- Parameters
commandString
: Command to query
- Return Value
CommandDelegate
: The command delegate matchin the command
-
VerboseMode
getVerboseMode
()¶ Get the verbose mode.
- Return Value
VerboseMode
: Verbose mode
-
void
setVerboseMode
(VerboseMode reqVerboseMode)¶ Set the verbose mode.
- Parameters
reqVerboseMode
: Verbose mode to set
-
String
getCommandPrompt
()¶ Get the command line prompt.
- Note
- This is what is shown on the command line before user input Default is Sming>
- Return Value
String
: The command line prompt
-
void
setCommandPrompt
(const String &reqPrompt)¶ Set the command line prompt.
- Note
- This is what is shown on the command line before user input Default is Sming>
- Parameters
reqPrompt
: The command line prompt
-
char
getCommandEOL
()¶ Get the end of line character.
- Note
- Only supports one EOL, unlike Windows
- Return Value
char
: The EOL character
-
void
setCommandEOL
(char reqEOL)¶ Set the end of line character.
- Note
- Only supports one EOL, unlike Windows
- Parameters
reqEOL
: The EOL character
-