Mapping Configuration

The Device Access provides possibility to be specified which mappings to which devices to be applied. Mapping configurations have to be provided. Mapping are applied to the Device when device is added in the Device Access. In the mapping configuration is specified the name of the protocol adapter for which will be applied mappings. There are two main characteristics for the device item mapping configurations. The first is a filter criteria - for which devices provided form the protocol adapter to be applied the supported mapping. The second characteristic is set of configuration data for the mapping to be applied to the matched devices. The simple process is: the Device Access will match the device to the filter of each configuration and then apply the one that matched. The filter criteria has to be constructed according to device data provided by adapter. It is all data described in HomeDeviceSpi interface - name, vendor, version, type, tags, attributes. The user data provided in Device interface is not used.

The mapping configurations are described into declarative manner by structured XML files that are validated by the following XSD Schema. The XML mapping configurations are provided by separate bundles. This bundle have specific manifest header.

Manifest Header

The bundles that provide XML mapping configuration files have special manifest header – "DAMappingConfig" that has two attributes:

xml – this attribute declares the path to the XML mapping configuration file. This attribute is mandatory.
version – this attribute declares the version of the XML file. This attribute is optional. If there is no specified version, the default 0.0.0 version is used. This attribute is transformed into correct OSGi version (org.osgi.framework.Version) format.

The following examples show valid manifest headers:

xml=/resources/mapping-config.xml;version="1.0.0"
xml=/resources/mapping-config1.xml;version=1.0.0
xml=/resources/mapping-config2.xml

The next example shows the manifest header of Device Mapping Configuration Demo bundle:

DAMappingConfig:

xml=/xml/mapping.configs/da-demo-mapping-config.xml;version="1.0.0"

Semantic of XML elements

<mapping-configs>

The root element is <mapping-configs> and it is required. This element holds one or many child elements <mapping-config>. The <mapping-configs> tag has required attribute "adapter" that holds the name of the supported protocol adapter.

<mapping-configs adapter="DA Demo">

...

</mapping-config>

<mapping-config>

The <mapping-config> element is required and holds the configuration data about the mappings that has to be applied and filter to match the device. For this reason the <mapping-config> element has two child elements- <devices> and <mappings>. The <devices> element is optional and it is possible to have zero or one element. The <mappings> element is required and it is possible to have one or many elements.

<devices>

The <devices> is an optional element. It is used to filter the devices provided from the protocol adapter to which their device items mapping will be applied. The <devices> element has one or many <device> child elements. The provided devices comply or not to the Functional Item Management Specification. It depends on which XML attributes or which XML elements have to be described on the <device> child element. There are two main possible ways to describe the device filter – by LDAP filter or by device properties.

The <device> tag has an optional attribute ldap that holds the LDAP filter. This value must be encoded according to the LDAP specification. The following example shows an LDAP filter for all devices with model "High Precision":

</devices>

When this XML attribute is provided, then the other XML attributes or child elements on the <device> element must not be provided.

The <device> tag has the following optional attributes:

"type" – for holding the type of the device.
"vendor" – for holding the vendor of the device.
"version" – for holding the version of the device.
"name" – for holding the name of the device.

The <device> elements have the following optional child elements:

<device-properties> – this element has one or more child elements <device-property>. The <device-property> tag has two required attributes:
- "name" – for holding the name of the device property and
- "value" – for holding the value of the device property.
  <device-properties>
  
  <device-property name="property 1" value="property value 1" />
  
  <device-property name="property 2" value="property value 2" />
  
  </device-properties>

<tags> – this element has one or many child elements <tag>. The <tag> tag has required attribute "value" that holds the tag of the device.
<tags>

<tag value="tag 1" />

<tag value="tag 2" />

</tags>

<attributes> – this child element is optional and it has one or many <attribute> child elements . On XML Object Representation page there is detailed information about the representation of the Device attributes.

The <attribute> element does not support child element <class>.

<array-value>

</array-value>

</attribute>

</attributes>

From the content of the <device> XML attributes <type>, <vendor>, <version> and <name> and the child elements <device-properties>, <tags> and <attributes>, LDAP filter is constructed by using AND operator. When these XML attributes and child elements are provided, the XML attribute "ldap" must not be provided.

<mappings>

The <mappings> element is required. It has one or many <mapping> child elements .

<mapping>

The <mapping> tag has required attribute "uid" that holds the UID of the mapping. For detailed information refer to XML Mapping guide.

</mappings>