Modules#

Command Interpreter Plugin#

Process commands coming from the serial port.

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

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

// 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
  ...
}

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

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

void main(void)
{
   emberCommandReaderInit();
   while(0) {
     ...
     // 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. The application's function name that implements the command.
3. An EmberCommandEntry::argumentTypes string specifies the number and types of arguments the command accepts.
4. A description string explains the command.
A default error handler emberCommandErrorHandler() is provided to deal with the incorrect command input. Applications may override it.
The application calls emberCommandReaderInit() to initialize 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 is 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 an error occurs in the command input, emberCommandErrorHandler() is called instead of 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 is generated. To disable this feature, define EMBER_REQUIRE_EXACT_COMMAND_NAME in the application configuration header.

Retrieve Arguments#

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

uint8_t

emberCommandArgumentCount(void)

uint32_t

emberUnsignedCommandArgument(uint8_t argNum)

int32_t

emberSignedCommandArgument(uint8_t argNum)

uint8_t *

emberStringCommandArgument(int8_t argNum, uint8_t *length)

const char *

emberCommandName(void)

uint8_t

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

bool

emberGetIpArgument(uint8_t index, uint8_t *target)

bool

emberGetIpPrefixArgument(uint8_t index, uint8_t *target)

void

emberGetExtendedPanIdArgument(int8_t index, uint8_t *extendedPanId)

#define

emberCopyKeyArgument (index, keyDataPointer)

#define

emberCopyEui64Argument (index, eui64)

#define

emberGetKeyArgument (index, keyDataPointer)

#define

emberGetEui64Argument (index, eui64)

Callbacks#

void

emberCommandErrorHandler(EmberCommandStatus status, EmberCommandEntry *command)

Command Table Settings#

#define

EMBER_MAX_COMMAND_ARGUMENTS 20

#define

EMBER_COMMAND_BUFFER_LENGTH 200

#define

EMBER_CUSTOM_COMMAND_BUFFER_LENGTH (EMBER_COMMAND_BUFFER_LENGTH - 3)

#define

EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

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)

typedef void

EmberCommandErrorHandler(EmberCommandStatus status, EmberCommandEntry *command)

Type of error handlers; the command argument is currently always NULL.

Variables#

EmberCommandEntry

emberCommandTable

Functions#

void

emberPrintCommandUsage(EmberCommandEntry *entry)

void

emberPrintCommandUsageNotes(void)

void

emberPrintCommandTable(void)

void

emberCommandClearBuffer(void)

void

emberCommandReaderInit(void)

Initialize the command interpreter.

bool

emberProcessCommandString(const uint8_t *input, uint16_t sizeOrPort)

Process the given string as a command.

uint8_t

emberHexToInt(uint8_t ch)

Return the value of a hexadecimal digit ch (0 - 15). Returns a value > 15 if ch is not a hexadecimal digit.

bool

emberStringToIpAddress(const uint8_t *string, uint8_t stringLength, uint8_t *target)

Parse textual representations of IPv6 addresses as described in http://www.ietf.org/rfc/rfc4291.txt.

bool

emberStringToIpPrefix(const uint8_t *string, uint8_t stringLength, uint8_t *target)

Parse textual representations of IPv6 prefixes as described in http://www.ietf.org/rfc/rfc4291.txt.

void

emberInitializeCommandState(EmberCommandState *state)

Must be called to initialize a command state before passing it to emberRunCommandInterpreter().

bool

emberRunCommandInterpreter(bool commandIsBinary, EmberCommandState *state, EmberCommandEntry *commands, EmberCommandErrorHandler *errorHandler, const uint8_t *input, uint16_t sizeOrPort)

For use when additional different command streams are used.

void

emberCommandReaderSetDefaultBase(uint8_t base)

Macros#

#define

MAX_TOKEN_COUNT (EMBER_MAX_COMMAND_ARGUMENTS + 1)

#define

emberCommandEntryAction (name, command, arguments, description)

#define

emberCommandEntrySubMenu (name, nestedCommands, description)

#define

emberCommandEntryTerminator ()

#define

emberCommand emberCommandEntryAction

#define

emberNestedCommand emberCommandEntrySubMenu

#define

emberProcessCommandInput (port)

Process the input coming in on the given serial port.

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

Retrieve signed integer arguments.

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 hexadecimal string arguments. Hexadecimal strings are already converted into binary. ASCII strings are null terminated. The null terminator is not included in the returned length argument. To retrieve the name of the command itself, use an argNum of -1. For example, to retrieve the first character of the command, uint8_t firstChar = emberStringCommandArgument(-1, NULL)[0]. If the command is nested, an index of -2, -3, and so on retrieves 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.

emberGetStringArgument#

uint8_t emberGetStringArgument (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

Copy the string argument to the given destination up to maxLength. If the argument length is not zero 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. ASCII strings are null terminated but the null terminator is not included in the returned length.

This function is commonly used for reading in hexadecimal strings, such as EUI64 or key data and left padding them with zeros. See emberGetKeyArgument and emberGetEui64Argument for convenience macros for this purpose.

emberGetIpArgument#

bool emberGetIpArgument (uint8_t index, uint8_t * target)

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	index
uint8_t *	N/A	target

Parse and return, via target, an IP address at the provided index. Returns true if an IP address was successfully parsed Returns false otherwise.

emberGetIpPrefixArgument#

bool emberGetIpPrefixArgument (uint8_t index, uint8_t * target)

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	index
uint8_t *	N/A	target

Parse and return, via target, an IP prefix at the provided index. Returns true if an IP prefix was successfully parsed. Returns false otherwise.

emberGetExtendedPanIdArgument#

void emberGetExtendedPanIdArgument (int8_t index, uint8_t * extendedPanId)

Parameters

Type	Direction	Argument Name	Description
int8_t	N/A	index
uint8_t *	N/A	extendedPanId

Copy the extended PAN ID argument to the given destination, reversing the bytes. Extended PAN IDs are stored little endian so reversing the bytes means they are big endian in the input command string.

Callbacks Documentation#

emberCommandErrorHandler#

void emberCommandErrorHandler (EmberCommandStatus status, EmberCommandEntry * command)

Parameters

Type	Direction	Argument Name	Description
EmberCommandStatus	N/A	status
EmberCommandEntry *	N/A	command

Command Table Settings Documentation#

Enumeration Documentation#

EmberCommandStatus#

EmberCommandStatus

Command error states.

If you change this list, also change the strings that describe these errors in the array emberCommandErrorNames[] in command-interpreter2-error.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)

EmberCommandErrorHandler#

typedef void EmberCommandErrorHandler(EmberCommandStatus status, EmberCommandEntry *command) (EmberCommandStatus status, EmberCommandEntry *command)

Type of error handlers; the command argument is currently always NULL.

Variable Documentation#

emberCommandTable#

EmberCommandEntry emberCommandTable[]

Function Documentation#

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 (const uint8_t * input, uint16_t sizeOrPort)

Process the given string as a command.

Parameters

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

emberHexToInt#

uint8_t emberHexToInt (uint8_t ch)

Return the value of a hexadecimal digit ch (0 - 15). Returns a value > 15 if ch is not a hexadecimal digit.

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	ch

emberStringToIpAddress#

bool emberStringToIpAddress (const uint8_t * string, uint8_t stringLength, uint8_t * target)

Parse textual representations of IPv6 addresses as described in http://www.ietf.org/rfc/rfc4291.txt.

Parameters

Type	Direction	Argument Name
const uint8_t *	N/A	string
uint8_t	N/A	stringLength
uint8_t *	N/A	target

emberStringToIpPrefix#

bool emberStringToIpPrefix (const uint8_t * string, uint8_t stringLength, uint8_t * target)

Parse textual representations of IPv6 prefixes as described in http://www.ietf.org/rfc/rfc4291.txt.

Parameters

Type	Direction	Argument Name
const uint8_t *	N/A	string
uint8_t	N/A	stringLength
uint8_t *	N/A	target

emberInitializeCommandState#

void emberInitializeCommandState (EmberCommandState * state)

Must be called to initialize a command state before passing it to emberRunCommandInterpreter().

Parameters

Type	Direction	Argument Name	Description
EmberCommandState *	N/A	state

emberRunCommandInterpreter#

bool emberRunCommandInterpreter (bool commandIsBinary, EmberCommandState * state, EmberCommandEntry * commands, EmberCommandErrorHandler * errorHandler, const uint8_t * input, uint16_t sizeOrPort)

For use when additional different command streams are used.

Parameters

Type	Direction	Argument Name
bool	N/A	commandIsBinary
EmberCommandState *	N/A	state
EmberCommandEntry *	N/A	commands
EmberCommandErrorHandler *	N/A	errorHandler
const uint8_t *	N/A	input
uint16_t	N/A	sizeOrPort

emberCommandReaderSetDefaultBase#

void emberCommandReaderSetDefaultBase (uint8_t base)

Parameters

Type	Direction	Argument Name	Description
uint8_t	N/A	base