|
#define
|
MAX_TOKEN_COUNT
(
EMBER_MAX_COMMAND_ARGUMENTS
+ 1)
|
|
#define
|
emberCommandEntryAction
(name, action, argumentTypes, description) { (name), (action), (argumentTypes), (description),
NULL
}
|
|
#define
|
emberCommandEntryActionWithDetails
(name, action, argumentTypes, description, argumentDescriptionArray) { (name), (action), (argumentTypes), (description), (argumentDescriptionArray) }
|
|
#define
|
emberCommandEntrySubMenu
(name, subMenu, description) { (name),
NULL
, (const char *)(subMenu), (description),
NULL
}
|
|
#define
|
emberCommandEntryTerminator
() {
NULL
,
NULL
,
NULL
,
NULL
,
NULL
}
|
|
#define
|
EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO
(0x01)
|
|
#define
|
emberProcessCommandInput
(port)
emberProcessCommandString
(
NULL
, 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.
|
|
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) (
emberCopyStringArgument
((index), (eui64),
EUI64_SIZE
, true))
|
|
#define
|
emberGetEui64Argument
(index, eui64) (
emberCopyStringArgument
((index), (eui64),
EUI64_SIZE
, true))
|
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 length;
...
...
}
⁄⁄ The main command table.
...
emberCommandEntryTerminator()
};
⁄⁄ 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) {
...
⁄⁄ 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:
-
The full command name.
-
Your application's function name that implements the command.
-
An
EmberCommandEntry::argumentTypes
string specifies the number and types of arguments the command accepts. See ::argumentTypes for details.
-
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.
#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_INTEPRETER_HAS_DESCRIPTION_FIELD
|
Whether or not the command entry structure will include descriptions for the commands. This consumes additional CONST space. By default descriptions are not included.
#define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO (0x01)
|
#define EMBER_MAX_COMMAND_ARGUMENTS 16
|
The maximum number of arguments a command can have. A nested command counts as an argument.
#define emberCommandEntryAction
|
(
|
|
name,
|
|
|
|
action,
|
|
|
|
argumentTypes,
|
|
|
|
description
|
|
)
|
|
{ (name), (action), (argumentTypes), (description),
NULL
}
|
#define emberCommandEntryActionWithDetails
|
(
|
|
name,
|
|
|
|
action,
|
|
|
|
argumentTypes,
|
|
|
|
description,
|
|
|
|
argumentDescriptionArray
|
|
)
|
|
{ (name), (action), (argumentTypes), (description), (argumentDescriptionArray) }
|
#define emberCommandEntrySubMenu
|
(
|
|
name,
|
|
|
|
subMenu,
|
|
|
|
description
|
|
)
|
|
{ (name),
NULL
, (const char *)(subMenu), (description),
NULL
}
|
#define emberCommandInterpreterEchoOff
|
(
|
|
)
|
|
Value:
uint8_t emberCommandInterpreter2Configuration
#define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO
Definition:
command-interpreter2.h:251
Turn echo of command line off.
#define emberCommandInterpreterEchoOn
|
(
|
|
)
|
|
Value:
uint8_t emberCommandInterpreter2Configuration
#define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO
Definition:
command-interpreter2.h:251
Turn echo of command line on.
#define emberCommandInterpreterIsEchoOn
|
(
|
|
)
|
|
Value:
uint8_t emberCommandInterpreter2Configuration
#define EMBER_COMMAND_INTERPRETER_CONFIGURATION_ECHO
Definition:
command-interpreter2.h:251
Returns true if echo is on, false otherwise.
A convenience macro for copying eui64 arguments to an EmberEUI64.
#define emberCopyKeyArgument
|
(
|
|
index,
|
|
|
|
keyDataPointer
|
|
)
|
|
|
Value:
true
))
uint8_t emberCopyStringArgument(int8_t argNum, uint8_t *destination, uint8_t maxLength, bool leftPad)
#define EMBER_ENCRYPTION_KEY_SIZE
Size of an encryption key in bytes (16).
Definition:
ember-types.h:121
uint8_t * emberKeyContents(EmberKeyData *key)
This function allows access to the actual key data bytes of the EmberKeyData structure.
A convenience macro for copying security key arguments to an
EmberKeyData
pointer.
A convenience macro for copying security key arguments to an
EmberKeyData
pointer.
Process 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.
1
void emberProcessCommandInput(uint8_t port);
typedef void(* CommandAction) (void)
|
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
|
|
The application may implement this handler. To override the default handler, define EMBER_APPLICATION_HAS_COMMAND_ACTION_HANDLER in the CONFIGURATION_HEADER.
uint8_t emberCommandArgumentCount
|
(
|
void
|
|
)
|
|
Returns the number of arguments for the current command.
void emberCommandClearBuffer
|
(
|
void
|
|
)
|
|
bool emberCommandInterpreterBusy
|
(
|
void
|
|
)
|
|
Returns true interpreter is reading a command.
const char* emberCommandName
|
(
|
void
|
|
)
|
|
A convenience macro for copying security key arguments to an
EmberKeyData
pointer.
void emberCommandReaderInit
|
(
|
void
|
|
)
|
|
Initialize the command interpreter.
void emberCommandReaderSetDefaultBase
|
(
|
uint8_t
|
base
|
)
|
|
uint8_t emberCopyBigEndianEui64Argument
|
(
|
int8_t
|
index,
|
|
|
EmberEUI64
|
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.
uint8_t emberCopyStringArgument
|
(
|
int8_t
|
argNum,
|
|
|
uint8_t *
|
destination,
|
|
|
uint8_t
|
maxLength,
|
|
|
bool
|
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.
void emberPrintCommandTable
|
(
|
void
|
|
)
|
|
void emberPrintCommandUsageNotes
|
(
|
void
|
|
)
|
|
bool emberProcessCommandString
|
(
|
uint8_t *
|
input,
|
|
|
uint8_t
|
sizeOrPort
|
|
)
|
|
|
Process the given string as a command.
int32_t emberSignedCommandArgument
|
(
|
uint8_t
|
argNum
|
)
|
|
Retrieves signed integer arguments.
bool emberStringArgumentToHostOrderIpv4Address
|
(
|
uint8_t
|
argNum,
|
|
|
uint32_t *
|
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.
uint8_t* emberStringCommandArgument
|
(
|
int8_t
|
argNum,
|
|
|
uint8_t *
|
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].
bool emberStringToHostOrderIpv4Address
|
(
|
const uint8_t *
|
string,
|
|
|
uint32_t *
|
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.
uint32_t emberUnsignedCommandArgument
|
(
|
uint8_t
|
argNum
|
)
|
|
Retrieves unsigned integer arguments.
uint8_t emberCommandInterpreter2Configuration
|
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.