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.

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

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

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.

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