Develop an interface that represents a functionality of a home device.

Determining Properties and Operations

Each Device Class Interface has properties (which may or may not be writable) and operations. You have to select the names for your custom Device Class Object properties and operations having in mind that the following names are reserved:

Reserved Property Names

• deviceClass
• propertyNames
• operationNames
• type
• class

Reserved Operation Names

• getPropertyMetaData
• getOperationMetaData
• getPollingInterval
• setPollingInterval
• refresh
• getSpiValue
• setPropertySecure
• invokeOperationSecure
• hashCode
• toString
• clone
• notify
• notifyAll
• finalize
• equals

Writing the Java Interface

Create the Java interface following the rules to have:

• Getter methods for all readable properties.
• Setter methods for all writable properties.
• Methods for executing Device Class Object operations.
• The names of the properties and operations defined as constants: PROPERTY_<PROPERTY_NAME> and OPERATION_<OPERATION_NAME>(optional).

The following Java code snippet demonstrates how to extend an existing Device Class Object interface to provide some functionality. It shows the BatteryAlert custom device class interface which is part of the Custom Device Classes Demo.

package demo.hdm.dc;      

import com.prosyst.mbs.services.hdm.deviceclasses.BatteryLevel;      

/**

* This device class extends the device class BatteryLevel and

* provides additional alert notifications of the battery.

*/

public interface BatteryAlert extends BatteryLevel {

  /**

   * Property name used for alert notifications of the battery.

   * When there is an alert from the battery, the event will be send. The value

   * of the event is one of the defined alerts.

   */

  public static final String PROPERTY_ALERT = "alert";      

  /**

   * Battery alert indicates that the battery is charged and it is full.

   */    

  public static final Integer ALERT_FULL_BATTERY = new Integer(1);

  /**

   * Battery alert indicates that the battery is in critical level.

   */

   public static final Integer ALERT_CRITICAL_BATTERY = new Integer(2);

}

Providing the Device Class Object Metadata

Create an XML-based metadata for your Device Class Interface. The Metadata Manager will parse the file and turn it into metatype objects which the Home Device Manager will store as the default metadata for the involved Device Class Object properties and operations.

Creating the XML File

Write an XML file using the tags supported by the Metadata Extension included in the "Developer Guide" section of the Bosch IoT Gateway Software OSGI documentation. In brief, such a document should contain the following tags:

• metatype-provider
  • objectclass - The metatype of the device class.
    • name - A friendly name of the device class.
    • id - The ID of the metatype, under which it will be saved in the Metadata Manager. It must be the fully-qualified name of the device class, e.g. "com.prosyst.mbs.services.hdm.deviceclasses.av.camera.MoveActuator".
    • description - A description of the device class.
    • attribute - The metadata of a property or of an operation. An XML file might can have several attributes.
    1. name - The friendly name of the property or operation. Can be empty.
    2. id - The key of the property or the name of the operation. It must match the names from the device class Java interface. For example, if we have a property "mode" and methods getMode and setMode in the Java interface, then the id tag must have value "mode". If we have an operation Java method called turnOn, then the id tag must have the value "turnOn".
    3. description - A description of the device class property or operation. Optional.
    4. type - The data type of the property. Though this attribute is not needed by the Home Device Manager, it is mandatory according to the Metadata Manager specification. Use any value, for example "int".
    5. cardinality - Use it only when defining a super metatype.
    6. key - A tag to hold the one of the following attributes of the property or operation. key has two attributes - "name" containing the attribute name and "value" - the value of the attribute:
       1. Property: "access", "unit", "min", "max" or "step". Refer to the "Manipulate the Properties of a Device Class Object" section to get the description of the attributes.
       2. Operation: "IN1", "IN2", ..., "OUT". See the "Execute Operations on a Device Class Object" section for more details on the attributes meaning.
    7. selected-pairs - (label, value) pairs which represent user-friendly options suitable for showing in a UI application. The first scalar is the label and the second one - the value. Java applications can access the (label, value) pairs as a java.util.Map value from the "enum" metadata attribute of a DCO property.
       1. scalar
    8. value - Use it only when defining a super metatype.
       1. scalar - The full-qualified name of the super device class.

If your device class Java interface extends another one, you have to reflect it the metadata XML as well. In this case, the device class metatype should also contain an attribute tag with sub-tags: id "super", type "&string;", cardinality "0" and value indicating the type of the super device class within a scalar. Thanks to this declaration, the Metadata Manager will automatically form the new metatype.

You can check if the XML file is correct in terms of metatype structure by using the parse command of the mtp group in the runtime console. For example, to parse the XML file of the Color device class from the HDM Device Classes Demo type the following: mtp.parse ../demo/hdm/dc/metadata/color.xml

The next example contains the metatype XML file of the BatteryAlert Device Class Object provided in the Custom Device Classes Demo. It declares that the BatteryAlert metatype inherits that of the BatteryLevel Device Class Object and adds an eventful new property "alert".

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE metatype-provider SYSTEM "conf.dtd">

<metatype-provider>

  <objectclass>

    <name>Battery Alert</name>

    <id>demo.hdm.dc.BatteryAlert</id>

    <description>This device class provides additional alert notifications of the battery.</description>

    <attribute modifier="opt">

      <name/>

      <id>alert</id>

      <description>Property used for alert notifications of the battery.</description>

      <type>int</type>

      <key name="access" value="E"/>

      <selected-pairs>

        <scalar>Full Battery</scalar>

        <scalar>1</scalar>

        <scalar>Critical Battery</scalar>

        <scalar>2</scalar>

      </selected-pairs>

    </attribute>

    <attribute modifier="req">

      <name/>

      <id>super</id>

      <description></description>

      <type>&string;</type>

      <cardinality>0</cardinality>

      <value>

        <scalar>com.prosyst.mbs.services.hdm.deviceclasses.BatteryLevel</scalar>

      </value>

    </attribute>

  </objectclass>

</metatype-provider>

Manifesting the Location of the XML File

You have to indicate the location of the metadata XML file within the bundle JAR file to the Metadata Manager running in the OSGi platform. Into the manifest of the bundle JAR file add a HomeDevice-MetaData header:

HomeDevice-MetaData: xml=<xml-resource-path>;pid=<device-class-name>;name=<device-class-display-name>;version=<metadata-version> [, xml=<xml-resource-path>;pid=<device-class-name>;name=<device-class-display-name>;version=<metadata-version>]

where:

• xml-resource-path – Specifies the path to the XML file inside and outside the bundle JAR file. Beware to use "/" as path separator.
• service-pid – Contains the fully-qualified class name of the device class interface
• display-name – Specifies the user-friendly name of the device class
• metadata-version – Specifies the version of the device class definition. The version value may be a string in the major.minior.micro format, which is used to distinguish changes in the format of a given resource.

For example, the manifest file of the Custom Device Classes Demo exports the following metatype XML files:

HomeDevice-MetaData:

xml=/metadata/color.xml;pid=demo.hdm.dc.Color;name=Color;version=1.0.0,

xml=/metadata/battery_alert.xml;pid=demo.hdm.dc.BatteryAlert;name=Battery Alert;version=1.0.0

Preparing the Bundle

Put the resources you created in an OSGi bundle:

• The new device class interfaces can be a part of the protocol adapter bundle whose device class objects implement them. If the interfaces are designed for use in different adapters, then it's better to place them in a separate bundle. In this case, you do not need to implement a bundle activator as well as to start the bundle.
• To make the device classes accessible to management applications, export the packages holding them in the Export-Package header of the manifest.
• Specify the path to the metatype XML files describing the device classes in the HomeDevice-MetaData header in the manifest.
• To check if the Metadata Manager  has successfully detected the metatypes listed via the HomeDevice-MetaData manifest header in your bundle's manifest file, in the runtime console use the list or listdb commands from the mtp group. For example, checking device classes bundle with ID "66": mtp.ls 66 HomeDevice-MetaData mtp.lsdb -m 66 HomeDevice-MetaData