org.osgi.service.zigbee

Interface ZCLCluster

public interface ZCLCluster

This interface represents a ZCL Cluster. Along with methods to retrieve the cluster information, like its ID, it provides methods to asynchronously send commands to the cluster and other methods that wrap most of the ZCL general commands.

Every asynchronous method defined in this interface returns back its result through the use of a Promise.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DOMAIN Property key for the optional cluster domain.
static String	ID Property key for the optional cluster id.
static String	NAME Property key for the optional cluster name.

Method Summary

Modifier and Type	Method and Description
Promise<ZCLAttribute>	getAttribute(int attributeId) Returns the cluster ZCLAttribute identifying that matches the given attributeId.
Promise<ZCLAttribute>	getAttribute(int attributeId, int code) Retrieves a ZCLAttribute object for a manufacturer specific attribute.
Promise<ZCLAttribute[]>	getAttributes() Returns an array of ZCLAttribute objects representing all this cluster's attributes.
Promise<ZCLAttribute[]>	getAttributes(int code) Returns an array of ZCLAttribute objects representing all the specific manufacturer attributes available on the cluster.
Promise<short[]>	getCommandIds() Returns an array of all the commandIds of the ZCLCluster.
int	getId() Returns the identifier of this cluster.
Promise<ZCLFrame>	invoke(ZCLFrame frame) Invokes a command on this cluster with a ZCLFrame.
Promise<ZCLFrame>	invoke(ZCLFrame frame, String exportedServicePID) Invokes a command on this cluster.
Promise<Map<Integer,ZCLReadStatusRecord>>	readAttributes(ZCLAttributeInfo[] attributes) Reads a list of attributes by issuing a ZCL Read Attributes command.
Promise<Map<Integer,Integer>>	writeAttributes(boolean undivided, Map<? extends ZCLAttributeInfo,?> attributesAndValues) Writes a set of attributes on the cluster using the ZCL Write Attributes or the Write Attributes Undivided commands, according to the passed undivided parameter.

Field Detail

ID

static final String ID

Property key for the optional cluster id. A ZigBee Event Listener service can announce for what ZigBee clusters it wants notifications.

See Also:

Constant Field Values

DOMAIN

static final String DOMAIN

Property key for the optional cluster domain. A ZigBee Event Listener service can announce for what ZigBee clusters domains it wants notifications.

See Also:

Constant Field Values

NAME

static final String NAME

Property key for the optional cluster name. A ZigBee Event Listener service can announce for what ZigBee clusters it wants notifications.

See Also:

Constant Field Values

Method Detail

getId

int getId()

Returns the identifier of this cluster.

Returns:

the cluster identifier.

getAttribute

Promise<ZCLAttribute> getAttribute(int attributeId)

Returns the cluster ZCLAttribute identifying that matches the given attributeId. getAttribute(int, int) method retrieves manufacturer-specific attributes.

Parameters:

attributeId - the ZCL attribute identifier.

Returns:

A promise representing the completion of this asynchronous call. In case of success in getting the attribute, the promise will be resolved with a ZCLAttribute instance. If attributeId do not exist in the cluster, then the promise fails with a ZCLException with status code ZCLException.UNSUPPORTED_ATTRIBUTE.

getAttribute

Promise<ZCLAttribute> getAttribute(int attributeId,
                                   int code)

Retrieves a ZCLAttribute object for a manufacturer specific attribute. If the code parameter is -1 it behaves like the getAttribute(int) and retrieves the non-manufacturer specific attribute attributeId.

Parameters:

attributeId - the ZCL attribute identifier

code - the manufacturer code of the attribute to be retrieved. If -1 is used, the method behaves exactly like getAttribute(int)

Returns:

A Promise representing the completion of this asynchronous call. The promise will be resolved with the requested ZCLAttribute. If a command such as ZCL Read Attributes or Discover Attributes has already been called once by the ZigBee host, the Promise can be quickly resolved. The resolution may be longer the first time one of the ZCLCluster methods to get one or all attributes is successfully called. If attributeId do not exist in the cluster, then the promise fails with a ZCLException with status code ZCLException.UNSUPPORTED_ATTRIBUTE

getAttributes

Promise<ZCLAttribute[]> getAttributes()

Returns an array of ZCLAttribute objects representing all this cluster's attributes.

This method returns only standard attributes. To retrieve manufacturer specific attributes use method getAttributes(int)

Returns:

A Promise representing the completion of this asynchronous call. The promise will be resolved with an array of ZCLAttribute objects.

getAttributes

Promise<ZCLAttribute[]> getAttributes(int code)

Returns an array of ZCLAttribute objects representing all the specific manufacturer attributes available on the cluster.

This method behaves like the getAttributes() method if the passed value is -1.

Parameters:

code - The the manufacturer code. Pass -1 to retrieve standard (that is, non-manufacturer specific) attributes.

Returns:

A Promise representing the completion of this asynchronous call. The promise will be resolved with an array of ZCLAttribute objects. If a command such as ZCL Read Attributes or Discover Attributes has already been called once by the ZigBee host, the Promise can be quickly resolved. The resolution may be longer the first time one of the ZCLCluster methods to get one or all attributes is successfully called.

readAttributes

Promise<Map<Integer,ZCLReadStatusRecord>> readAttributes(ZCLAttributeInfo[] attributes)

Reads a list of attributes by issuing a ZCL Read Attributes command. The attribute list is provided in terms of an array of ZCLAttributeInfo objects.

As described in section 2.4.1.3 Effect on Receipt of the ZCL specification, a Read Attributes command results in a list of attribute status records comprising a mix of successful and unsuccessful attribute reads.

The method returns a promise. The object used to resolve the Promise is a Map<Integer, ZCLReadStatusRecord>. For each Map entry, the key contains the attribute identifier and the value, a ZigBee Read Attributes Status Record, which is made of the status of the read of this attribute, the ZigBee data type of the attribute and the attribute value in the corresponding Java wrapper type (or null in case of an unsupported attribute or in case of an invalid value). For attributes which data type serialization is not supported (that is, ZCLDataTypeDescription.getJavaDataType() returns null), the value is of type byte[].

When the list of attributes do not fit into a single ZCLFrame, ZigBee clusters truncate the list of attributes returned in the response. The client has to check the Map of results to send a new request for the attributes which values are missing. In export situations, the base driver may truncate the read attribute command response sent to networked devices in order to obey the rules.

NOTE: According to the ZigBee Specification all the attributes must be standard attributes or belong to the same manufacturer code, otherwise the promise must fail with a IllegalArgumentException exception.

Parameters:

attributes - An array of ZCLAttributeInfo.

Returns:

A promise representing the completion of this asynchronous call. The promise may fail with an IllegalArgumentException if the array size is 0 or if one of the array entries is null or not valid. An IllegalArgumentException is also thrown if some of ZCLAttributeInfo are manufacturer specific and other are standard, or even if there are mix of attributes with different manufacturer specific code. If the passed argument is null the promise must fail with a NullPointerException.

writeAttributes

Promise<Map<Integer,Integer>> writeAttributes(boolean undivided,
                                              Map<? extends ZCLAttributeInfo,?> attributesAndValues)

Writes a set of attributes on the cluster using the ZCL Write Attributes or the Write Attributes Undivided commands, according to the passed undivided parameter.

The promise resolves with a Map<Integer, Integer>. If all the attributes have been written successfully, the map is empty. In case of failure in writing specific attribute(s), the map is filled with entries related to those attributes. Every key is set with the id of an attribute that was not written successfully, every value with the status returned in the associated write attribute response record accordingly re-mapped to one of the constants defined in the ZCLException class.

According to the ZigBee Specification all the attributes must be standard attributes or, if manufacturer-specific they must have the same manufacturer code, otherwise an IllegalArgumentException occurs.

Parameters:

undivided - true if an undivided write attributes command is requested, false if not.

attributesAndValues - A Map<ZCLAttributeInfo, Object> of attributes and values to be written. For ZCLAttributeInfo objects which serialization is not supported (that is, getDataType().getJavaDataType() returns null), the value must be of type byte[].

Returns:

A promise representing the completion of this asynchronous call. If resolved successfully the promise may return an empty Map<Integer, Integer>. Otherwise the map will be filled with the status information about the attributes that were not written. The key represents the attributeID and the value the status present in the corresponding attribute record returned by the ZCL Write Attributes response message. The original ZCL status values must be re-mapped to the list of status values listed in the ZCLException class. The promise may fail with an IllegalArgumentException if some of ZCLAttributeInfo are manufacturer specific and other are standard, or even if there are mix of attributes with different manufacturer specific code.

getCommandIds

Promise<short[]> getCommandIds()

Returns an array of all the commandIds of the ZCLCluster.

This method is implemented for ZCL devices compliant version equal or later than 1.2 of the Home Automation Profile or other profiles that adds a general command that enables discovery of command identifiers. When the device implements a profile that does not support this feature, the promise fails with a ZCLException with code ZCLException.GENERAL_COMMAND_NOT_SUPPORTED.

Returns:

A Promise representing the completion of this asynchronous call. The promise will be resolved with short[] containing the command identifiers supported by the cluster.

invoke

Promise<ZCLFrame> invoke(ZCLFrame frame)

Invokes a command on this cluster with a ZCLFrame. The returned promise provides the invocation response in an asynchronous way. The source endpoint is not specified in this method call. To send the appropriate message on the network, the base driver must generate a source endpoint. The latter must not correspond to any exported endpoint.

Parameters:

frame - The frame containing the command to issue.

Returns:

A promise representing the completion of this asynchronous call. Promise.getValue() returns the response ZCLFrame.

invoke

Promise<ZCLFrame> invoke(ZCLFrame frame,
                         String exportedServicePID)

Invokes a command on this cluster. This method is to be used by applications when the targeted device has to distinguish between source endpoints of the message. For instance, alarms cluster (see 3.11 Alarms Cluster in [ZCL]) generated events are differently interpreted if they come from the oven or from the intrusion alert system.

Parameters:

frame - The frame containing the command to issue.

exportedServicePID - : the source endpoint of the command request. In targeted situations, the source endpoint is the valid service PID of an exported endpoint.

Returns:

A promise representing the completion of this asynchronous call. Promise.getValue() returns the response ZCLFrame.