Command Interpreter Plugin
Connect Application Framework API Reference

Processes commands coming from the serial port. More...

Data Structures

struct EmberCommandEntry
Command entry for a command table. More...
struct EmberCommandState
For use when declaring a separate command streams. The fields are not accessed directly by the application. More...

Macros

#define MAX_TOKEN_COUNT ( EMBER_MAX_COMMAND_ARGUMENTS + 1)
#define emberCommandEntryAction (name, command, arguments, description) { name, command, arguments, description }
#define emberCommandEntrySubMenu (name, nestedCommands, description) { name, NULL , (PGM_P)nestedCommands, description }
#define emberCommandEntryTerminator () { NULL , NULL , NULL , NULL }
#define emberCommand emberCommandEntryAction
#define emberNestedCommand emberCommandEntrySubMenu
#define emberProcessCommandInput (port) emberProcessCommandString ( NULL , port)
Process the input coming in on the given serial port. More...

Typedefs

typedef void(* CommandAction ) (void)
typedef void EmberCommandErrorHandler ( EmberCommandStatus status, EmberCommandEntry *command)
Type of error handlers; the command argument is currently always NULL. More...

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. More...

Functions

void emberCommandErrorHandler ( EmberCommandStatus status, EmberCommandEntry *command)
void emberPrintCommandUsage ( EmberCommandEntry *entry)
void emberPrintCommandUsageNotes (void)
void emberPrintCommandTable (void)
void emberCommandClearBuffer (void)
void emberCommandReaderInit (void)
Initialize the command interpreter. More...
bool emberProcessCommandString (const uint8_t *input, uint16_t sizeOrPort)
Process the given string as a command. More...
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. More...
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 . More...
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 . More...
void emberInitializeCommandState ( EmberCommandState *state)
Must be called to initialize a command state before passing it to emberRunCommandInterpreter() . More...
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. More...
void emberCommandReaderSetDefaultBase (uint8_t base)

Variables

EmberCommandEntry emberCommandTable []

Command Table Settings

#define EMBER_MAX_COMMAND_ARGUMENTS 20
#define EMBER_COMMAND_BUFFER_LENGTH 125
#define EMBER_CUSTOM_COMMAND_BUFFER_LENGTH ( EMBER_COMMAND_BUFFER_LENGTH - 3)
#define EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

Functions to 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) ( emberGetStringArgument ((index), (eui64), EUI64_SIZE , TRUE ))
#define emberGetKeyArgument (index, keyDataPointer)
#define emberGetEui64Argument (index, eui64) emberGetExtendedPanIdArgument (index, (eui64)->bytes)

Detailed Description

Processes 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);
}
...
}
}
  1. 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.
  2. A default error handler emberCommandErrorHandler() is provided to deal with the incorrect command input. Applications may override it.
  3. The application calls emberCommandReaderInit() to initialize and emberProcessCommandInput() in its main loop.
  4. 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.

Macro Definition Documentation

◆ EMBER_COMMAND_BUFFER_LENGTH

#define EMBER_COMMAND_BUFFER_LENGTH 125

The maximum number of arguments a command can have. A nested command counts as an argument.

Definition at line 117 of file command-interpreter2.h .

◆ EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

#define EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

Indicate whether or not the command entry structure includes descriptions for the commands. This consumes additional CONST space, which is expensive on the XAP. By default, descriptions are not included.

Definition at line 130 of file command-interpreter2.h .

◆ EMBER_CUSTOM_COMMAND_BUFFER_LENGTH

#define EMBER_CUSTOM_COMMAND_BUFFER_LENGTH ( EMBER_COMMAND_BUFFER_LENGTH - 3)

The maximum message size for custom commands reserves three bytes for the length (1 bytes) and the custom command identifier (2 bytes).

Definition at line 123 of file command-interpreter2.h .

◆ EMBER_MAX_COMMAND_ARGUMENTS

#define EMBER_MAX_COMMAND_ARGUMENTS 20

The maximum number of arguments a command can have. A nested command counts as an argument.

Definition at line 113 of file command-interpreter2.h .

◆ emberCommand

#define emberCommand emberCommandEntryAction

Definition at line 224 of file command-interpreter2.h .

◆ emberCommandEntryAction

#define emberCommandEntryAction ( name,
command,
arguments,
description
) { name, command, arguments, description }

Definition at line 215 of file command-interpreter2.h .

◆ emberCommandEntrySubMenu

#define emberCommandEntrySubMenu ( name,
nestedCommands,
description
) { name, NULL , (PGM_P)nestedCommands, description }

Definition at line 217 of file command-interpreter2.h .

◆ emberCommandEntryTerminator

#define emberCommandEntryTerminator ( ) { NULL , NULL , NULL , NULL }

Definition at line 219 of file command-interpreter2.h .

◆ emberCopyEui64Argument

#define emberCopyEui64Argument ( index,
eui64
) ( emberGetStringArgument ((index), (eui64), EUI64_SIZE , TRUE ))

A convenience macro for copying eui64 arguments to an EmberEUI64.

Definition at line 301 of file command-interpreter2.h .

◆ emberCopyKeyArgument

#define emberCopyKeyArgument ( index,
keyDataPointer
)
Value:
( emberGetStringArgument ((index), \
emberKeyContents ((keyDataPointer)), \
EMBER_ENCRYPTION_KEY_SIZE , \
TRUE ))
EMBER_ENCRYPTION_KEY_SIZE
#define EMBER_ENCRYPTION_KEY_SIZE
Size of an encryption key in bytes (16).
Definition: ember-types.h:48
TRUE
#define TRUE
An alias for one, used for clarity.
Definition: platform-common.h:209
emberGetStringArgument
uint8_t emberGetStringArgument(int8_t argNum, uint8_t *destination, uint8_t maxLength, bool leftPad)
emberKeyContents
uint8_t * emberKeyContents(EmberKeyData *key)
This macro allows the programmer to gain access to the key data bytes of the EmberKeyData structure...

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

Definition at line 294 of file command-interpreter2.h .

◆ emberGetEui64Argument

#define emberGetEui64Argument ( index,
eui64
) emberGetExtendedPanIdArgument (index, (eui64)->bytes)

Copy the EUI64 argument to the given EmberEui64 destination reversing the bytes. EUI64's are stored little endian so reversing the bytes means they are big endian in the input command string.

Definition at line 348 of file command-interpreter2.h .

◆ emberGetKeyArgument

#define emberGetKeyArgument ( index,
keyDataPointer
)
Value:
( emberGetStringArgument ((index), \
emberKeyContents ((keyDataPointer)), \
EMBER_ENCRYPTION_KEY_SIZE , \
true ))
EMBER_ENCRYPTION_KEY_SIZE
#define EMBER_ENCRYPTION_KEY_SIZE
Size of an encryption key in bytes (16).
Definition: ember-types.h:48
emberGetStringArgument
uint8_t emberGetStringArgument(int8_t argNum, uint8_t *destination, uint8_t maxLength, bool leftPad)
emberKeyContents
uint8_t * emberKeyContents(EmberKeyData *key)
This macro allows the programmer to gain access to the key data bytes of the EmberKeyData structure...

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

Definition at line 338 of file command-interpreter2.h .

◆ emberNestedCommand

#define emberNestedCommand emberCommandEntrySubMenu

Definition at line 225 of file command-interpreter2.h .

◆ emberProcessCommandInput

#define emberProcessCommandInput ( port ) emberProcessCommandString ( NULL , port)

Process the input coming in on the given serial port.

Returns
true if an end of line character was read. If the application uses a command line prompt, this indicates it is time to print the prompt.
void emberProcessCommandInput (uint8_t port);

Definition at line 382 of file command-interpreter2.h .

◆ MAX_TOKEN_COUNT

#define MAX_TOKEN_COUNT ( EMBER_MAX_COMMAND_ARGUMENTS + 1)

Definition at line 136 of file command-interpreter2.h .

Typedef Documentation

◆ CommandAction

typedef void(* CommandAction) (void)

Definition at line 138 of file command-interpreter2.h .

◆ EmberCommandErrorHandler

typedef void EmberCommandErrorHandler( EmberCommandStatus status, EmberCommandEntry *command)

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

Definition at line 455 of file command-interpreter2.h .

Enumeration Type Documentation

◆ EmberCommandStatus

enum 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

Definition at line 236 of file command-interpreter2.h .

Function Documentation

◆ emberCommandArgumentCount()

uint8_t emberCommandArgumentCount ( void )

Returns the number of arguments for the current command.

◆ emberCommandClearBuffer()

void emberCommandClearBuffer ( void )

◆ emberCommandErrorHandler()

void emberCommandErrorHandler ( EmberCommandStatus status,
EmberCommandEntry * command
)

◆ emberCommandName()

const char* emberCommandName ( void )

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

◆ emberCommandReaderInit()

void emberCommandReaderInit ( void )

Initialize the command interpreter.

◆ emberCommandReaderSetDefaultBase()

void emberCommandReaderSetDefaultBase ( uint8_t base )

◆ emberGetExtendedPanIdArgument()

void emberGetExtendedPanIdArgument ( int8_t index,
uint8_t * 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.

◆ emberGetIpArgument()

bool emberGetIpArgument ( uint8_t index,
uint8_t * 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
)

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

◆ emberGetStringArgument()

uint8_t emberGetStringArgument ( int8_t argNum,
uint8_t * destination,
uint8_t maxLength,
bool 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.

◆ 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.

◆ emberInitializeCommandState()

void emberInitializeCommandState ( EmberCommandState * state )

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

◆ emberPrintCommandTable()

void emberPrintCommandTable ( void )

◆ emberPrintCommandUsage()

void emberPrintCommandUsage ( EmberCommandEntry * entry )

◆ emberPrintCommandUsageNotes()

void emberPrintCommandUsageNotes ( void )

◆ emberProcessCommandString()

bool emberProcessCommandString ( const uint8_t * input,
uint16_t sizeOrPort
)

Process the given string as a command.

◆ 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.

◆ emberSignedCommandArgument()

int32_t emberSignedCommandArgument ( uint8_t argNum )

Retrieve signed integer arguments.

◆ emberStringCommandArgument()

uint8_t* emberStringCommandArgument ( int8_t argNum,
uint8_t * 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].

◆ 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 .

◆ 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 .

◆ emberUnsignedCommandArgument()

uint32_t emberUnsignedCommandArgument ( uint8_t argNum )

Retrieves unsigned integer arguments.

Variable Documentation

◆ emberCommandTable

EmberCommandEntry emberCommandTable[]