Parameter Dictionaries

This chapter describes Parameter Dictionaries which are used in the process of configuring and managing customer premises equipment (CPE) for CWMP.

This chapter includes the following sections:

Overview

Parameter dictionaries are XML files that list valid objects and parameters that Cisco BAC uses to configure a CWMP device. The dictionaries validate the objects and parameters used in the configuration and firmware rule templates.

Parameter dictionaries provide metadata about the supported objects and parameters, such as name, type, writeability and readability. Each dictionary is stored in a file and added to the RDU through the management API or the administrator user interface.

Configuration and firmware rule templates include a ParameterDictionary tag, an indicator of which dictionary defines the parameters in a given template. Cisco BAC validates configuration and firmware rule templates by using the dictionary to which the templates refer. All parameter names and values in the configuration and firmware rule template must be compatible with the parameters referenced in the parameter dictionary.

Figure 7-1 illustrates the schema of a parameter dictionary.

Figure 7-1 Parameter Dictionary Schema

 

Configuration or firmware rules template processing fails during instruction generation if there are errors in the template. To avoid configuration instruction generation errors, ensure that all:

  • The object names and parameter names exist in the dictionary.
  • The parameter values specified in templates directly or through substitutable parameters are of the type specified in the dictionary.
  • Parameters that are not writable do not have a value. However, they may have the notification, access control, or both attributes set in configuration templates.

Using Default Dictionaries

This Cisco BAC release provides default dictionaries according to the parameters defined in the TR-069, the TR-098, TR-104, TR-181, and the TR-196 specifications. Each of the specifications cover the following data models:

  • TR-069—Internet Gateway Device data model 1.0.
  • TR-098—Internet Gateway Device data model 1.1, including extensive QoS capabilities.
  • TR-104—VoIP data model for gateway or standalone ATA.
  • TR-181—Device data model for TR-069 issue 2 amendment 2.
  • TR-196—Femto Access Point Service data model amendment 1 and issue 2.

For administrative convenience, the basic-cwmp-dictionary.xml dictionary provides a combination of all standard parameters (TR-098 and TR-104).

These default dictionaries are located at:

  • <BPR_HOME>/rdu/templates/cwmp/dictionary/tr069-cwmp-dictionary.xml
  • <BPR_HOME>/rdu/templates/cwmp/dictionary/tr104-cwmp-dictionary.xml
  • <BPR_HOME>/rdu/templates/cwmp/dictionary/tr098-cwmp-dictionary.xml
  • <BPR_HOME>/rdu/templates/cwmp/dictionary/tr196-cwmp-dictionary-v1.1.xml
  • <BPR_HOME>/rdu/templates/cwmp/dictionary/tr196-cwmp-dictionary-v2.0.xml
  • <BPR_HOME>/rdu/templates/cwmp/dictionary/tr196-cwmp-dictionary-IGD-v1.1.xml
  • <BPR_HOME>/rdu/templates/cwmp/dictionary/tr196-cwmp-dictionary-IGD-v2.0.xml
  • <BPR_HOME>/rdu/templates/cwmp/dictionary/basic-cwmp-dictionary.xml

Note You cannot modify or delete the default dictionaries in Cisco BAC.


You can add new user-defined dictionaries that templates reference. This feature enables Cisco BAC support for CPE parameter models, including vendor-specific parameters. For additional information, see the subsequent section on Custom Dictionaries. Cisco BAC support for vendor-specific dictionaries enables its use with any emerging data models such as WT-135 (IPTV STB) or WT-140 (NAS).

Custom Dictionaries

CWMP includes an extensibility mechanism that allows the use of vendor-specific parameters in addition to the standard parameters. Thus, you can add custom dictionaries to the Cisco BAC system to support any CPE. You can use this feature to support devices with practically any data model, including emerging standard data models such as WT-135 (IPTV STB) or WT-140 (NAS).

You can add, view, replace, or delete custom dictionaries to or from Cisco BAC through the administrator user interface or the management API.


Note You cannot use custom dictionaries for configuration templates. Cisco BAC configuration templates can only use the parameter dictionaries in the Cisco BAC database.

While adding custom dictionaries, ensure that they are based on the parameter dictionary schema, described in earlier sections.


Parameter Dictionary Syntax

Cisco BAC validates the syntax of a parameter dictionary according to the Parameter Dictionary Schema, located at <BPR_HOME>/rdu/templates/cwmp/TemplateDictionarySchema.xsd.

If you want to add a vendor-specific parameter to a standard object, remember to define all higher-level standard objects and their parameters in the custom dictionary.

Cisco BAC supports all data types that are defined in the TR-069 and TR-196 specification. The Parameter Dictionary specifies the data types that this Cisco BAC release supports, as listed in Table 7-1 :

Table 7-1 Cisco BAC Supported Data Types

Type
Description

String

A maximum allowed length may be listed using the string (N) syntax, where (N) is the maximum string length in characters.

You can also give a value range by using the string[Min:Max] syntax, where the Min and the Max values are inclusive. If Min or Max are missing, this indicates no limit.

int

An integer in the range of -2147483648 to +2147483647, inclusive.

You can give a value range by using the int[Min:Max] syntax, where the Min and the Max values are inclusive. If Min or Max are missing, this indicates no limit.

unsignedInt

An unsigned integer in the range 0 to 4294967295, inclusive.

You can give a value range using the unsignedInt[Min:Max] syntax, where the the Min and the Max values are inclusive. If Min or Max are missing, this indicates no limit.

boolean

A value, where 1 represents true, and 0 represents false.

dateTime

The time expressed in UTC (Universal Coordinated Time) unless stated otherwise; for example, 2004-01-03T03:04:05-(or +)05:00

base64

You can use the base 64 (N) syntax to specify a maximum allowed length, where (N) is the maximum length in characters after Base64 encoding.

hexBinary

You can use the hexBinary (N) syntax to specify a maximum allowed length, where (N) is the maximum length in characters after hex encoding.

You can also give a value range by using the int[Min:Max] syntax, where the Min and the Max values are inclusive. If Min or Max are missing, this indicates no limit.

Sample Parameter Dictionary

The following is a sample from the TR-069 parameter list, with its corresponding dictionary schema:

 

Name
Type
Write
Read

InternetGatewayDevice

Object

-

R

InternetGatewayDevice.DeviceInfo

Object

-

R

X_HGI_ALG

Object

-

R

X_08017_ChipModel

string

-

R

ALGNumberOfEntries

unsignedInt

-

R

Manufacturer

string(64)

-

R

<ParameterDictionary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="TemplateDictionarySchema.xsd">
<Object name="InternetGatewayDevice">
<Object name="DeviceInfo">
<Writable>false</Writable>
<Parameter>
<Name>Manufacturer</Name>
<Type>string(64)</Type>
<Readable>true</Readable>
<Writable>false</Writable>
</Parameter>
<Parameter>
<Name>X_08017_ChipModel</Name>
<Type>string</Type>
<Readable>true</Readable>
<Writable>false</Writable>
</Parameter>
</Object>
<!-- custom property: InternetGatewayDevice.X_HGI_ALG -->
<!-- as defined for HGI's Application Layer Gateway Management -->
<Object name="X_HGI_ALG">
<Parameter>
<Name>ALGNumberOfEntries</Name>
<Type>unsignedint</Type>
<Readable>true</Readable>
<Writable>false</Writable>
</Parameter>
</Object>
</Object>
</ParameterDictionary>
 

The following is a sample from the TR-196 Issue 2 Femto Access Point Service Data Model (FAPService:2.0) parameter list (which supports LTE), with its corresponding dictionary schema:

 

Name
Type
Write
Read

Device.Services.FAPService.1.
FAPControl.LTE.Gateway

Object

W

R

SecGWServer1

string(64)

W

R

S1SigLinkServerList

string(256)

W

R

S1SigLinkPort

unsignedInt

W

R

<ParameterDictionary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="TemplateDictionarySchema.xsd">
<Object name="Device">
<Object name="Services">
<Object name="FAPService">
<Object name="FAPControl">
<Object name="LTE">
<Object name="Gateway">
<Writable>true</Writable>
<Parameter>
<Name>SecGWServer1</Name>
<Type>string(64)</Type>
<Readable>true</Readable>
<Writable>true</Writable>
</Parameter>
<Parameter>
<Name>S1SigLinkServerList</Name>
<Type>string(256)</Type>
<Readable>true</Readable>
<Writable>true </Writable>
</Parameter>
<Parameter>
<Name>S1SigLinkPort</Name>
<Type>unsignedInt</Type>
<Readable>true</Readable>
<Writable>true </Writable>
</Parameter>
</Object>
</Object>
</Object>
</Object>
</Object>
</Object>
</ParameterDictionary>
 

Managing Parameter Dictionaries through User Interface

You can use the administrator user interface to manage parameter dictionary files, and view, add, delete, or replace parameter dictionaries. To export files, see Exporting Files.


Note You cannot modify or delete the default dictionaries.


Adding Parameter Dictionaries

To add a new parameter dictionary to the Cisco BAC RDU database:


Step 1 Choose Configuration on the Primary Navigation bar.

Step 2 Choose Files on the Secondary Navigation bar. The View Files page appears.

Step 3 Click Add.

The Add Files page appears.

Step 4 Choose Parameter Dictionary from the File Type drop-down list.

Step 5 Browse for the Source File Name.

Step 6 Enter the File Name.

Step 7 Click Submit.

The View Files page appears with the new file.


 

Viewing Parameter Dictionaries

To view the content of a file in the Cisco BAC RDU database:


Step 1 Choose Configuration on the Primary Navigation bar.

Step 2 Choose Files on the Secondary Navigation bar.

The View Files page appears.

Step 3 From the File Type drop-down list, select Parameter Dictionary.

Step 4 Click the View Details icon () corresponding to the file that you had specified for a search.

The content of the Parameter Dictionary appears.


 

Deleting Parameter Dictionaries

To delete an existing parameter dictionary from the RDU database:


Note You cannot delete built-in default dictionaries.



Step 1 Choose Configuration > Files.

Step 2 From the File Type drop-down list, select Parameter Dictionary.

Step 3 Check the file you want to delete.

Step 4 Click Delete.

The View Files page appears without the deleted file.


 

Replacing Parameter Dictionaries

To replace the content of an existing parameter dictionary file in the Cisco BAC RDU database:


Note You cannot modify built-in default dictionaries.



Step 1 Choose Configuration > Files.

Step 2 From the File Type drop-down list, select Parameter Dictionary.

Step 3 From the search results, click the link corresponding to the file you want to replace.

The Replace File page appears. Note that the selected filename already appears on this page.

Step 4 Browse for the source file to be used as a replacement for the displayed file.

Step 5 Click Submit.

After submitting the replacement file, a confirmation page appears to indicate that, after replacement, Cisco BAC will regenerate instructions for the affected devices.

Step 6 Click OK.

The View Files page appears.