Overview

An arbitrary class of devices, including any TR-069 enabled device, can be represented in RM by using the control unit model and therefore can be managed in a unified way. To represent a device as a set of control units (CUs), there should be one or more Control Unit Providers, which will represent the specific devices as hierarchies of control unit objects.

However, RM offers enhanced mapping between the data models of TR-069 and RM, i.e. between parameters trees and control units respectively. In this case, you do not have to implement any Control Unit Providers, but only write a Tree-to-CU Mapping XML file. RM will automatically register Control Unit Providers for the control units involved in Tree-to-CU Mapping file.

A Tree-to-CU Mapping XML file is an extension of the regular CU metatype and specifies the following metadata:

• The metatype, which describes the interface of the control unit type – the number and the type of the state variables and actions, parent relations, etc. See the Control Unit Metatypes section of Generic Device Management documentation for more details on control unit metadata.

• The exact mapping between concrete TR-069 parameter nodes and the control unit components. In particular, the mapping is done by appending to certain CU metatype elements associations between:

  • node paths and control unit IDs

  • state variables and node attributes

  • actions and TR-069 command sequences.

Mapping Elements

Tree Nodes

Generally, tree nodes have name, path and path separator attributes with the following meaning:

• Name – A string that does not contain a path separator character (or it is escaped).

• Path – The full path in the tree that locates the target node. For TR-069, the root of the tree has path "". The node names within the path are divided with separators.

  For TR-069 you could use a parameter @ROOT which denotes the TR-069 tree root (i.e. Device. or InternetGatewayDevice.). There is an important difference betweent this TR-069 tree root and the mapping root – the latter adds "" as a representer of the device itself.

• Separator – A symbol that separates the names in a path. For TR-069, it is . (dot).

For example, X.Y.Z is a node with name Z and path X.Y.Z into a TR-069 device tree with separator . (dot).

Patterns

A Tree-to-CU mapping file can contain patterns which locate in a best way the proper nodes to execute the CU transformation upon. Patterns are matched by the RM TR-069 System at runtime against the parameter structure of a device, and a separate control unit instance is defined for every distinct match. During this process, the pattern variables are assigned the matched node names (i.e. TR-069 parameters) and can be potentially used in the definition of the other CU elements – IDs, parent IDs, state variables and actions.

• Filter – It is a String containing one or more variables, enclosed in curly brackets ({}), that should or shouldn't contain a separator. Filters can be used to filter nodes without control unit context while Parameterized Filters, described next, can use such a context.

  There are four types of variables that a filter might contain:

  • {*} – Unnamed variable that will match a part of a node name (a part of a path that contains a separator won't match this pattern)

  • {**} – Unnamed variable that will match a part of a node path including the separators within the path (a part of a path that contain a separator could match this pattern)

  • {x=*} – Named variable that will match a part of a node name (a part of a path that contains a separator won't match this pattern)

  • {x=**} – Named variable that will match a part of a node path (a part of a path that contains a separator could match this pattern)

    Named variables can be included into contexts and used in filtering based on Parametrized Filters or in Parameterized Strings evaluation.

    For example, we can have the following filters:

    
    

    Device.Services.OSGi.{id=*}.MyService

     

    Device.Services.{id=**}.MyService

     

    Device.Services.*.MyService

     

    Device.Services.OSGi.{**}.MyParameter

     

    Device.Services.OSGi.{id=*}.MyService.{comp=*}.Param0

    
    

• Parameterized Filter – It can contain the four variable types we have discussed into the Filter definition but can also include parameters that must be substituted with values before applying the filter. The parameter is a name into curly brackets ({}), for example {x}.

  If a Parameterized Filter contains parameters, it must be applied within a context that contains values for all its parameters.

  For instance, we might have the following Parameterized Filter. It contains a parameter {id} which must be evaluated prior to applying the filter and a named variable {comp=*} which can be later used as a parameter:

  Device.Services.OSGi.{id}.MyService.{comp=*}.Param1

• Parameterized String – It contains only node or attribute selector parameters. It is not used for filtering but just for evaluation. For example, the next Parameterized String contains parameters {id} and {comp}, which have to be substituted with actual values. In addition, the snippet uses a parameter {@ROOT}, which represents the root of the TR-069 tree - Device or InternetDeviceGateway:

  Device.Services.OSGi.{id}.MyService.{comp}.Param1  
  {@ROOT}Services.OSGi.{id}.MyService.{comp}.Param1

  Device.Services.OSGi.{id}.MyService.{comp=*}.Param1

• Attribute selector – It selects an attribute of a node:

  Device.Services.OSGi.{id}.MyService.{comp}.Param1@value

• Expression – It is a Parameterized String that contains a query for a TR-069 node attribute. The query contains two parts – node name (a Parameterized String) and an attribute name, separated with @. The whole statement must be enclosed in curly brackets to become a qualified expression.

  Following is an example expression which evaluates to the value of the value attribute of the node Device.Services.OSGi.{id}.MyService.{comp}.Param1.

  {Device.Services.OSGi.{id}.MyService.{comp}.Param1@value}

  The expression can also mix parameters, attribute queries like:

  • {Device.Services.OSGi.{id}.MyService.{comp}.Param1@value}-123-{id}-{comp)-abc-{Device.Services.OSGi.{id}.MyService.{comp}.Param1@name}

  Generally, the TR-069 Device Manager has knowledge of the following node attributes:

  • path – A string representing the path of a TR-069 parameter tree node.

  • name – A string representing the name of a TR-069 parameter parameter tree node.

  • type – An integer representing the accessibility (read-only or read-write) and the data type of the attribute. type can have the following values:

    • 5 – Read-only object

    • 9 – Read-write object

    • 37 – Read-only parent node of a multi instance object

    • 41 – Read-write parent node of a multi instance object

    • 21 – Read-only multi instance object

    • 25 – Read-write multi instance object

    • 582 – Read-only string

    • 586 – Read-write string

    • 1158 – Read-only integer

    • 1162 – Read-write integer

    • 2182 – Read-only boolean

    • 2186 – Read-write boolean

    • 4230 – Read-only date-time

    • 4234 – Read-write date-time

    • 8326 – Read-only unsigned integer

    • 8330 – Read-write unsigned integer

    • 16646 – Read-only base64 encoded binary

    • 16650 – Read-write base64 encoded binary

    • 32902 – Read-only long

    • 32906 – Read-write long

    • 65670 – Read-only unsigned long

    • 65674 – Read-write unsigned long

    • 131334 – Read-only hexadecimal binary

    • 131338 – Read-write hexadecimal binary

• value – The value of the TR-069 parameter node of the relevant type (string, integer, long, boolean, date, byte array)

• notification.attribute – An integer representing the notification property of the parameter - 0 for off, 1 for passive or 2 for active, as defined in the TR-069 standard.

• access.list – A string array showing the entities beside the ACSs that are granted access to the TR-069 node.

• Condition – Implies a requirement on the TR-069 node attributes. It is defined by a binary operation (returning boolean result), an attribute query and a constant/attribute query. We might have the following example conditions:

  Device.Services.OSGi.{id}.MyService.{comp}.Param1@value > 10
  Device.Services.OSGi.{id}.MyService.{comp}.Param1@value > Device.Services.OSGi.{id}.MyService.{comp}.Param2@value

  
  

The supported binary operations are:

• == – equals

• != – not equal to

• < – less than

• > – greater than

• <= – less than or equal to

• >= – greater than or equal to

• << – is contained (the left operand is contained into the right operand (as strings))

• >> – contains (the left operand contains the right operand)

• <<< – is contained in a list, whose entries are separated with ',' (comma). The right operand is interpreted as a comma-separated list.

• >>> – list, whose entries are separated with ',' (comma) contains. The left operand is interpreted as a comma-separated list.

• <<<< – is contained in a list, whose entries are separated with ' ' (empty space). The right operand is interpreted as a space-separated list.

• >>>> – list, whose entries are separated with ' ' (empty space) contains. The left operand is interpreted as a space-separated list.

Mapping XML Files

File Location

Place your tree-to-CU mapping XML files in a sub-directory of the initial_config/tree2cu one inside RM.

XML Schema

The XML schema of the Tree-to-CU mapping file format is available as schema.xsd in the initial_config/tree2cu directory of RM.

Primitives

path-pattern – Represents the definition of a set of nodes matching all specified terms. Note that a path pattern can contain an attribute singleSource (true by default), which if false allows forming a control unit/parent control unit from several source paths matching the pattern.

The following elements can participate in a path pattern:

• path – A Parameterized Filter (presently, filter's variables can be only system properties and properties within the relevant context). For instance:

  Device.Services.OSGi.{id}

  
  

• condition – A condition pattern (see above). A path-pattern can have multiple conditions, each introducing additional constraints over the nodes compared with the matching pattern. A path matches the path pattern only if all its conditions are satisfied.

  We might have the following condition:

    Device.Services.OSGi.{id}.MyService.{comp}.Param1@value > 10

Tree-to-CU Mapping

The actual tree-to-control unit mapping is represented by the cu-mapping element and its components. The cu-mapping must be inside the topmost objectclass of the control unit metatype and defines how a TR-069 parameter tree should be transformed into control units. Control units may form hierarchies based on parent-child relationships between them. Only one cu-mapping can be defined in a mapping file.

A cu-mapping contains the following sub-elements:

• path-pattern – Signifies the nodes for which the TR-069 Device Manager will generate specific control units as described in the previous section. The nodes that satisfy a pattern are called CU generators and for each of them a control unit is produced.

  Patterns can contain attribute selectors but they MUST be static (immutable over time) and available before the relevant CU generator is reached.

• cu-id – A Parameterized String that specifies the ID of the resulting control unit. The context implied by the CU generator node can be used for definition and evaluation of the ID.

  A Parameterized String can contain attribute selectors but they MUST be static (immutable over time) and available before the relevant CU generator is reached.

• cu-parents – Define a parent-child relationship between control units, and a cu-mapping can have more than one cu-parent. Use the following elements to introduce such as parent-child relationship:

  • path-pattern – Has the same meaning as when in a cu-mapping.

  • cu-type – The type of the parent control unit.

  • cu-id – A Parameterized String that declares the ID of the parent control unit. Has similar meaning as when in a cu-mapping.

A Tree-to-CU mapping might look like the following example, where {$residentialmanagement.osgi.root} stands for the value of the residentialmanagement.osgi.root system property:

\{\$ctx\}@name\; >\; 1

There is a special property ctx that you can use into a tree context (for later evaluations). Its value will be determined as the path of the node matching the associated path pattern. For instance, you might use ctx property in a pattern condition like this:

Node Attribute to CU State Variable Mapping

You can map the value of a control unit state variable to the values of one or more attributes of a parameter node. The mapping description can be added into the definition of the state variable, or can be placed outside it and then additionally associated.

Inside the Mapping XML File

• var-def – A Pattern Expression that can be added to the attribute definition for each state variable. Such an expression can take values from a set of attributes and then combine them. For instance, such a combined var-def could be:

  <var-def>{@model-{Node.X@value}_{{$ctx}Y@path}</var-def>

  
  

• ext-var-def – A Pattern Expression that can be defined outside the attribute definition for the corresponding state variable. By using this element, you can provide a mapping definition for state variables inherited from a control unit's super type. ext-var-def has similar semantics to var-def but with the next differences:

  • It should be a sub-element of the root objectclass, not of a state variable attribute.

  • It requires a mandatory attribute var-name that contains the name of the related state variable.

For example, the following versions of a state variable to node attribute mapping might be used (@MODEL stands for device model):

The following is an example of state variable to node mapping outside variable's definition:

By Providing a State Variable Mapping Plugin

Instead of specifying var-def or ext-var-def elements inside the mapping XML file, the values of certain state variables can also be determined and returned programmatically by a custom State Variable Mapping Plugin installed on the RM backend. The plugin has to register a com.prosyst.mprm.backend.tree2cu.spi.Var service in the OSGi framework of the RM backend with special registration properties as described in the API documentation of the Var interface.

CU Action to Scripts Mapping

You can map a control unit action to a script consisting of a sequence of SOAP method calls. The mapping description can be added into the definition of the action, or can be placed outside it and then additionally associated.

Inside the Mapping XML File

Mapping Elements

When mapping a control unit action to a sequence of method calls in a mapping file, use the following XML elements:

• action-def – In each action objectclass definition (such an objectclass element is a placed inside the top objectclass), you can additionally insert an action-def element that contains a sequence of RM-defined script commands or of SOAP method calls to be executed when the corresponding action is invoked e.g. from the Console.

• ext-action-def – By using this element, you can introduce a script for a control unit action outside action's objectclass element. In this way, you can provide a mapping definition for actions inherited from a super type. ext-action-def has the same semantics as action-def with the following differences:

  • It should be a sub-element of the root objectclass, not of action's objectclass.

  • It must contain an attribute action-name holding the name of the related action.

Commands in a Mapped Script

In the script you can use directly SOAP method calls to a CPE or some flexible script commands which take input from or place the results in the action context. RM provides the following script commands in the form of XML elements:

• Sync – Launches synchronization with a node. The parameter path to the target node is specified in the path attribute of Sync as a Parameterized String.

• Set – Sets a parameter described with the attributes key and value. Depending on the value of value, you can add an object or retrieve a TR-069 parameter value. Then, the result will be placed as value of the key attribute. To be able to use the result in subsequence method calls, set a variable {$<var_name>} as key value.

  • To add an object to the parameter tree of a CPE, set value to

    AddObject://<path_pattern>

    The result will be the instance ID of the created object and it will be assigned to the variable defined in key.

  • To get a node value from a CPE, set value to

    GetNodeValue://<path_pattern>

    The result will be available into the tree context as a value of the variable assigned to key.

• The <path_pattern> is a Parameterized String.

Following is an example for mapping a control unit action to a script, which contains both direct CPE method calls and RM-defined script commands:

Using Parameters and the Input Arguments to the Control Unit Action Inside a Script

You can place parameters inside the script, i.e. make it parameterized. The parameter values should be evaluated before the execution of the relevant command is reached.

Additionally to the context of the CU generator, the input arguments the CU action is invoked with are also accessible into the action context and you can use them within the script commands. To refer the arguments, use the variables {$0} for the first argument, {$1} for the second argument, etc.

Refer to the listing above for illustration of parametrization of action scripts.

By Providing an Action Mapping Plugin

You can map a control unit action, defined in a mapping XML file, to an Action Mapping Plugin so as to provide its sophisticated execution. In this case, implement a com.prosyst.mprm.backend.tree2cu.spi.Action service and register it in the OSGi framework of the RM backend with special registration properties as described in the API documentation of the Action interface. Pass the results from the action execution back to RM by calling the AsyncTaskListener provided as an argument to Action's invoke method.