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 commandhandler::VerboseMode

Verbose mode.

Values:

VERBOSE

Verbose mode.

SILENT

Silent mode.

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 parameters
  • commandOutput: 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 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()

Public Members

String commandName

Command name.

String commandHelp

Command help.

String commandGroup

Command group.

CommandFunctionDelegate commandFunction

Command Delegate (function that is called when command is invoked)

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

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

String getCommandWelcomeMessage()

Get the welcome message.

Note
Only if verbose mode is enabled
Return Value
  • String: The welcome message that is shown when clients connect

void setCommandWelcomeMessage(const String &reqWelcomeMessage)

Set the welcome message.

Note
Only if verbose mode is enabled
Parameters
  • reqWelcomeMessage: The welcome message that is shown when clients connect