Home Devices (deprecated)

A physical device is represented as a Home Device object with properties which provide general information about the device, as well as information about its current status.

Retrieving a Home Device

Devices are referred to by their unique ID which is stored in the UID field of the HomeDevice object:

Retrieve the Home Device Admin service (com.prosyst.mbs.services.hdm.HomeDeviceAdmin). If you are accessing the Home Device Manager via the JSON Remote API use the functions from the HDAccess group.
Do one of the following:
- Invoke the getHomeDevice method (or HDAccess/getHomeDevice if you are using the JSON Remote API) and pass the unique UID of the device you want to retrieve. (You can get the UID's of a device immediately after it connects to the network by subscribing to device events).
- Invoke one of the getHomeDevices methods or HDAccess/getHomeDevices if you are using JSON Remote API You can pass as arguments:
  - an LDAP String filter that holds criteria for matching all devices in the HDM network
  - a ProtocolAdapterInfo instance (or the name of the Protocol Adapter if you are using the JSON Remote API) to apply the LDAP filter only on devices registered for a specific Protocol Adapter.

The method returns an array of all devices that meet the specified criteria. Invoke one of the methods by passing null as a value for the filter parameter and you will receive either all home devices in the network or only the devices registered for the specified Protocol Adapter.

The following Java code snippet demonstrates how to retrieve all devices in the network that have status online. A filter that matches the status of the device with a predefined status constant is used.

HomeDeviceAdmin deviceadmin = (HomeDeviceAdmin) service;

try {

HomeDevice[] onlinedevices = deviceadmin.getHomeDevices('('+ HomeDevice.STATUS + "=" + HomeDevice.STATUS_ONLINE + ')');

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

System.out.println(onlinedevices[i].getUID());

}

The following JavaScript code snippet demonstrates how to retrieve all devices in the network that have status online via the JSON-RPC API.

var xhr = new XMLHttpRequest();

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

xhr.setRequestHeader("Content-Type","application/json");

xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getHomeDevices", "params": "(status=2)", "id": 1}');

onlinedevices = JSON.parse(xhr.responseText).result;

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

console.log(devices[i].UID);

}

Retrieving Child Home Devices

A complex home device can sometimes be represented as several Home Devices in a parent-child relationship.

For example, there might be a complex physical battery-based device with a motion sensor and two binary switches. It will be convenient to define the device in the HDM system as one root home device which will represent the physical device and will have BatteryLevel as device class object. Another three child HomeDevice objects will be created - one for the motion sensor with a MotionSensor as a device class object and two for the binary switches with BinarySwitch as device class objects.

To retrieve the child home devices for such a complex Home Device:

Retrieve the root Home Device by following the steps from the previous section.
Then retrieve the child home devices by calling the getChildren() method of the com.prosyst.mbs.services.hdm.HomeDevice interface (or by accessing the ChildUIDs property if you are using the JSON Remote API).

In protocol adapters where devices are added manually, the parent-child relationship between them is also introduced manually. To add a device as a child of another device, use the HomeDevice.PARENT_ID property when invoking the addHomeDevice method.

The following Java code snippet retrieves a home device with UID "23", prints the UIDs of its child devices and then retrieves the first of them.

HomeDeviceAdmin deviceadmin = (HomeDeviceAdmin) service;

try {

//retrieve a device

HomeDevice mydevice = deviceadmin.getHomeDevice("23");

String[] childdeviceuids = mydevice.getChildUIDs();

//print the UIDs of all child devices

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

System.out.println(childdeviceuids[i]);

}

//retrieve a child device

HomeDevice childdevice = deviceadmin.getHomeDevice(childdeviceuids[0]);

The following JavaScript code snippet demonstrates how to use the JSON-RPC API to retrieve remotely a child home device.

//retrieve a device

var xhr = new XMLHttpRequest();

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

xhr.setRequestHeader("Content-Type","application/json");

xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getHomeDevice", "params": "23", "id": 1}');

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

childdeviceuids = mydevice.ChildUIDs;

//print the UIDs of all child devices

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

console.log(childdeviceuids[i]);

}

//retrieve a child device

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

xhr.setRequestHeader("Content-Type","application/json");

xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getHomeDevice", "params": "'+childdeviceuids[0]+'", "id": 2}');

childdevice = JSON.parse(xhr.responseText).result;

Device Status

It is represented by one of the STATUS_XXX constants of the HomeDevice interface, e.g. STATUS_ONLINE. To check the status of a device, call the getStatus method of its home device object. (or access the Status property if you are using the JSON Remote API)

The status of a device can have a different meaning for end devices (a normal device like sensor or actuator) and for network controllers (a device that provides connection to other devices).

Parameter	Description - Network Controllers	Description - End Devices
OFFLINE	The controller is unplugged or there is no connection to it. This status may be inaccurate for radio based devices.	The device cannot be accessed. Either the controller is unplugged or there is some problem with the device itself. This status may be inaccurate for radio based devices.
INITIALIZING	HDM attempts to obtain the list of available devices from the controller.	The data which represents the end device is either being read at the moment or its properties are initially read so cache in HDM can be filled.
NOT_INITIALIZED	Not Applicable	The data which represents the device is either not fully read or it contains errors (in this case, it will create an error object).
NOT_CONFIGURED	Not Applicable	There is a pending configuration. This status means that the user is required to push some button on the device in order for it to receive configuration parameters e.g. changed display text or authentication mode. Sometimes devices with this status can perform operations.
ONLINE	The controller is working properly. This status may be inaccurate for radio based devices.	The device is working properly. It can also mean that there was a problem during the last communication with it (in this case, it will create an error object). This status may be inaccurate for radio based devices.
REMOVED	The device has been removed by the end user. This status is used to notify applications that keep references to the removed device.	The device has been removed by the end user. This status is used to notify applications that keep references to the removed device.
REMOVING	The user launched a remove operation in HDM while the controller is in OFFLINE status. Only after the controller becomes available it can be removed.	The user requested from the HDM to remove the device but for some reason this cannot be done at the moment (for example because the device is currently not available in the network or is waiting for some user interaction with it). As soon as the operation can be executed, it is processed by the controller. On success, the device status becomes REMOVED.

Device Errors

When the device is connected but is not operational due to a fault you can retrieve an error object, related to the fault by calling the getError method of the HomeDevice object representing the respective home device (or by accessing the Error property if you are using the JSON Remote API).

The Error object contains a message and an error code, which signifies the type of the error.

Error Code	Description
DEVICE_NOT_ACCESSIBLE	For a controller this property indicates that the connection to the controller is lost. It is possible to check if the peripheral device related to the home device representation of the controller is available to see if the controller was unplugged. In other cases only the protocol adapter is installed without the OSGi-based driver for the controller. For an end device this property indicates that the end device is not accessible any more. For example driver does not return info about the end device after controller is plugged. It is used only in OFFLINE status.
DEVICE_BROKEN	The error code indicates that the controller or end device is broken. It is used only in OFFLINE status.
DEVICE_DATA_INSUFFICIENT	The error code indicates that the data to represent the end device is not enough or is not correct. It is used only in NOT_ INITIALIZED status.
DEVICE_COMMUNICATION_ERROR	The error code indicates that an error occurred while sending a command to an end device. The command can be for getting/setting a DCO property or executing a DCO operation. It is used in ONLINE and NOT_INITIALIZED status.
NO_PROTOCOL_ADAPTER	There is no protocol adapter service registered. For example if a network controller is unplugged the driver components along with the protocol adapter for this controller will be uninstalled after predefined timeout. It is used only in OFFLINE status.
IN_DUTY_CYCLE	The device is in duty cycle. Used only in OFFLINE status.
CONFIGURATION_NOT_APPLIED	The error code indicates that the configuration is not applied or only a part of the configuration is applied on the physical device. For example the user has to perform additional action (to press button on the device). It is used only in NOT_CONFIGURED status.
CONFIGURATION_NOT_VALID	The error code indicates that the configuration is invalid. For example configuration device class or device class property is not available. It is used only in NOT_CONFIGURED status.

Device Properties

Home Device objects have two sets of properties:

Predefined Properties

Properties which are shared by all Home Devices.

UID - The unique ID of the device, by which you can identify it in HDM
Name - A user-friendly name for the device.
ParentUID, ChildUIDs - The parent and child devices of the current device, if it has any.
Status, Error - The status of the device and a status error, if there is one.
Type - Specifies what the device does. If the device is a network controller (coordinator), this property is equal to the HomeDevice.TYPE_CONTROLLER constant.
Vendor, Version - Hardware-related information.
ProtocolAdapterName - The protocol adapter that the device uses.
DeviceClasses - The Device Class Objects attached to the device.
TimestampAdded - The time when the device is added to the system (stored as integer).

If you are using the Java API you can retrieve the values of these properties with the get<Property_name> method of the HomeDevice object. If you are using the JSON Remote API, you can access them directly.

Additional Properties

Home Devices have a set of additional properties which are added by their protocol adapters or by third parties.

You can retrieve a list of a Home Device's additional properties by calling the getProperties method (or by retrieving the Properties object if you are using the JSON Remote API).

You can also add more properties to this list. Use the setProperty method if you are using the Java API and HDAdmin/setHomeDeviceProperty if you are using the JSON Remote API.

The following Java code snippet demonstrates how to add and retrieve home device properties.

String deviceUID = "23";

String propertykey ="key";

String propertyvalue ="value";

HomeDevice mydevice = deviceadmin.getHomeDevice(deviceUID);

//adding a property

mydevice.setProperty(propertykey, propertyvalue);
//retrieving properties

System.out.println(mydevice.getProperties());

The following JavaScript code snippet demonstrates how to remotely add and retrieve home device properties via JSON-RPC API.

deviceUID = "23";

propertykey ="key";

propertyvalue ="value";

//adding a property

var xhr = new XMLHttpRequest();

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

xhr.setRequestHeader("Content-Type","application/json");

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

deviceUID+'", "'+propertykey+'", "'+propertyvalue+'"], "id": 1}');

//retrieving properties

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

xhr.send('{"jsonrpc": "2.0", "method": "HDAccess/getHomeDevice", "params": "23", "id": 1}');

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

console.log(mydevice.Properties);