ZigbeeDevice
Overview
The ZigbeeDevice class represents a zigbee device on the network.
As a sub-class of Device, it inherits everything from that interface, as well as providing convenience methods for interacting with zigbee devices.
API
readAttribute(int clusterId, int attributeId)
Usage
Sends a command over the network to read a zigbee attribute from the specified server cluster.
Returns a CompletableFuture of a Property containing the name, type, and value of the attribute. Otherwise, will complete exceptionally on all errors.
This is a non-blocking call.
Parameters
| Name | Type | Description |
|---|---|---|
| clusterId | int | The server-side cluster where the attribute resides. |
| attributeId | int | The attribute to read. |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Property> | Contains a CompletableFuture<Property> of the zigbee attribute being read. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
// blocking
Property property = ((ZigbeeDevice)device).readAttribute(0x0000, 0x0001).get();
System.out.println(property.toString());
...
// async
((ZigbeeDevice)device).readAttribute(0x0000, 0x0001).thenAccept( property -> {
System.out.println(property.toString());
});
readAttribute(int clusterId, int attributeId, int manufacturerCode, boolean isServer)
Usage
Sends a command over the network to read a zigbee attribute from the specified cluster, manufacturerCode, and cluster side (server or client).
Returns a CompletableFuture of a Property containing the name, type, and value of the attribute. Otherwise, will complete exceptionally on all errors.
This is a non-blocking call.
Parameters
| Name | Type | Description |
|---|---|---|
| clusterId | int | The server-side cluster where the attribute resides. |
| attributeId | int | The attribute to read. |
| manufacturerCode | int | The manufacturerCode associated with the cluster; 0 if none. |
| isServer | boolean | Whether the cluster is server-side. |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Property> | Contains a CompletableFuture<Property> of the zigbee attribute being read. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
// blocking
Property property = ((ZigbeeDevice)device).readAttribute(0x0000, 0x0001, 0xFC01, true).get();
System.out.println(property.toString());
...
// async
((ZigbeeDevice)device).readAttribute(0x0000, 0x0001, 0xFC01, true).thenAccept( property -> {
System.out.println(property.toString());
});
writeAttribute(int clusterId, int attributeId, short dataType, byte[] value)
Usage
Sends a command over the network to write a zigbee attribute to the specified server cluster.
Returns a CompletableFuture of a Property containing the name, type, and value of the attribute that was written. Otherwise, will complete exceptionally on all errors.
This is a non-blocking call.
Parameters
| Name | Type | Description |
|---|---|---|
| clusterId | int | The server-side cluster where the attribute resides. |
| attributeId | int | The attribute to be written. |
| dataType | short | The identifier for the data type of the value being written. See Zigbee Specification References for supported data types. |
| value | byte[] | The value, in bytes, to be written. The order is LSB. For example, 2700 (decimal) would be "new byte[] {(byte)0x8C, (byte)0x0A}". |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Property> | Contains a CompletableFuture<Property> of the zigbee attribute being written. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device d = gateway.getDevice(id);
// blocking
Property p = ((ZigbeeDevice)d).writeAttribute(0x0201, 0x0012, 0x29, new byte[] {(byte)0x8C, (byte)0x0A}).get();
System.out.println(p.toString());
...
// async
((ZigbeeDevice)d).writeAttribute(0x0201, 0x0012, 0x29, new byte[] {(byte)0x8C, (byte)0x0A}).thenAccept( property -> {
System.out.println(p.toString());
});
writeAttribute(int clusterId, int attributeId, short dataType, byte[] value, int manufacturerCode, boolean isServer)
Usage
Sends a command over the network to write a zigbee attribute to the specified server cluster.
Returns a CompletableFuture of a Property containing the name, type, and value of the attribute that was written. Otherwise, will complete exceptionally on all errors.
This is a non-blocking call.
Parameters
| Name | Type | Description |
|---|---|---|
| clusterId | int | The server-side cluster where the attribute resides. |
| attributeId | int | The attribute to be written. |
| dataType | short | The identifier for the data type of the value being written. See Zigbee Specification References for supported data types. |
| value | byte[] | The value, in bytes, to be written. The order is LSB. For example, 2700 (decimal) would be "new byte[] {(byte)0x8C, (byte)0x0A}". |
| manufacturerCode | int | The manufacturerCode associated with the cluster; 0 if none. |
| isServer | boolean | Whether the cluster is server-side. |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Property> | Contains a CompletableFuture<Property> of the zigbee attribute being written. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device d = gateway.getDevice(id);
// blocking
Property p = ((ZigbeeDevice)d).writeAttribute(0xF001, 0x0001, 0x29, new byte[] {(byte)0x8C, (byte)0x0A}, 0xFC01, true).get();
System.out.println(p.toString());
...
// async
((ZigbeeDevice)d).writeAttribute(0xF001, 0x0001, 0x29, new byte[] {(byte)0x8C, (byte)0x0A}, 0xFC01, true).thenAccept( property -> {
System.out.println(p.toString());
});
sendZclCommand(short commandId, byte[] payload, int clusterId)
Usage
Sends a ZCL general command over the network to the specified server cluster.
A CompletableFuture of a Property that contains a JSON string with the ZCL command response. The CompletableFuture completes exceptionally on any errors.
This is a non-blocking call.
Parameters
| Name | Type | Description |
|---|---|---|
| commandId | short | The ZCL command id. |
| payload | byte[] | The payload in bytes. Each field in the payload is entered as LSB, so 2700 (decimal) would be 0x8C 0x0A. Can pass null for no payload. |
| clusterId | int | The cluster to send the command to. |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Property> | Contains a CompletableFuture<Property> with a JSON string of the ZCL Command Response. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device d = gateway.getDevice(id);
// blocking command to discover commands that the OnOff cluster can receive
Property p = ((ZigbeeDevice)d).sendZclCommand(0x11, new byte[] {(byte)0x00, (byte)0xFF}, 0x0006).get();
System.out.println(p.toString());
...
// async command to discover the commands that the OnOff cluster can receive
((ZigbeeDevice)d).sendZclCommand(0x11, new byte[] {(byte)0x00, (byte)0xFF}, 0x0006).thenAccept( property -> {
System.out.println(p.toString());
});
sendZclCommand(short commandId, byte[] payload, int clusterId, int manufacturerCode, boolean isServer, boolean isClusterSpecific, boolean responseRequired)
Usage
Sends a ZCL command (cluster specific, or general command) over the network to the specified cluster (server-side or client-side) and manufacturerCode.
A CompletableFuture of a Property that contains a JSON string with the ZCL command response. The CompletableFuture completes exceptionally on any errors.
This is a non-blocking call.
Parameters
| Name | Type | Description |
|---|---|---|
| commandId | short | The ZCL command id. |
| payload | byte[] | The payload in bytes. Each field in the payload is entered as LSB, so 2700 (decimal) would be 0x8C 0x0A. Can pass null for no payload. |
| clusterId | int | The cluster to send the command to. |
| manufacurerCode | int | The manufacturer code. 0 means "not manufacturing specific". |
| isServer | boolean | Whether the cluster is a server cluster. |
| isClusterSpecific | boolean | Whether the command is cluster specific (as opposed to a ZCL general command). |
| responseRequired | boolean | Whether the system should wait for a response and relay it back. If a command does not have a response, this flag must be false, otherwise an error may be reported. |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Property> | Contains a CompletableFuture<Property> with a JSON string of the ZCL Command Response. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device d = gateway.getDevice(id);
// blocking command to discover commands that the OnOff cluster can receive
Property p = ((ZigbeeDevice)d).sendZclCommand(0x11, new byte[] {(byte)0x00, (byte)0xFF}, 0xFC01, 0xFCC0, true, true, true).get();
System.out.println(p.toString());
...
// async command to discover the commands that the OnOff cluster can receive
((ZigbeeDevice)d).sendZclCommand(0x11, new byte[] {(byte)0x00, (byte)0xFF}, 0xFC01, 0xFCC0, true, true, true).thenAccept( property -> {
System.out.println(p.toString());
});
sendZclMulticastCommand(int groupId, short commandId, byte[] payload, int clusterId, int manufacturerCode, boolean isServer, boolean isClusterSpecific, boolean requiresResponse)
Usage
Sends a ZCL command (cluster specific, or general command) to the specified groupId, cluster (server-side or client-side) and manufacturerCode.
Returns a CompletableFuture of a Collection of Property objects, where each Property contains a JSON string with a ZCL command response. The CompletableFuture completes exceptionally on any errors.
If 'requiresResponse' is false, the returned Collection will contain one default response.
This is a non-blocking call.
This method is thread-safe.
Parameters
| Name | Type | Description |
|---|---|---|
| groupId | int | The group id to address the multicast message to. |
| commandId | short | The ZCL command id. |
| payload | byte[] | The payload in bytes. Each field in the payload is entered as LSB, so 2700 (decimal) would be 0x8C 0x0A. Can pass null for no payload. |
| clusterId | int | The cluster to send the command to. |
| manufacurerCode | int | The manufacturer code. 0 means "not manufacturing specific". |
| isServer | boolean | Whether the cluster is a server cluster. |
| isClusterSpecific | boolean | Whether the command is cluster specific (as opposed to a ZCL general command). |
| responseRequired | boolean | Whether the system should wait for a response and relay it back. If a command does not have a response, this flag must be false, otherwise an error may be reported. If false, then the returned Collection will contain one default response. |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Collection<Property>> | Contains a CompletableFuture<Collection<Property>>. Each Property is a JSON string of a single received ZCL Command Response. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... ZigbeeDevice zd = (ZigbeeDevice)gateway.getDevice(id); // multicast the "on" command to the "OnOff" cluster to group id 3 zd.sendZclMulticastCommand(0x0003, 0x01, null, 0x0006, 0x0000, true, true, false);
sendZclBroadcastCommand(String broadcastAddress, short commandId, byte[] payload, int clusterId, int manufacturerCode, boolean isServer, boolean isClusterSpecific, boolean requiresResponse)
Usage
Sends a ZCL command (cluster specific, or general command) to the specified broadcast address, cluster (server-side or client-side) and manufacturerCode.
Returns a CompletableFuture of a Collection of Property objects, where each Property contains a JSON string with a ZCL command response. The CompletableFuture completes exceptionally on any errors.
If 'requiresResponse' is false, the returned Collection will contain one default response.
This is a non-blocking call.
This method is thread-safe.
Parameters
| Name | Type | Description |
|---|---|---|
| broadcastAddress | String | The broadcast address that indicates the range of target devices (0xFF = All Devices, 0xFD = All Non-Sleepy Devices, 0xFC = All routers and coordinators) |
| commandId | short | The ZCL command id. |
| payload | byte[] | The payload in bytes. Each field in the payload is entered as LSB, so 2700 (decimal) would be 0x8C 0x0A. Can pass null for no payload. |
| clusterId | int | The cluster to send the command to. |
| manufacurerCode | int | The manufacturer code. 0 means "not manufacturing specific". |
| isServer | boolean | Whether the cluster is a server cluster. |
| isClusterSpecific | boolean | Whether the command is cluster specific (as opposed to a ZCL general command). |
| responseRequired | boolean | Whether the system should wait for a response and relay it back. If a command does not have a response, this flag must be false, otherwise an error may be reported. If false, then the returned Collection will contain one default response. |
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<Collection<Property>> | Contains a CompletableFuture<Collection<Property>>. Each Property is a JSON string of a single received ZCL Command Response. Will return exceptionally on any and all errors; the exception will contain an errorCode and description. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... ZigbeeDevice zd = (ZigbeeDevice)gateway.getDevice(id); // broadcast the "off" command to the "OnOff" cluster, to all devices zd.sendZclBroadcastCommand(0xFF, 0x00, null, 0x0006, 0x0000, true, true, false);
Legal Notices
Copyright © 2020 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.