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.

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

inline 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

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

inline String getCommandWelcomeMessage()

Get the welcome message.

Note

Only if verbose mode is enabled

Returns

String – The welcome message that is shown when clients connect

inline 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