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
-
enum VerboseMode
Verbose mode.
Values:
-
enumerator VERBOSE
Verbose mode.
-
enumerator SILENT
Silent mode.
-
enumerator VERBOSE
-
using CommandFunctionDelegate = Delegate<void(String commandLine, CommandOutput *commandOutput)>
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 parameters
commandOutput – Pointer to the CLI print stream
-
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 command
reqHelp – Help message shown by CLI “help” command
reqGroup – The command group to which this command belongs
reqFunction – Delegate that should be invoked (triggered) when the command is entered by a user
-
CommandDelegate(String reqName, String reqHelp, String reqGroup, CommandFunctionDelegate reqFunction)
-
class CommandHandler
- #include <CommandHandler.h>
Command handler class.
Public Functions
-
CommandHandler()
Instantiate a 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
- Returns
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 commands 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
- Returns
CommandDelegate – The command delegate matching the command
-
inline VerboseMode getVerboseMode()
Get the verbose mode.
- Returns
VerboseMode – Verbose mode
-
inline void setVerboseMode(VerboseMode reqVerboseMode)
Set the verbose mode.
- Parameters
reqVerboseMode – Verbose mode to set
-
inline String getCommandPrompt()
Get the command line prompt.
Note
This is what is shown on the command line before user input Default is Sming>
- Returns
String – The command line prompt
-
inline 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
-
inline char getCommandEOL()
Get the end of line character.
Note
Only supports one EOL, unlike Windows
- Returns
char – The EOL character
-
inline void setCommandEOL(char reqEOL)
Set the end of line character.
Note
Only supports one EOL, unlike Windows
- Parameters
reqEOL – The EOL character
-
CommandHandler()