Some protocol adapters allow automatic discovery of newly-joined devices while others require new devices to be explicitly registered. In order to work with a protocol adapter you must first check the operations it supports.

Retrieving the Operations Supported by the Protocol Adapter

If a protocol adapter supports the "add devices" operation it means that it cannot detect new devices automatically. If it supports the "search" operation it means that changes in the state of devices in the network are automatically detected and you are allowed to manually search for new devices.

To check if a certain operation is supported by a protocol adapter:

1. Install and start the protocol adapter you want to use.
2. Retrieve the com.prosyst.mbs.hdm.HomeDeviceAdmin service.
3. Call the getProtocolAdapterInfo method of the HomeDeviceAdmin, passing the name of the protocol adapter as an argument. You will get a ProtocolAdapterInfo object that contains all information necessary to work with the protocol adapter.
4. Call the getOperations method of the ProtocolAdapterInfo. It will return all operations that are supported by the protocol adapter stored in a bitmask.
5. Execute a bitwise AND operation on the bitmask and one of the operation constants from the ProtocolAdapterInfo class - OPERATION_ADD, OPERATION_SEARCH, OPERATION_REMOVE.

If the adapter supports the operation, the result of the expression will be equal to the operation constant. Otherwise, the result will be "0".

The following Java code example demonstrates how to check if a given protocol adapter (stored in the adapterinfo variable) supports the Add and Search operations.

  if ((adapterinfo.getOperations() & ProtocolAdapterInfo.OPERATION_ADD) == ProtocolAdapterInfo.OPERATION_ADD) {

    System.out.println("The adapter supports the ADD operation");

  }

  if ((adapterinfo.getOperations() & ProtocolAdapterInfo.OPERATION_SEARCH) == ProtocolAdapterInfo.OPERATION_SEARCH) {

    System.out.println("The adapter supports the SEARCH operation");

  }

The Add, Search and Remove operations of the protocol adapter:

• If the protocol adapter supports the Add operation you can use it to manually add the devices in the network. If the protocol adapter does not support the Add operation the protocol driver can automatically detect new devices. However in some cases not only does the protocol driver automatically detect devices, but also the protocol adapter supports the Add operation, i.e. you can also manually add devices in the network.
• The Search operation results in adding new devices if such are detected, as well as removing devices which are not available (anymore).
• If the adapter supports the Remove operation you can remove previously added devices from the network.

Device Properties

If the protocol adapter requires devices to be added manually, you add them by creating a map of device properties. These properties are different depending on the protocol. You can retrieve them again from the protocol's ProtocolAdapterInfo object.

Protocol-Specific Home Device Properties

If the protocol supports the Add without device classes operation, you add a device to it by only specifying the properties of the device, and not the ones of its device class objects. To retrieve them:

1. Retrieve the ProtocolAdapterInfo object.
2. Call the getProperties method by passing null as an argument.

The method will return a Map of all device properties, that are required by the protocol adapter in order for a device to be added, along with their default values.

The default value of a property is either a String or a String[]. If the default value is a String[], you must pick one of the elements of this array as the actual value.

Protocol-Specific Device Class Properties

If the protocol supports the Add operation, you add a device to it by specifying both the properties of the device and those of its device class objects, in one map.

To retrieve the device class object properties:

1. Retrieve the ProtocolAdapterInfo object.
2. Call the getProperties method by passing the device class object as an argument.

The method will return a Map of all device class properties, that are required by the protocol adapter in order for a device class object to be added, along with their default values.

The default value of a property is either a String or a String[]. If the default value is a String[], you must pick one of the elements of this array as the actual value.

Property Metadata

You can retrieve a map that contains metadata for a given home device or device class object property with the getPropertyMetaData method of the ProtocolAdapterInfo object.

The following table contains the metadata properties that describe an adapter-handled device property: