Command Interpreter
Thread Stack API Reference

The command interpreter.

Data Structures

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

Macros

#define MAX_TOKEN_COUNT ( EMBER_MAX_COMMAND_ARGUMENTS + 1)
#define MAX_COMMAND_TABLE_NESTING 16
#define emberBinaryCommand emberBinaryCommandEntryAction
#define emberBinaryNestedCommand emberBinaryCommandEntrySubMenu
#define emberBinaryCommandEntryAction (identifier, command, arguments, description)   { { (PGM_P)identifier }, command, arguments, description }
#define emberBinaryCommandEntrySubMenu (identifier, nestedCommands, description)   { { (PGM_P)identifier }, NULL , description, nestedCommands }
#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)
This function processes input coming in on the given serial port.

Typedefs

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

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.

Functions

void emberCommandErrorHandler ( EmberCommandStatus status, EmberCommandEntry *command)
void emberPrintCommandUsage ( EmberCommandEntry *entry)
void emberPrintCommandUsageNotes (void)
void emberPrintCommandTable (void)
void emberCommandClearBuffer (void)
void emberCommandReaderInit (void)
This function initializes the command interpreter.
bool emberProcessCommandString (const uint8_t *input, uint16_t sizeOrPort)
This function processes the given string as a command.
void emberInitializeCommandState ( EmberCommandState *state)
This function must be called to initialize a command state before passing it to emberRunBinaryCommandInterpreter() or emberRunAsciiCommandInterpreter() .
bool emberRunBinaryCommandInterpreter ( EmberCommandState *state, EmberCommandEntry *commands, EmberCommandErrorHandler *errorHandler, const uint8_t *input, uint16_t sizeOrPort)
For use to process binary commands when additional different command streams are being used.
bool emberRunAsciiCommandInterpreter ( EmberCommandState *state, EmberCommandEntry *commands, EmberCommandErrorHandler *errorHandler, const uint8_t *input, uint16_t sizeOrPort)
For use to process ASCII commands when additional different command streams are being used.
void emberCommandReaderSetDefaultBase (uint8_t base)

Variables

EmberCommandEntry emberCommandTable []
EmberCommandEntry emberBinaryCommandTable []

Command Table Settings

#define EMBER_MAX_COMMAND_ARGUMENTS 14
#define EMBER_COMMAND_BUFFER_LENGTH 100
#define EMBER_CUSTOM_COMMAND_BUFFER_LENGTH ( EMBER_COMMAND_BUFFER_LENGTH - 3)
#define EMBER_COMMAND_INTERPRETER_HAS_DESCRIPTION_FIELD
#define EMBER_COMMAND_INTERPRETER_NO_ERROR_MESSAGE

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)
uint8_t * emberStringCommandArgument (int8_t argNum, uint8_t *length)
uint8_t * emberLongStringCommandArgument (int8_t argNum, uint16_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 emberGetIpv6AddressArgument (uint8_t index, EmberIpv6Address *dst)
This function parses an IPv6 address in a CLI command.
bool emberGetIpv6PrefixArgument (uint8_t index, EmberIpv6Address *dst, uint8_t *dstPrefixBits)
This function parses an IPv6 prefix in a CLI command.
void emberGetExtendedPanIdArgument (int8_t index, uint8_t *extendedPanId)
#define emberGetKeyArgument (index, keyDataPointer)
#define emberGetEui64Argument (index, eui64) emberGetExtendedPanIdArgument (index, (eui64)->bytes)

Detailed Description

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

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

1 // Usage: network form 22 0xAB12 -3 { 00 01 02 A3 A4 A5 A6 A7 }
2 void formCommand(void)
3 {
4 uint8_t channel = emberUnsignedCommandArgument(0);
5 uint16_t panId = emberUnsignedCommandArgument(1);
6 int8_t power = emberSignedCommandArgument(2);
7 uint8_t length;
8 uint8_t *eui64 = emberStringCommandArgument(3, &length);
9 ...
10 ... call emberFormNetwork() etc
11 ...
12 }
13
14 // The table of network commands.
15 EmberCommandEntry networkCommands[] = {
16 emberCommandEntryAction("form", formCommand, "uvsh", "Form a network"),
17 emberCommandEntryAction("join", joinCommand, "uvsh", "join a network"),
18 ...
19 emberCommandEntryTerminator()
20 };
21
22 EmberCommandEntry systemCommands[] = {
23 emberCommandEntrySubMenu("network", networkCommands, "Network form/join commands"),
24 ...
25 emberCommandEntryTerminator()
26 };
27
28 // The main command table. A SubMenu with an empty command name processes
29 // the commands in the subtable as if they were in the main table.
30 EmberCommandEntry emberCommandTable[] = {
31 emberCommandEntrySubMenu("", systemCommands, ""),
32 emberCommandEntryAction("status", statusCommand, "Prints application status),
33 ...
34 emberCommandEntryTerminator()
35 };
36
37 void main(void)
38 {
39 emberCommandReaderInit();
40 while(0) {
41 ...
42 // Process input and print prompt if it returns true.
43 if (emberProcessCommandInput(serialPort)) {
44 emberSerialPrintf(1, "%p>", PROMPT);
45 }
46 ...
47 }
48 }
  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. 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.
  2. A default error handler emberCommandErrorHandler() is provided to deal with incorrect command input. Applications may override it.
  3. The application calls emberCommandReaderInit() to initalize, 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 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.

Macro Definition Documentation

#define EMBER_COMMAND_BUFFER_LENGTH   100

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

#define EMBER_COMMAND_INTERPRETER_HAS_DESCRIPTION_FIELD

Whether or not the command entry structure will include descriptions for the commands and error information. This consumes additional CONST space. By default descriptions are not included.

#define EMBER_COMMAND_INTERPRETER_NO_ERROR_MESSAGE

Whether or not error messages are included. This consumes additional CONST space. By default error messages are included.

#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).

#define EMBER_MAX_COMMAND_ARGUMENTS   14

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

#define emberBinaryCommand emberBinaryCommandEntryAction
#define emberBinaryCommandEntryAction ( identifier,
command,
arguments,
description
) { { (PGM_P)identifier }, command, arguments, description }
#define emberBinaryCommandEntrySubMenu ( identifier,
nestedCommands,
description
) { { (PGM_P)identifier }, NULL , description, nestedCommands }
#define emberBinaryNestedCommand emberBinaryCommandEntrySubMenu
#define emberCommand emberCommandEntryAction
#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 emberGetEui64Argument ( index,
eui64
) emberGetExtendedPanIdArgument (index, (eui64)->bytes)

This function copies 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.

#define emberGetKeyArgument ( index,
keyDataPointer
)
Value:
( emberGetStringArgument ((index), \
emberKeyContents((keyDataPointer)), \
EMBER_ENCRYPTION_KEY_SIZE , \
true ))
emberGetStringArgument
uint8_t emberGetStringArgument(int8_t argNum, uint8_t *destination, uint8_t maxLength, bool leftPad)
EMBER_ENCRYPTION_KEY_SIZE
#define EMBER_ENCRYPTION_KEY_SIZE
Size of an encryption key in bytes (16).
Definition: ember-types.h:50

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

#define emberNestedCommand emberCommandEntrySubMenu
#define emberProcessCommandInput ( port ) emberProcessCommandString ( NULL , 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.
1 void emberProcessCommandInput(uint8_t port);
#define MAX_COMMAND_TABLE_NESTING   16
#define MAX_TOKEN_COUNT   ( EMBER_MAX_COMMAND_ARGUMENTS + 1)

Typedef Documentation

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

Enumeration Type Documentation

enum EmberCommandStatus

If you change this list, ensure you 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

Function Documentation

uint8_t emberCommandArgumentCount ( void )

This function returns the number of arguments for the current command.

void emberCommandClearBuffer ( void )
void emberCommandErrorHandler ( EmberCommandStatus status,
EmberCommandEntry * command
)
const char* emberCommandName ( void )

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

void emberCommandReaderInit ( void )
void emberCommandReaderSetDefaultBase ( uint8_t base )
void emberGetExtendedPanIdArgument ( int8_t index,
uint8_t * extendedPanId
)

This function copies 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.

bool emberGetIpArgument ( uint8_t index,
uint8_t * target
)

This function parses and returns, via target, an IP address at the provided index. Returns true if an IP address was successfully parsed Return false otherwise

bool emberGetIpv6AddressArgument ( uint8_t index,
EmberIpv6Address * dst
)
Parameters
index An index of the IPv6 address to parse
dst the EmberIpv6Address a location where the address will be written
Returns
true if the IPv6 address was successfully parsed.
bool emberGetIpv6PrefixArgument ( uint8_t index,
EmberIpv6Address * dst,
uint8_t * dstPrefixBits
)
Parameters
index An index of the IPv6 prefix to parse
dst the EmberIpv6Address a location where the address will be written
prefixBits the number of prefix bits in the string
Returns
true if the IPv6 prefix was successfully parsed.
uint8_t emberGetStringArgument ( int8_t argNum,
uint8_t * destination,
uint8_t maxLength,
bool leftPad
)

This function 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. This function 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 zeroes. See emberGetKeyArgument and emberGetEui64Argument for convenience macros for this purpose.

void emberInitializeCommandState ( EmberCommandState * state )
uint8_t* emberLongStringCommandArgument ( int8_t argNum,
uint16_t * length
)

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

void emberPrintCommandTable ( void )
void emberPrintCommandUsage ( EmberCommandEntry * entry )
void emberPrintCommandUsageNotes ( void )
bool emberProcessCommandString ( const uint8_t * input,
uint16_t sizeOrPort
)
bool emberRunAsciiCommandInterpreter ( EmberCommandState * state,
EmberCommandEntry * commands,
EmberCommandErrorHandler * errorHandler,
const uint8_t * input,
uint16_t sizeOrPort
)
bool emberRunBinaryCommandInterpreter ( EmberCommandState * state,
EmberCommandEntry * commands,
EmberCommandErrorHandler * errorHandler,
const uint8_t * input,
uint16_t sizeOrPort
)
int32_t emberSignedCommandArgument ( uint8_t argNum )

This function retrieves signed integer arguments.

uint8_t* emberStringCommandArgument ( int8_t argNum,
uint8_t * length
)

This function retrieves quoted string or hexadecimal string arguments. Hexadecimal strings have already been converted into binary. ASCII strings have been null terminated. The null terminator is not included in the returned length argument. To retrieve the name of the command, 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, 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].

uint32_t emberUnsignedCommandArgument ( uint8_t argNum )

This function retrieves unsigned integer arguments.

Variable Documentation

EmberCommandEntry emberBinaryCommandTable[]
EmberCommandEntry emberCommandTable[]