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

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.

       
       // 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. See ::argumentTypes for details.
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 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 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:

         (
         
          emberGetStringArgument
         
         ((index),                            \
        
          emberKeyContents
         
         ((keyDataPointer)), \
        
          EMBER_ENCRYPTION_KEY_SIZE
         
         ,          \
        
          TRUE
         
         ))

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:

         (
         
          emberGetStringArgument
         
         ((index),                            \
        
          emberKeyContents
         
         ((keyDataPointer)), \
        
          EMBER_ENCRYPTION_KEY_SIZE
         
         ,          \
        
          true
         
         ))

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

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 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[]

Command Interpreter Plugin Silicon Labs Connect Application Framework API Reference

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Command Table Settings

Functions to Retrieve Arguments

Detailed Description

License

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation

Command Interpreter Plugin
Silicon Labs Connect Application Framework API Reference