Modules#

Command Interpreter#

Interpret serial port commands. See command-interpreter2.c for source code.

See the following application usage example followed by a brief explanation.

&frasl;&frasl; Usage: network form 22 0xAB12 -3 { 00 01 02 A3 A4 A5 A6 A7 }
void formCommand(void)
{
  uint8_t channel = emberUnsignedCommandArgument(0);
  uint16_t panId  = emberUnsignedCommandArgument(1);
  int8_t power   = emberSignedCommandArgument(2);
  uint8_t length;
  uint8_t *eui64  = emberStringCommandArgument(3, &length);
  ...
  ... call emberFormNetwork() etc
  ...
}

&frasl;&frasl; The main command table.
EmberCommandEntry emberCommandTable[] = {
  emberCommandEntrySubMenu("network",  networkCommands, "Network form/join commands"),
  emberCommandEntryAction("status",    statusCommand,   "Prints application status),
  ...
  emberCommandEntryTerminator()
};

&frasl;&frasl; The table of network commands.
EmberCommandEntry networkCommands[] = {
  emberCommandEntryAction("form", formCommand, "uvsh", "Form a network"),
  emberCommandEntryAction("join", joinCommand, "uvsh", "Join a network"),
  ...
  emberCommandEntryTerminator()
};

void main(void)
{
   emberCommandReaderInit();
   while(0) {
     ...
     &frasl;&frasl; Process input and print prompt if it returns true.
     if (emberProcessCommandInput(serialPort)) {
        emberSerialPrintf(1, "%p>", PROMPT);
     }
     ...
   }
}

Applications specify the commands that can be interpreted by defining the emberCommandTable array of type EmberCommandEntry. The table includes the following information for each command:
1. The full command name.
2. Your application's function name that implements the command.
3. An EmberCommandEntry::argumentTypes string specifies the number and types of arguments the command accepts. See ::argumentTypes for details.
4. A description string explains the command.

A default error handler emberCommandErrorHandler() is provided to deal with incorrect command input. Applications may override it.
The application calls emberCommandReaderInit() to initalize, and emberProcessCommandInput() in its main loop.
Within the application's command functions, use emberXXXCommandArgument() functions to retrieve command arguments.

The command interpreter does extensive processing and validation of the command input before calling the function that implements the command. It checks that the number, type, syntax, and range of all arguments are correct. It performs any conversions necessary (for example, converting integers and strings input in hexadecimal notation into the corresponding bytes), so that no additional parsing is necessary within command functions. If there is an error in the command input, emberCommandErrorHandler() is called rather than a command function.

The command interpreter allows inexact matches of command names. The input command may be either shorter or longer than the actual command. However, if more than one inexact match is found and there is no exact match, an error of type EMBER_CMD_ERR_NO_SUCH_COMMAND will be generated. To disable this feature, define EMBER_REQUIRE_EXACT_COMMAND_NAME in the application configuration header.

Command Table Settings#

#define

EMBER_MAX_COMMAND_ARGUMENTS 16

#define

EMBER_COMMAND_BUFFER_LENGTH 100

#define

EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

Functions to Retrieve Arguments#

Use the following functions in your functions that process commands to retrieve arguments from the command interpreter. These functions pull out unsigned integers, signed integers, and strings, and hex strings. Index 0 is the first command argument.

uint8_t

emberCommandArgumentCount(void)

uint32_t

emberUnsignedCommandArgument(uint8_t argNum)

int32_t

emberSignedCommandArgument(uint8_t argNum)

bool

emberStringToHostOrderIpv4Address(const uint8_t *string, uint32_t *hostOrderIpv4Address)

bool

emberStringArgumentToHostOrderIpv4Address(uint8_t argNum, uint32_t *hostOrderIpv4Address)

uint8_t *

emberStringCommandArgument(int8_t argNum, uint8_t *length)

const char *

emberCommandName(void)

uint8_t

emberCopyStringArgument(int8_t argNum, uint8_t *destination, uint8_t maxLength, bool leftPad)

uint8_t

emberCopyBigEndianEui64Argument(int8_t index, EmberEUI64 destination)

#define

emberCopyKeyArgument (index, keyDataPointer)

#define

emberCopyEui64Argument (index, eui64)

#define

emberGetEui64Argument (index, eui64)

Enumerations#

enum

EmberCommandStatus {

EMBER_CMD_SUCCESS

EMBER_CMD_ERR_PORT_PROBLEM

EMBER_CMD_ERR_NO_SUCH_COMMAND

EMBER_CMD_ERR_WRONG_NUMBER_OF_ARGUMENTS

EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE

EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR

EMBER_CMD_ERR_STRING_TOO_LONG

EMBER_CMD_ERR_INVALID_ARGUMENT_TYPE

}

Command error states.

Typedefs#

typedef void(*

CommandAction)(void)

Variables#

uint8_t

emberCommandInterpreter2Configuration

Functions#

void

emberCommandReaderSetDefaultBase(uint8_t base)

void

emberCommandActionHandler(const CommandAction action)

void

emberCommandErrorHandler(EmberCommandStatus status)

void

emberPrintCommandUsage(EmberCommandEntry *entry)

void

emberPrintCommandUsageNotes(void)

void

emberPrintCommandTable(void)

void

emberCommandClearBuffer(void)

void

emberCommandReaderInit(void)

Initialize the command interpreter.

bool

emberProcessCommandString(uint8_t *input, uint8_t sizeOrPort)

Process the given string as a command.

bool

emberCommandInterpreterBusy(void)

Returns true interpreter is reading a command.

Macros#

#define

MAX_TOKEN_COUNT (EMBER_MAX_COMMAND_ARGUMENTS + 1)

#define

emberCommandEntryAction (name, action, argumentTypes, description)

#define

emberCommandEntryActionWithDetails (name, action, argumentTypes, description, argumentDescriptionArray)

#define

emberCommandEntrySubMenu (name, subMenu, description)

#define

emberCommandEntryTerminator ()

#define

EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO (0x01)

#define

emberProcessCommandInput (port)

Process input coming in on the given serial port.

#define

emberCommandInterpreterEchoOn ()

Turn echo of command line on.

#define

emberCommandInterpreterEchoOff ()

Turn echo of command line off.

#define

emberCommandInterpreterIsEchoOn ()

Returns true if echo is on, false otherwise.

Command Table Settings Documentation#

Functions to Retrieve Arguments Documentation#

emberCommandArgumentCount#

uint8_t emberCommandArgumentCount (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Returns the number of arguments for the current command.

emberUnsignedCommandArgument#

uint32_t emberUnsignedCommandArgument (uint8_t argNum)

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	argNum

Retrieves unsigned integer arguments.

emberSignedCommandArgument#

int32_t emberSignedCommandArgument (uint8_t argNum)

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	argNum

Retrieves signed integer arguments.

emberStringToHostOrderIpv4Address#

bool emberStringToHostOrderIpv4Address (const uint8_t * string, uint32_t * hostOrderIpv4Address)

Parameters

Type	Direction	Argument Name	Description
const uint8_t *	N/A	string
uint32_t *	N/A	hostOrderIpv4Address

Parses an IPv4 address string and returns a host order uint32_t. Returns true if address is valid dotted quad notation (A.B.C.D), false otherwise.

emberStringArgumentToHostOrderIpv4Address#

bool emberStringArgumentToHostOrderIpv4Address (uint8_t argNum, uint32_t * hostOrderIpv4Address)

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	argNum
uint32_t *	N/A	hostOrderIpv4Address

Parses an IPv4 address string from a command argument and returns host order uint32_t. Returns true if address is valid dotted quad notation (A.B.C.D), false otherwise.

emberStringCommandArgument#

uint8_t* emberStringCommandArgument (int8_t argNum, uint8_t * length)

Parameters

Type	Direction	Argument Name	Description
int8_t	N/A	argNum
uint8_t *	N/A	length

Retrieve quoted string or hex string arguments. Hex strings have already been converted into binary. To retrieve the name of the command itself, use an argNum of -1. For example, to retrieve the first character of the command, do: uint8_t firstChar = emberStringCommandArgument(-1, NULL)[0]. If the command is nested, an index of -2, -3, etc will work to retrieve the higher level command names. Note that [-1] only returns the text entered. If an abbreviated command name is entered only the text entered will be returned with [-1].

emberCommandName#

const char* emberCommandName (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

A convenience macro for copying security key arguments to an EmberKeyData pointer.

emberCopyStringArgument#

uint8_t emberCopyStringArgument (int8_t argNum, uint8_t * destination, uint8_t maxLength, bool leftPad)

Parameters

Type	Direction	Argument Name
int8_t	N/A	argNum
uint8_t *	N/A	destination
uint8_t	N/A	maxLength
bool	N/A	leftPad

Copies the string argument to the given destination up to maxLength. If the argument length is nonzero but less than maxLength and leftPad is true, leading zeroes are prepended to bring the total length of the target up to maxLength. If the argument is longer than the maxLength, it is truncated to maxLength. Returns the minimum of the argument length and maxLength.

This function is commonly used for reading in hex strings such as EUI64 or key data and left padding them with zeroes. See emberCopyKeyArgument and emberCopyEui64Argument for convenience macros for this purpose.

emberCopyBigEndianEui64Argument#

uint8_t emberCopyBigEndianEui64Argument (int8_t index, EmberEUI64 destination)

Parameters

Type	Direction	Argument Name	Description
int8_t	N/A	index
EmberEUI64	N/A	destination

Copies eui64 arguments in big-endian format to an EmberEUI64. This is useful because eui64s are often presented to users in big-endian format even though they are used in software in little-endian format.

Enumeration Documentation#

EmberCommandStatus#

EmberCommandStatus

Command error states.

If you change this list, ensure you also change the strings that describe these errors in the array emberCommandErrorNames[] in command-interpreter.c.

Enumerator
EMBER_CMD_SUCCESS
EMBER_CMD_ERR_PORT_PROBLEM
EMBER_CMD_ERR_NO_SUCH_COMMAND
EMBER_CMD_ERR_WRONG_NUMBER_OF_ARGUMENTS
EMBER_CMD_ERR_ARGUMENT_OUT_OF_RANGE
EMBER_CMD_ERR_ARGUMENT_SYNTAX_ERROR
EMBER_CMD_ERR_STRING_TOO_LONG
EMBER_CMD_ERR_INVALID_ARGUMENT_TYPE

Typedef Documentation#

CommandAction#

typedef void(* CommandAction) (void) )(void)

Variable Documentation#

emberCurrentCommand#

EmberCommandEntry* emberCurrentCommand

A pointer to the currently matching command entry. Only valid from within a command function. If the original command was nested, points to the final (non-nested) command entry.

emberCommandTable#

EmberCommandEntry emberCommandTable[]

emberCommandInterpreter2Configuration#

uint8_t emberCommandInterpreter2Configuration

Configuration byte.

Function Documentation#

emberCommandReaderSetDefaultBase#

void emberCommandReaderSetDefaultBase (uint8_t base)

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	base

emberCommandActionHandler#

void emberCommandActionHandler (const CommandAction action)

Parameters

Type	Direction	Argument Name	Description
const CommandAction	N/A	action

The application may implement this handler. To override the default handler, define EMBER_APPLICATION_HAS_COMMAND_ACTION_HANDLER in the CONFIGURATION_HEADER.

emberCommandErrorHandler#

void emberCommandErrorHandler (EmberCommandStatus status)

Parameters

Type	Direction	Argument Name	Description
EmberCommandStatus	N/A	status

The application may implement this handler. To override the default handler, define EMBER_APPLICATION_HAS_COMMAND_ERROR_HANDLER in the CONFIGURATION_HEADER. Defining this will also remove the help functions emberPrintCommandUsage(), emberPrintCommandUsageNotes(), and emberPrintCommandTable().

emberPrintCommandUsage#

void emberPrintCommandUsage (EmberCommandEntry * entry)

Parameters

Type	Direction	Argument Name	Description
EmberCommandEntry *	N/A	entry

emberPrintCommandUsageNotes#

void emberPrintCommandUsageNotes (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

emberPrintCommandTable#

void emberPrintCommandTable (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

emberCommandClearBuffer#

void emberCommandClearBuffer (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

emberCommandReaderInit#

void emberCommandReaderInit (void )

Initialize the command interpreter.

Parameters

Type	Direction	Argument Name	Description
void	N/A

emberProcessCommandString#

bool emberProcessCommandString (uint8_t * input, uint8_t sizeOrPort)

Process the given string as a command.

Parameters

Type	Direction	Argument Name	Description
uint8_t *	N/A	input
uint8_t	N/A	sizeOrPort

emberCommandInterpreterBusy#

bool emberCommandInterpreterBusy (void )

Returns true interpreter is reading a command.

Parameters

Type	Direction	Argument Name	Description
void	N/A