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)
Processes 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)
Initializes the command interpreter. More...
bool emberProcessCommandString (const uint8_t *input, uint16_t sizeOrPort)
Processes the given string as a command. More...
uint8_t emberHexToInt (uint8_t ch)
Returns 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)
Parses 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)
Parses 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.

License

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code. Interprets 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 main command table.
15 EmberCommandEntry emberCommandTable[] = {
16 emberCommandEntrySubMenu("network", networkCommands, "Network form/join commands"),
17 emberCommandEntryAction("status", statusCommand, "Prints application status),
18 ...
19 emberCommandEntryTerminator()
20 };
21
22 // The table of network commands.
23 EmberCommandEntry networkCommands[] = {
24 emberCommandEntryAction("form", formCommand, "uvsh", "Form a network"),
25 { "join", joinCommand, "uvsh" },
26 ...
27 emberCommandEntryTerminator()
28 };
29
30 void main(void)
31 {
32 emberCommandReaderInit();
33 while(0) {
34 ...
35 // Process input and print prompt if it returns true.
36 if (emberProcessCommandInput(serialPort)) {
37 emberSerialPrintf(1, "%p>", PROMPT);
38 }
39 ...
40 }
41 }
  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. See ::argumentTypes for details.
    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 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 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

#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 116 of file command-interpreter2.h .

#define EMBER_COMMAND_INTEPRETER_HAS_DESCRIPTION_FIELD

Indicates 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 129 of file command-interpreter2.h .

#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 122 of file command-interpreter2.h .

#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 112 of file command-interpreter2.h .

#define emberCommand emberCommandEntryAction

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

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

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

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

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

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

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

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

A convenience macro for copying eui64 arguments to an EmberEUI64.

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

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

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

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

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

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.

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

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

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

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

#define emberNestedCommand emberCommandEntrySubMenu

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

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

Processes 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.
1 void emberProcessCommandInput(uint8_t port);

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

#define MAX_TOKEN_COUNT ( EMBER_MAX_COMMAND_ARGUMENTS + 1)

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

Typedef Documentation

typedef void(* CommandAction) (void)

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

typedef void EmberCommandErrorHandler( EmberCommandStatus status, EmberCommandEntry *command)

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

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

Enumeration Type Documentation

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 235 of file command-interpreter2.h .

Function Documentation

uint8_t emberCommandArgumentCount ( void )

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 )

Initializes the command interpreter.

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

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
)

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

bool emberGetIpPrefixArgument ( uint8_t index,
uint8_t * target
)

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

uint8_t emberGetStringArgument ( 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 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 zeroes. See emberGetKeyArgument and emberGetEui64Argument for convenience macros for this purpose.

uint8_t emberHexToInt ( uint8_t ch )

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

void emberInitializeCommandState ( EmberCommandState * state )

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

void emberPrintCommandTable ( void )
void emberPrintCommandUsage ( EmberCommandEntry * entry )
void emberPrintCommandUsageNotes ( void )
bool emberProcessCommandString ( const uint8_t * input,
uint16_t sizeOrPort
)

Processes the given string as a command.

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.

int32_t emberSignedCommandArgument ( uint8_t argNum )

Retrieves signed integer arguments.

uint8_t* emberStringCommandArgument ( int8_t argNum,
uint8_t * length
)

Retrieves 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].

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

Parses 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
)

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

uint32_t emberUnsignedCommandArgument ( uint8_t argNum )

Retrieves unsigned integer arguments.

Variable Documentation

EmberCommandEntry emberCommandTable[]