Remote Configuration Tool

Overview

The remote configuration tool is used to generate a device configuration header file and upload device configuration information to Device Cloud. It allows you to define all device configuration data and information that can be accessed through Device Cloud using Cloud Connector. You must include the generated header file and provide callback functions to handle all device configuration within an application.

Usage

Usage

java -jar ConfigGenerator.jar [-help] [-verbose] [-nodesc] [-vendor] [-path] [-url] <"username"[:"password"]> <device_type> <firmware_version> <input_config_file>

Description

Generates and uploads configuration information (descriptors) to Device Cloud and also generates ANSI C header files (remote_config.h) from the input Cloud Connector configuration file. This header file must be included in the application.

Options

• -help Shows help message.
• -verbose Optional output messages regarding what the tool is doing.
• -nodesc Optional exclusion of error descriptions in the generated file. Error descriptions will not be included and sent to Device Cloud when an error is encountered. This is used to reduce the code size.
• -vendor Optional Vendor ID obtained during the Device Cloud Setup process. If a Vendor ID is not given, the tool tries to retrieve it from Device Cloud.
• -path Optional directory path where the generated file will be created.
• -url Optional for the Device Cloud URL; default is login.etherios.com.
• username Username used to log in to Device Cloud.
• password Optional password used to log in to Device Cloud. If this is not specified in the command line, you will be prompted for your password.
• device_type Device type string with quotes.
• firmware_version Firmware version number (i.e. 1.0.0.0).
• input_config_file Input configuration file, see the Input Configuration File section below for more information.

NOTE: username, password,vendor_id, device_type and firmware_version are used for accessing your Device Cloud account and uploading device configuration information (descriptors) for your device.

Example:

java -jar ConfigGenerator.jar username:password "Linux Application" 1.0.0.0 config.rci

Location

ConfigGenerator.jar is located within the [Etherios_Cloud_Connector_Installation_Path]\Tools\ folder.

Input Configuration File

You must define all device configuration data and system information that is accessed through Device Cloud, and run the tool to generate the remote_config.h file. When doing so you must include the remote_config.h header file and provide callbacks to handle all device configuration data and system information.

The following keywords should be used to define device configuration data and system information:

1. globalerror keyword
2. group keyword
3. error keyword
4. element keyword
5. type keyword
6. value keyword
7. min keyword
8. max keyword
9. access keyword
10. units keyword
11. Comment Tag

globalerror keyword

A globalerror is used to define the text in Device Cloud when an error condition occurs. Globalerrors define errors common to all configurations.

Syntax

globalerror <name> <description>

Options

• name Label (no spaces) of the error.
  The tool creates <name> with connector_global_error_ prefix enumeration value for each error. This error enumeration value will be used by the application-defined callback to return an error which is sent along to Device Cloud.
• description Error string message with quotes (e.g. "Unable to write to NVRam"). This description is sent to Device Cloud along with the enumeration value.

Example:

	globalerror load_fail "Unable to load configuration"

	globalerror save_fail "Unable to save configuration"

	globalerror memory_fail "Insufficient memory"

The enumeration values:

	connector_global_error_load_fail

	connector_global_error_save_fail

	connector_global_error_memory_fail

group keyword

A group is used to define device configuration data and information about the current state of the device. It contains metadata about the element named in the element keyword.

Syntax

group <type> <name> [count] <description> [help_description]

Options

• type:
  • setting = device configuration data
  • state = information about the current state of the device
• name Label (no spaces) of the group.
  The tool creates <name> with connector_<type>_ prefix enumeration value to identify the group. Cloud Connector passes this enumeration value to the application-defined callback for accessing the group.
• count Optional for number of array instances of the group. If count is not given, the group has only 1 instance.
• description Description for this group with quotes, suitable for displaying in a generic GUI to represent this group. This is only used in the descriptor. It must be 40 characters or less.
• help_description Optional description with quotes for extra information shown as a tool-tip and help text.

Example:

group setting serial 2 "Serial Port"

group state system_info "System Information"

The enumeration values:

connector_setting_serial

connector_state_system_info

error keyword

An error is used to define the text in Device Cloud when an error condition occurs. It is used to specify an error for an individual group.

Syntax

error <name> <description>

Options

• name Label (no spaces) of the error.
  The tool creates <name> with connector_<group_type>_<group_name>_error_ prefix enumeration value for each error. This error enumeration value will be used by the application-defined callback to return an error which is sent along to Device Cloud.
• description Error string message with quotes (e.g. "Invalid data bits rate"). This description is sent to Device Cloud along with the enumeration value.

Example:

error invalid_databits "invalid data bits rate"

The enumeration values:

connector_setting_serial_error_invalid_data

element keyword

An element is used to describe valid fields in a group. It describes an element under the group that has a type and contains a value.

Syntax

element <name> <description> [help_description] type <type_value> [min <min_value>] [max <max_value>] [access <access_value>] [units <units_description>]

Options

• name Label (no spaces) of the element.
  The tool creates <name> with connector_<group_type>_ prefix enumeration value to identify the element. Cloud Connector passes this enumeration value to the application-defined callback for accessing the element.
• description Description for this element with quotes, suitable for displaying in a generic GUI to represent this element. This is only used in the descriptor. It must be 40 characters or less.
• help_description Optional description with quotes for extra information shown as a tool-tip and help text.
• type see type keyword.
• min see min keyword.
• max see max keyword.
• access see access keyword.
• units see units keyword.

Example:

element ip_addr "Static IP Address" type ipv4 access read_write

The enumeration values:

connector_setting_ethernet_ip_addr

type keyword

"type" is used to indicate the value type of an element's value named in the element keyword. Type is use to indicate to the descriptor user which restrictions to place on a value and how to interpret a value received from Cloud Connector.

Syntax

type <value>

value

• string Single line string with null-terminated.
• multiline_string This type is used for a null-terminated string that may be more than one line. A "text area" is shown in Device Cloud that allows a user to form multiple lines by pressing enter.
• password This Password type is the same as the string type except "*" are shown instead of characters when a user types within Device Cloud.
• int32 32-bit signed integer value.
• uint32 32-bit unsigned integer value.
• hex32 32-bit unsigned hexadecimal
• 0x_hex32 32-bit unsigned hexadecimal with 0x prefix shown in Device Cloud.
• float Floating value float.h is included in the generated header file.
• enum enum is used to define a set of allowed values for an element. This is a pull-down menu shown in Device Cloud. See value keyword to define set of enum values for the element.
  Note: min and max keywords will throw an error.
• on_off "on" or "off " value. Application-defined callback should use connector_on value for "on" or connector_off value for "off". This type is shown as radio buttons in Device Cloud.
  Note: min and max keywords will throw an error.
• boolean true or false. Application-defined callback should use connector_true value for true or connector_false value for false.
  Note: min and max keywords will throw an error.
• ipv4 Valid IPv4 address (32-bit value) which is shown aaa.bbb.ccc.ddd in Device Cloud.
  Note: min and max keywords will throw an error.
• fqdnv4 This type accepts either ipv4 or DNS name.
• fqdnv6 This type accepts either IPv6 address, IPv4 address, or DNS name.
• datetime Date and time type. It's a null-terminated string which contains the ISO 8601 standard for date and time representation. The format is: YYYY-MM-DDTHH:MM:SStz where:
  • YYYY:Year
  • MM: Month
  • DD: Day
  • T: The separator between date and time
  • HH: Hours in 24-hour clock
  • MM: Minutes
  • SS: Seconds
  • tz: Time zone, specified either in the form [+,-]HHMM or Z for Coordinated Universal Time (UTC)
  Examples:
  "2002-05-30T09:30:10-0600"
"2002-05-30T15:30:10Z"
  Note: min and max keywords will throw an error.

Example:

element ip_addr "Static IP Address" type ipv4 access read_write

value keyword

"value" is used to define a set of values for an element named in the element keyword with enum type (type keyword).

Syntax

value <name> [description] [help_description]

Options

• name Label (no spaces) of the enum value.
  The tool creates <name> with connector_<group_type>_<group_name>_<element_name>_ prefix enumeration value for each values. Cloud Connector and the application-defined callback use this enumeration value to set and retrieve the value of an element.
• description Optional description for this value with quotes, suitable for displaying in a generic GUI to represent this element. This is only used in the descriptor. It must be 40 characters or less.
• help_description Optional description with quotes for extra information shown as a tool-tip and help text.

Example:

	element baud "Baud rate" type enum access read_write

		value auto "Automatic"

		value 1200

		value 2400

		value 9600

		value 19200

The enumeration values:

	connector_setting_serial_baud_auto

	connector_setting_serial_baud_300

	connector_setting_serial_baud_2400

	connector_setting_serial_baud_9600

	connector_setting_serial_baud_19200

min keyword

"min" is used to specify minimum value or length of an element.

Syntax

min <value>

Options

• value Minimum value or length in bytes.
  Device Cloud will validate this range check. The user can do additional checks, as well.

Example:

element setting sys_password type password min 8 max 31

max keyword

"max" is used to specify maximum value or length of an element.

Syntax

max <value>

Options

• value Maximum value or length in bytes.
  Device Cloud will validate this range check. The user can do additional checks, as well.

Example:

element setting sys_password type password min 8 max 31

access keyword

"access" is used to define accessibility of an element named in the element keyword; default is read_write. This tells Cloud Connector and Device Cloud whether an element is settable or not. It's grayed out if read_only is specified.

Syntax

access <value>

value

• read_only Read only element.
• write_only Write only element.
• read_write Read and write element.

Example:

element setting sys_password type password access read_only min 8 max 31

units keyword

"units" is used to define the displayed text in Device Cloud. It's used as the units for the element.

Syntax

units <description>

Options

• description Units string with quotes (e.g. "seconds"). This description is shown in Device Cloud.

Example:

element sys_up_time "System up time" type uint32 access read_only units "seconds"

Comment Tag

The # symbol is used for comments. Any sequence of characters after # will be treated as a comment and will not be processed.

Example:

# State configuration for GPS

# Must setup the following group in order for GPS shown in Device Cloud.

Input Configuration File Sample

globalerror load_fail "Load fail"

globalerror save_fail "Save fail"

globalerror memory_fail "Insufficient memory"

group setting serial 2 "Serial Port" "Port 1 is used for printf"

	element baud "Baud rate" type enum access read_write

		value 2400

		value 4800

		value 9600

		value 19200

		value 38400

		value 57600

		value 115200

		value 230400

	element parity "Parity" type enum access  read_write

		value none

		value odd

		value even

	element databits "Data bits" type uint32 access  read_write  min  5 max  8

	element xbreak "Tx Break" type on_off access  read_write

	element txbytes "Tx bytes" type uint32 access  read_only

	error invalid_baud "Invalid baud rate "

	error invalid_databits "Invalid data bits"

	error invalid_parity  " Invalid parity"

	error invalid_xbreak "Invalid xbreak setting"

	error invalid_databits_parity "Invalid combination of data bits and parity"

group setting device_info  "Device info"

	element product "Product" type string access  read_write  min  1 max  64

	element model "Model" type string access  read_write  min  0 max  32

	element company "Company" type string access  read_write

	element desc "Description" type multiline_string access  read_write

	element syspwd "System password" type password access  read_write  max  64

	error invalid_length "invalid length"

group state debug_info "Debug info on Cloud Connector thread"

	element version "Version" type string access  read_only

	element stacktop "Stack begin" type 0x_hex32 access  read_only

	element stacksize "Stack size" type hex32 access  read_only

	element stackbottom "Stack end" type 0xhex access  read_only

	element usedmem "Allocated memory used" type uint32 access  read_only

# State configuration for GPS

# Must setup the following group in order for GPS shown in Device Cloud.

group state gps_stats "GPS"

	element latitude "Latitude" type float access read_only

	element longitude "Longitude" type float access read_only