In HDM the functions of a device are represented by Device Class Objects. Each HomeDevice object may have one or more Device Class Objects attached to it. You can use each of the functions of the device by modifying the relevant Device Class Object. A Device Class Object associated with a Home Device provides methods for executing operations on the device, as well as properties for storing device information.

Retrieving Device Class Objects

Each device class object implements a specific interface outlining certain device capabilities such as actuator, sensor, switch, etc. The packages contain a collection of predefined interfaces reflecting most widely spread device types.

To retrieve the Device Class Object of a Home Device:

1. Retrieve the HomeDevice object.
2. Check what interfaces does it support (optional) by using the getDeviceClasses method (or by accessing the DeviceClasses property).
3. Call the getDeviceClassObject method of the HomeDevice object (or HDAccess/getDeviceClassObject if you are using the JSON Remote API) by passing the interface of the Device Class Object of the object you need, e.g.DoorActuator, BinarySwitch, etc..

   One Home Device cannot contain more than one Device Class Object which implements a certain Interface.

4. If you are using the Java API, cast the returned DeviceClassObject to its interface.

You can also retrieve a device class object from an event your application has received through the OSGi Event Admin.

The following Java code snippet demonstrates how to get a Device Class Object (DCO) of type "BinarySwitch" from a Home Device object with an ID "23".

  String deviceUID = "23";

  String dco=BinarySwitch.class.getName();

  HomeDevice mydevice = deviceadmin.getHomeDevice(deviceUID);

    // Checks if the device supports the Binary Switch functionality

  boolean supportsBinarySwitch = false;

  String[] deviceclassobjects = mydevice.getDeviceClasses();

  for (int i = 0; i < deviceclassobjects.length; i++) {

    if (deviceclassobjects[i].equals(dco)) {

      supportsBinarySwitch = true;

    }

  }

  if (supportsBinarySwitch) {

      // Retrieve a Binary Switch Device Class Object

    DeviceClassObject mydeviceclassobject = mydevice

      .getDeviceClassObject(dco);

    BinarySwitch mybinaryswitch = (BinarySwitch) mydeviceclassobject;

  }

The following JavaScript code snippet demonstrates getting remotely a Device Class Object (DCO) of type "BinarySwitch" from a Home Device object with an ID "23".

  deviceUID = "23"

  dco="com.prosyst.mbs.services.hdm.deviceclasses.BinarySwitch"

  var xhr = new XMLHttpRequest();

  xhr.open("POST", "/remote/json-rpc", false);

  xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getHomeDevice", "params": "'+deviceUID+

       '", "id": 1}')

  mydevice = JSON.parse(xhr.responseText).result

    // Checks if the device supports the Binary Switch functionality

  supportsBinarySwitch = false

  deviceclassobjects = mydevice.DeviceClasses

  for (i = 0; i < deviceclassobjects.length; i++) {

    if (deviceclassobjects[i]===dco) {

      supportsBinarySwitch = true;

    }

  }

  if (supportsBinarySwitch) {

      // Retrieve a Binary Switch Device Class Object

    xhr.open("POST", "/remote/json-rpc", false);

    xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getDeviceClassObject", "params":["'+

        deviceUID+'", "'+dco+'", true ], "id": 2}')

    mybinaryswitch = JSON.parse(xhr.responseText).result

  }

Device Class Object Properties

Device Class Objects have properties, which identify the device's state or contain information collected by it.

You can retrieve a list of all properties with the getPropertyNames method of the DeviceClassObject interface (If you are using the JSON Remote API you can find them in the Properties array).

Checking Property Access Rights

Some Device Class Object properties values can be changed, and some cannot. You can check if property is writable by retrieving its access metadata property.

Reading Property Values

You can retrieve the current value of a property by calling the get<property_name> method of the Device Class Object (or by calling HDAccess/getDCOProperty if you are using the JSON Remote API).

The property values are retrieved from the HDM property cache.

Writing Property Values

You can change the value of a property by calling the set<property_name> method of the Device Class Object.

Some properties on some Device Class Objects are changed by executing operations.

The following Java code snippet demonstrates how to retrieve the value of a Device Class Object property.

  String dco=BinarySwitch.class.getName();

    //Print Device Class Object

  BinarySwitch mybinaryswitch = (BinarySwitch) mydevice.getDeviceClassObject(dco);

    //Retrieve state property value

  System.out.println(mybinaryswitch.getState()); //State = On

    //Change it (via an operation)

  mybinaryswitch.turnOff();

    //Print the new values

  System.out.println(mybinaryswitch.getState()); //State = Off    

The following JavaScript code snippet demonstrates how to retrieve the value of a DCO property remotely.

  dco="com.prosyst.mbs.services.hdm.deviceclasses.BinarySwitch"

    //Print state property value

  var xhr = new XMLHttpRequest();

  xhr.open("POST", "/remote/json-rpc", false);

  xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getDCOProperty", "params": ["'+

       mydevice.UID+'", "'+dco+'", "state"], "id": 1}')

  console.log(JSON.parse(xhr.responseText).result) //State = On

    //Change it (via an operation)    

  xhr.open("POST", "/remote/json-rpc", false);

  xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/invokeDCOOperation", "params": ["'+

      mydevice.UID+'", "'+dco+'", "turnOff", {}], "id": 2}')

    //Print the new values

  xhr.open("POST", "/remote/json-rpc", false);

  xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getDCOProperty", "params": ["'+

      mydevice.UID+'", "'+dco+'", "state"], "id": 3}')

  console.log(JSON.parse(xhr.responseText).result) //State = Off

Property Metadata

Each property defined in a Device Class Object interface is associated with some metadata which contains information such as name, description, access rights etc.

To get the metadata of a Device Class Object property call the getPropertyMetadata method.

The following Java code snippet demonstrates how to retrieve the metadata of a DCO property. It prints the names and descriptions of all available properties of the Device Class Object stored in the mydeviceclassobject variable (see the previous example).

  String[] properties = mybinaryswitch.getPropertyNames();

  for (int i = 0; i < properties.length; i++) {

    String propertyname = properties[i];

    Map propertymetadata = mydeviceclassobject.getPropertyMetaData(propertyname);

    System.out.println(propertyname+": "+propertymetadata.get(DeviceClassObject.META_INFO_PROPERTY_DESCRIPTION));

  }

The following JavaScript code snippet demonstrates how to retrieve remotely the metadata of a Device Class Object property.

  properties=mybinaryswitch.Properties

  for (i = 0; i < properties.length; i++) {

    propertyname = properties[i].Name

    propertymetadata = properties[i].Metadata;

    console.log(propertyname+": "+propertymetadata.description);

  }

Property Cache

The Home Device Manager stores the last known values of the Device Class Object properties in an internal cache. When an application makes an attempt to retrieve the value of a specific Device Class Object property, the Home Device Manager returns the property value from its cache.

Refreshing Cached Values

The cached Device Class Object property values are refreshed:

• When the physical device to which the Device Class Object belongs sends property change notifications (if the device supports that functionality).
• Periodically, over a defined polling interval.
• When an application sets a new value to the property.
• When an application executes an operation over the Device Class Object (in this case, all the Device Class Object properties are refreshed).
• When an application requests it explicitly by calling the refresh method either of the Device Class Object or of the whole Home Device.

The Home Device Manager sends events through the OSGi Event Admin service about Device Class Object property changes only if the property value in the Device Class Object cache is changed.

Polling Interval

The Home Device Manager polls the values of all properties of devices that do not support property change notifications.

Each Protocol Adapter has a minimal polling interval which you can retrieve from the ProtocolAdapterInfo object, using the getMinimalPollingInterval method. The method returns the minimal polling interval in milliseconds or "0" if polling is not supported.

To change the polling interval simply invoke the setPollingInterval method of the Device Class Object. The new polling interval must not be less than the minimal one.

To disable the polling set the polling interval to "0".

Device Class Object Operations

The device actions that you can trigger are represented by Device Class Object operations.

You can list the operations that a Device Class Object supports by using the getOperationNames method of the DeviceClassObject.

Triggering an Operation

To trigger an operation on a Device Class Object call the method named after it (or call the HDAccess/invokeDCOOperation if you are using the JSON Remote API).

Retrieving Operation Metadata

To get the metadata of an operation, for example, to provide exhaustive information to the user, invoke the getOperationMetadata method. The returned Map will contain the following information in the form of String key-value pairs:

Both methods for operation and property change are executed synchronously and they block the execution of the application until a response from the device is received. For asynchronous operation and property change use the asynchronous utility.