...
The intent is that developers should use the protocol-agnostic methods in the Device class for all their device interactions, and only use the protocol-specific methods in subclasses (such as ZigbeeDevice) if they require custom behaviours that haven't been specified or implemented in the Device class.
...
This is a non-blocking call.
Will complete exceptionally on all errors.
Parameters
None.
Returns
Return Type | Description |
---|
CompletableFuture<String> | A CompletableFuture<String> of the future result. The result can contain error codes or messages if any errors occurred. |
...
Will complete exceptionally on all errors. |
The result is a JSON string with 5 key/value pairs if it was successful
Code Block |
---|
Code Block |
---|
|
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device d = gw.getDevice(id); |
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gw.getDevice(id);
device.ping().thenAccept( pingResult -> System.out.println(pingResult) );
... |
leaveNetwork()
Usage
Request the device to leave the network.
Parameters
None.
Returns
None.
Examples
|
{
"status":{"value":[0]}, // byte value: 0 = success, non-zero = failure
"latency":46, // in ms
d.leaveNetwork(); |
sendProtocolMessage(String json)
Usage
Send a protocol-specific message using the underlying network protocol.
Parameters
...
Protocol Message Specification
Code Block |
---|
language | text |
---|
title | zcl unicast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zcl_unicast",
"message":
{
"nodeId":"0x1234",
"endpointId":"0x01",
"localEndpoint":"0x01", // optional, will default to 0x01
"clusterId":"0x0006",
"responseOptions":"0x02", // optional, will default to no response
"encryption":"0x01", // optional, will default to network encryption
"frameControl":"0x00", // optional, will default to ZCL General Command, Client-to-Server
"manufacturerCode":"0x00", // optional, will only be read if frameControl requires it
"transactionNum":"0x00", // optional, will only be read if responseOptions requires it
"commandId":"0x00",
"payload":"0x0001030405" // optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
}"directOrIndirect":{"value":[1]}, // byte value: 0 = response received directly from target device, 1 = response received indirectly from target device
"lastHopLQI":255, // LQI of last responding hop
"lastHopRSSI":-13 // RSSI (in dBm) of last responding hop
} |
Throws
The CompletableFuture returned by this method will throw a TimeoutException if the request does not receive a response from the target node after 20 seconds.
Examples
Code Block |
---|
|
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gw.getDevice(id);
device.ping().thenAccept( pingResult -> System.out.println(pingResult) );
... |
leaveNetwork()
Usage
Request the device to leave the network.
Parameters
None.
Returns
None.
Examples
Code Block |
---|
|
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device d = gw.getDevice(id);
d.leaveNetwork(); |
sendProtocolMessage(String json)
Usage
Send a protocol-specific message using the underlying network protocol.
Parameters
Name | Type | Description |
---|
json | String | A JSON string formatted according the the protocol message specification (see below) |
Protocol Message Specification
Code Block |
---|
language | text |
---|
title | zcl multicast unicast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zcl_multicastunicast",
"message":
{
"nodeId":"0x1234",
"groupIdendpointId":"0x00010x01",
"localEndpoint":"0x01", // optional, will default to 0x01
"clusterId":"0x0006",
"radiusresponseOptions":"0x00" // optional, will default to 0x00 (max radius)
"nonMemberRadius":"0x07", 0x02", // optional, will default to 0x07no (infinite non-member-radius)
response
"responseOptionsencryption":"0x020x01", // optional, will default to nonetwork responseencryption
"frameControl":"0x00", // optional, will default to ZCL General Command, Client-to-Server
"manufacturerCode":"0x00", // optional, will only be read if frameControl requires it
"transactionNum":"0x00", // optional, will only be read if responseOptions requires it
"commandId":"0x00",
"payload":"0x0001030405" // optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
} |
...
Code Block |
---|
language | text |
---|
title | zcl broadcast multicast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zcl_broadcastmulticast",
"message":
{
"broadcastAddressgroupId":"0xFD0x0001",
"endpoint":"0x01",
"localEndpoint":"0x01", // optional, will default to 0x01
"clusterId":"0x0006",
"radius":"0x00" // optional, will default to 0x00 (max radius)
"responseOptionsnonMemberRadius":"0x020x07", // optional, will default to no response0x07 (infinite non-member-radius)
"frameControlresponseOptions":"0x000x02", // optional, will default to ZCL no response
"frameControl":"0x00", // optional, will default to ZCL General Command, Client-to-Server
"manufacturerCode":"0x00", // optional, will only be read if frameControl requires it
"transactionNum":"0x00", // optional, will only be read if responseOptions requires it
"commandId":"0x00",
"payload":"0x0001030405" // optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
} |
...
Code Block |
---|
language | text |
---|
title | zdo unicast zcl broadcast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zdozcl_unicastbroadcast",
"message":
{
"nodeIdbroadcastAddress":"0x12340xFD",
"responseOptionsendpoint":"0x020x01",
// optional, will default to no response
"transactionNumlocalEndpoint":"0x000x01", // optional, will onlydefault beto read if responseOptions requires it
0x01
"commandIdclusterId":"0x00010x0006",
"payloadradius":"0x00010304050x00" // optional, canwill omitdefault ifto there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
} |
Code Block |
---|
language | text |
---|
title | zdo broadcast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zdo_broadcast",
"message":
{
"broadcastAddress":"0xFD",
"radius":"0x00" 0x00 (max radius)
"responseOptions":"0x02", // optional, will default to no response
"frameControl":"0x00", // optional, will default to ZCL General Command, Client-to-Server
"manufacturerCode":"0x00", // optional, will defaultonly tobe 0x00read (maxif radius)
"responseOptions":"0x02", // optional, will default to no response
frameControl requires it
"transactionNum":"0x00", // optional, will only be read if responseOptions requires it
"commandId":"0x00010x00",
"payload":"0x0001030405" // optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
} |
...
...
...
Protocol Message Response Specification
Code Block |
---|
language | text |
---|
title | zcl response or zcl passthrough message |
---|
|
{
|
...
title | zdo unicast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zclzdo_responseunicast",
// other valid value is zcl_passthrough_message
"message":
{
"sourceNode":"0xCB13",
"sourceEndpoint":"0x01",
"localEndpoint":"0x01",
"clusterId":"0x0006",
"encryption":"0x00",
"frameControl":"0x02",
"manufacturerCode":"0x0000",
"transactionNum":"0x7C",
"commandId":"0x01",
"payload":"0x01436300"
}
}
|
Code Block |
---|
language | text |
---|
title | zdo response protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zdo_response",
"message":
{
"sourceNode":"0xCB13",
"transactionNum":"0x7C",
"commandId":"0x0001", "message":
{
"nodeId":"0x1234",
"responseOptions":"0x02", // optional, will default to no response
"transactionNum":"0x00", // optional, will only be read if responseOptions requires it
"commandId":"0x0001",
"payload":"0x0001030405" // optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
} |
Code Block |
---|
language | text |
---|
title | zdo broadcast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zdo_broadcast",
"message":
{
"broadcastAddress":"0xFD",
"radius":"0x00" // optional, will default to 0x00 (max radius)
"responseOptions":"0x02", // optional, will default to no response
"transactionNum":"0x00", // optional, will only be read if responseOptions requires it
"commandId":"0x0001",
"payload":"0x0001030405" // optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
} |
Returns
Return Type | Description |
---|
CompletableFuture<String> | A JSON string formatted according to the protocol message response specification (see below) |
Protocol Message Response Specification
Code Block |
---|
language | text |
---|
title | zcl response or zcl passthrough message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zcl_response", // other valid value is zcl_passthrough_message
"message":
{
"payloadsourceNode":"0x014363000xCB13",
} } |
Code Block |
---|
language | text |
---|
title | default response protocol message |
---|
|
{ "gatewayApiVersionsourceEndpoint":"2.0.40x01",
"protocolName "localEndpoint":"zigbee0x01",
"protocolVersion "clusterId":"30x0006",
"messageType "encryption":"default_response0x00",
"status "frameControl":"0x000x02" // 0x00 is always success; anything else may refer to a general or specific failure
} |
Examples
Code Block |
---|
|
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// This is an example of using the Protocol Passthrough API, with a zigbee message formed as a json string.
// The zigbee message we're forming is a Zone Enroll Response Command (see ZCL Spec Section 8.2.2.3.1)
Device device = gw.getDevice(id);
Optional<Property> protocolProperty = device.getCachedProperty(PropertyNames.PROTOCOL_PROPERTY_NAME);
if (protocolProperty.isPresent()) {
Property p = protocolProperty.get();
JsonObject jsonObject = jsonParser.parse(p.getValue()).getAsJsonObject();
ZCLUnicastMessageBuilder builder = new ZCLUnicastMessageBuilder();
builder.setGatewayAPIVersion(GatewayClient.getApiVersion());
builder.setProtocolName("zigbee");
builder.setProtocolVersion(3);
builder.setNodeID(jsonObject.get(ZigBeeMessageTypeAdapter.NODE_ID_KEY).getAsString());
builder.setEndpointID(jsonObject.get(ZigBeeMessageTypeAdapter.ENDPOINT_ID_KEY).getAsString());
builder.setClusterID(IAS_ZONE_CLUSTER_ID);
builder.setResponseOptions(ZigBee.FrameConstants.RESPONSE_OPTIONS_APS_RESPONSE.toBitmap8());
builder.setFrameControl(ZigBee.FrameConstants.FRAME_CONTROL_CLIENT_TO_SERVER_CLUSTER_CMD.toBitmap8());
builder.setCommandID(ZONE_ENROLL_RESPONSE_ID);
// Zone Enroll Response:
// Field 1: 00 - enroll success
// Field 2: 01 - zone id
// therefore, final payload is: 0x0001
builder.setPayload("0x0001");
ZCLUnicastMessage message = builder.build();
device.sendProtocolMessage(message.toJson())
.thenAccept(jsonResponse -> System.out.println(jsonResponse));
}
,
"manufacturerCode":"0x0000",
"transactionNum":"0x7C",
"commandId":"0x01",
"payload":"0x01436300"
}
}
|
Code Block |
---|
language | text |
---|
title | zdo response protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zdo_response",
"message":
{
"sourceNode":"0xCB13",
"transactionNum":"0x7C",
"commandId":"0x0001",
"payload":"0x01436300"
}
} |
Code Block |
---|
language | text |
---|
title | default response protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"default_response",
"status":"0x00" // 0x00 is always success; anything else may refer to a general or specific failure
} |
Examples
Code Block |
---|
|
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// This is an example of using the Protocol Passthrough API, with a zigbee message formed as a json string.
// The zigbee message we're forming is a Zone Enroll Response Command (see ZCL Spec Section 8.2.2.3.1)
Device device = gw.getDevice(id);
Optional<Property> protocolProperty = device.getCachedProperty(PropertyNames.PROTOCOL_PROPERTY_NAME);
if (protocolProperty.isPresent()) {
Property p = protocolProperty.get();
JsonObject jsonObject = jsonParser.parse(p.getValue()).getAsJsonObject();
ZCLUnicastMessageBuilder builder = new ZCLUnicastMessageBuilder();
builder.setGatewayAPIVersion(GatewayClient.getApiVersion());
builder.setProtocolName("zigbee");
builder.setProtocolVersion(3);
builder.setNodeID(jsonObject.get(ZigBeeMessageTypeAdapter.NODE_ID_KEY).getAsString());
builder.setEndpointID(jsonObject.get(ZigBeeMessageTypeAdapter.ENDPOINT_ID_KEY).getAsString());
builder.setClusterID(IAS_ZONE_CLUSTER_ID);
builder.setResponseOptions(ZigBee.FrameConstants.RESPONSE_OPTIONS_APS_RESPONSE.toBitmap8());
builder.setFrameControl(ZigBee.FrameConstants.FRAME_CONTROL_CLIENT_TO_SERVER_CLUSTER_CMD.toBitmap8());
builder.setCommandID(ZONE_ENROLL_RESPONSE_ID);
// Zone Enroll Response:
// Field 1: 00 - enroll success
// Field 2: 01 - zone id
// therefore, final payload is: 0x0001
builder.setPayload("0x0001");
ZCLUnicastMessage message = builder.build();
device.sendProtocolMessage(message.toJson())
.thenAccept(jsonResponse -> System.out.println(jsonResponse));
}
|
Upgrade API
startOtaUpgrade()
Usage
Notifies the remote device that an OTA image is available for upgrade.
Assumes that GatewayClient.registerOtaFile(...) API has been called first to register a valid OTA upgrade file that the remote device will accept.
Notes:
- All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.
- This is a non-blocking call.
- This method is thread-safe.
Parameters
None.
Returns
None.
All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.
Examples
Code Block |
---|
|
ConnectionInfo c = new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0");
GatewayClient gw = new GatewayClient(c);
...
gw.registerOtaFile("path/to/otaFile.ota", c);
gw.registerOtaProgressHandler( progress ->
System.out.println("DeviceId: " + progress.getId() + ", Progress: " + progress.getProgress() + " %")
);
...
Device device = gw.getDevice(id);
device.startOtaUpgrade();
... |
abortOtaUpgrade()
Usage
Signals the remote device that it should stop any on-going OTA upgrade, and stops serving OTA upgrade files to that device.
Notes:
- All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.
- This is a non-blocking call.
- This method is thread-safe.
Parameters
None.
Returns
None.
All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.
Examples
Code Block |
---|
|
ConnectionInfo c = new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0");
GatewayClient gw = new GatewayClient(c);
...
gw.registerOtaFile("path/to/otaFile.ota", c);
gw.registerOtaProgressHandler( progress ->
System.out.println("DeviceId: " + progress.getId() + ", Progress: " + progress.getProgress() + " %")
);
...
Device device = gw.getDevice(id);
device.startOtaUpgrade();
...
device.abortOtaUpgrade(); |