OSGi 8.1.0 · org.osgi.service.zigbee.ZCLCluster · APIdia, the JavaDoc alternative

Modifier and Type	Field and Description
public static final String	DOMAIN Property key for the optional cluster domain.
public 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.
public static final String	NAME Property key for the optional cluster name.

Method Summary

Modifier and Type	Method and Description
public Promise<ZCLAttribute>	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(int the ZCL attribute identifier. attributeId) Returns the cluster `ZCLAttribute` identifying that matches the given attributeId.
public Promise<ZCLAttribute>	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` getAttribute(int the ZCL attribute identifier attributeId, int the manufacturer code of the attribute to be retrieved. If -1 is used, the method behaves exactly like `ZCLCluster#getAttribute(int)` code) Retrieves a `ZCLAttribute` object for a manufacturer specific attribute.
public Promise<ZCLAttribute[]>	Returns: A `Promise` representing the completion of this asynchronous call. The promise will be resolved with an array of `ZCLAttribute` objects. getAttributes() Returns an array of `ZCLAttribute` objects representing all this cluster's attributes.
public Promise<ZCLAttribute[]>	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. getAttributes(int The the manufacturer code. Pass -1 to retrieve standard (that is, non-manufacturer specific) attributes. code) Returns an array of `ZCLAttribute` objects representing all the specific manufacturer attributes available on the cluster.
public Promise<short[]>	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. getCommandIds() Returns an array of all the commandIds of the ZCLCluster.
public int	Returns: the cluster identifier. getId() Returns the identifier of this cluster.
public Promise<ZCLFrame>	Returns: A promise representing the completion of this asynchronous call. `Promise#getValue()` returns the response `ZCLFrame`. invoke(ZCLFrame The frame containing the command to issue. frame) Invokes a command on this cluster with a `ZCLFrame`.
public Promise<ZCLFrame>	Returns: A promise representing the completion of this asynchronous call. `Promise#getValue()` returns the response `ZCLFrame`. invoke(ZCLFrame The frame containing the command to issue. frame, String : the source endpoint of the command request. In targeted situations, the source endpoint is the valid service PID of an exported endpoint. exportedServicePID) Invokes a command on this cluster.
public Promise<Map<Integer, ZCLReadStatusRecord>>	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`. readAttributes(ZCLAttributeInfo[] An array of `ZCLAttributeInfo`. attributes) Reads a list of attributes by issuing a ZCL Read Attributes command.
public Promise<Map<Integer, Integer>>	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. writeAttributes(boolean `true` if an undivided write attributes command is requested, `false` if not. undivided, Map<? extends ZCLAttributeInfo, ?> 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[]. 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.

DOMAIN	back to summary
public 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.

ID	back to summary
public 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.

NAME	back to summary
public 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.

Method Detail

getAttribute back to summary

getAttribute	back to summary
public Promise<ZCLAttribute> getAttribute(int attributeId) Returns the cluster `ZCLAttribute` identifying that matches the given attributeId. `ZCLCluster#getAttribute(int, int)` method retrieves manufacturer-specific attributes. Parameters attributeId:int the ZCL attribute identifier. Returns:Promise<ZCLAttribute> 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`.

public Promise<ZCLAttribute> getAttribute(int attributeId)

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

Parameters

attributeId:int: the ZCL attribute identifier.

Returns:Promise<ZCLAttribute>

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 back to summary

getAttribute	back to summary
public 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 `ZCLCluster#getAttribute(int)` and retrieves the non-manufacturer specific attribute `attributeId`. Parameters attributeId:int the ZCL attribute identifier code:int the manufacturer code of the attribute to be retrieved. If -1 is used, the method behaves exactly like `ZCLCluster#getAttribute(int)` Returns:Promise<ZCLAttribute> 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`

public 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 ZCLCluster#getAttribute(int) and retrieves the non-manufacturer specific attribute attributeId.

Parameters

attributeId:int: the ZCL attribute identifier
code:int: the manufacturer code of the attribute to be retrieved. If -1 is used, the method behaves exactly like ZCLCluster#getAttribute(int)

Returns:Promise<ZCLAttribute>

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 back to summary

getAttributes	back to summary
public 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 `ZCLCluster#getAttributes(int)` Returns:Promise<ZCLAttribute[]> A `Promise` representing the completion of this asynchronous call. The promise will be resolved with an array of `ZCLAttribute` objects.

public 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 ZCLCluster#getAttributes(int)

Returns:Promise<ZCLAttribute[]>: A Promise representing the completion of this asynchronous call. The promise will be resolved with an array of ZCLAttribute objects.

getAttributes back to summary

getAttributes	back to summary
public 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 `ZCLCluster#getAttributes()` method if the passed value is -1. Parameters code:int The the manufacturer code. Pass -1 to retrieve standard (that is, non-manufacturer specific) attributes. Returns:Promise<ZCLAttribute[]> 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.

public 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 ZCLCluster#getAttributes() method if the passed value is -1.

Parameters

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

Returns:Promise<ZCLAttribute[]>

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.

getCommandIds back to summary

getCommandIds	back to summary
public 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:Promise<short[]> A `Promise` representing the completion of this asynchronous call. The promise will be resolved with `short[]` containing the command identifiers supported by the cluster.

public 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:Promise<short[]>: A Promise representing the completion of this asynchronous call. The promise will be resolved with short[] containing the command identifiers supported by the cluster.

getId	back to summary
public int getId() Returns the identifier of this cluster. Returns:int the cluster identifier.

getId

back to summary

public int getId()

Returns the identifier of this cluster.

Returns:int: the cluster identifier.

invoke back to summary

invoke	back to summary
public 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:ZCLFrame The frame containing the command to issue. Returns:Promise<ZCLFrame> A promise representing the completion of this asynchronous call. `Promise#getValue()` returns the response `ZCLFrame`.

public 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:ZCLFrame: The frame containing the command to issue.

Returns:Promise<ZCLFrame>

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

invoke back to summary

invoke	back to summary
public 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:ZCLFrame The frame containing the command to issue. exportedServicePID:String : the source endpoint of the command request. In targeted situations, the source endpoint is the valid service PID of an exported endpoint. Returns:Promise<ZCLFrame> A promise representing the completion of this asynchronous call. `Promise#getValue()` returns the response `ZCLFrame`.

public 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:ZCLFrame: The frame containing the command to issue.
exportedServicePID:String: : the source endpoint of the command request. In targeted situations, the source endpoint is the valid service PID of an exported endpoint.

Returns:Promise<ZCLFrame>

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

readAttributes back to summary

readAttributes	back to summary
public 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:ZCLAttributeInfo[] An array of `ZCLAttributeInfo`. Returns:Promise<Map<Integer, ZCLReadStatusRecord>> 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`.

public 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:ZCLAttributeInfo[]: An array of ZCLAttributeInfo.

Returns:Promise<Map<Integer, ZCLReadStatusRecord>>

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 back to summary

writeAttributes	back to summary
public 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:boolean `true` if an undivided write attributes command is requested, `false` if not. attributesAndValues:Map<? extends ZCLAttributeInfo, ?> 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:Promise<Map<Integer, Integer>> 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.

public 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:boolean: true if an undivided write attributes command is requested, false if not.
attributesAndValues:Map<? extends ZCLAttributeInfo, ?>: 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:Promise<Map<Integer, Integer>>

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.

public Interface ZCLCluster

Field Summary

Method Summary

Field Detail

Method Detail