...
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 |
---|
|
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); "status":{"value":[0]}, // byte value: 0 = success, non-zero = failure
"latency":46, // in
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
}
}ms
"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":
{
"groupIdnodeId":"0x00010x1234",
"localEndpointendpointId":"0x01",
// optional "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 0x07 (infinite non-member-radius)no 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 no0x07 response
(infinite non-member-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 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",
"localEndpoint":"0x01", // optional, will default to no response0x01
"clusterId":"0x0006",
"transactionNumradius":"0x00", // optional, will onlydefault beto read0x00 if responseOptions requires it
(max radius)
"commandIdresponseOptions":"0x00010x02", "payload// optional, will default to no response
"frameControl":"0x00010304050x00" , // 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 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",
"radiuspayload":"0x000x0001030405" // optional, willcan defaultomit toif 0x00 (max radius)
"responseOptions":"0x02", // optional, will default to no response
"transactionNum":"0x00", // optional, will only be read if responseOptions requires it
"commandId":"0x0001there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
}
} |
Code Block |
---|
language | text |
---|
title | zdo unicast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zdo_unicast",
"message":
{
"nodeId":"0x1234",
"payloadresponseOptions":"0x00010304050x02", // optional, canwill omit if there's no payloaddefault 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
}
} |
...
...
...
Protocol Message Response Specification
Code Block |
---|
language | text |
---|
title | zcl response or zcl passthrough message |
---|
|
{
|
...
title | zdo broadcast protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"zclzdo_responsebroadcast",
// other valid value is zcl_passthrough_message
"message":
{
"sourceNode":"0xCB13",
"sourceEndpoint":"0x01",
"localEndpoint":"0x01",
"clusterId":"0x0006",
"encryption":"0x00",
"frameControl":"0x02 "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",
"manufacturerCodemessageType":"0x0000zcl_response", // other valid value is zcl_passthrough_message
"transactionNummessage":"0x7C",
{
"commandIdsourceNode":"0x010xCB13",
"payloadsourceEndpoint":"0x014363000x01"
,
} } |
Code Block |
---|
language | text |
---|
title | zdo response protocol message |
---|
|
{ "gatewayApiVersionlocalEndpoint":"2.0.40x01",
"protocolName "clusterId":"zigbee0x0006",
"protocolVersion":"3", "messageTypeencryption":"zdo_response0x00",
"message": {"frameControl":"0x02",
"sourceNodemanufacturerCode":"0xCB130x0000",
"transactionNum":"0x7C",
"commandId":"0x00010x01",
"payload":"0x01436300"
}
}
|
Code Block |
---|
language | text |
---|
title | default zdo response protocol message |
---|
|
{
"gatewayApiVersion":"2.0.4",
"protocolName":"zigbee",
"protocolVersion":"3",
"messageType":"defaultzdo_response",
"statusmessage":"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));
}
"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(); |