Specific devices will have their own implementations of the methods defined in the Device class (such as ZigbeeDevice and its subclasses, LightDevice, ThermostatDevice, etc); however, they will all share the same API defined in the Device class.

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.

Sub-Classes

Page Tree

root	@self

...

Will result in a request over the network the first time it's called; however, subsequent calls will return a cached value.

This is a non-blocking call.

Parameters

None.

Returns

Return Type

Description

CompletableFuture<String>

A CompletableFuture containing a String with the result.

Will complete exceptionally on any errors with a RequestExeptionRequestException. The RequestException will contain an error message and code.

...

Will result in a request over the network the first time it's called; however, subsequent calls will return a cached value.

This is a non-blocking call.

Parameters

None.

Returns

Return Type

Description

CompletableFuture<String>

A CompletableFuture containing a String with the result.

Will complete exceptionally on any errors with a RequestExeptionRequestException. The RequestException will contain an error message and code.

...

Will result in a request over the network the first time it's called; however, subsequent calls will return a cached value.

This is a non-blocking call.

Parameters

None.

Returns

Return Type

Description

CompletableFuture<String>

A CompletableFuture containing a String with the result.

Will complete exceptionally on any errors with a RequestExeptionRequestException. The RequestException will contain an error message and code.

...

Returns

Return Type

Description

Optional<CommandData>

An optional CommandData object, which contains a CompletableFuture<String>

A CompletableFuture<String> of the future result, as well as a cached version of the result since the last call.The result .

The result can contain error codes or messages. Usually, it will return a simple "success" if successful.

...

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device sourceDevice = gw.getDevice(sourceId);
String destinationDeviceId = sourceDevice.getConnectedGatewayId().get();
sourceDevice.bindDevice(destinationDeviceId, property)
			.get()
	        .getCommandResult()
	        .whenComplete((result, error) -> {
	            if (error != null) {
	                System.out.println("error calling bind: " + error.getMessage());
	            } else {
	            	System.out.println("bind device result: " + result);
	            }
			});

...

Returns

Return Type

Description

Optional<CommandData>

An optional CommandData object, which contains a CompletableFuture<String>

A CompletableFuture<String> of the future result, as well as a cached version of the result since the last call.

The result can contain error codes or messages. Usually, it will return a simple "success" if successful.

...

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device sourceDevice = gw.getDevice(sourceId);
String destinationDeviceId = sourceDevice.getConnectedGatewayId().get();
sourceDevice.unbindDevice(destinationDeviceId, property)
			.get() 	        .getCommandResult()
	        .whenComplete((result, error) -> {
	            if (error != null) {
	                System.out.println("error calling unbind: " + error.getMessage());
	            } else {
	            	System.out.println("unbind device result: " + result);
	            }
			});

...

Returns

Return Type

Description

Optional<CommandData>

An optional CommandData object, which contains a CompletableFuture<String>

A CompletableFuture<String> of the future result, as well as a cached version of the result since the last call.The result can contain error codes or messages. Usually, .

The result can contain error codes or messages. Usually, it will return a simple "success" if successful.

...

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device device = gw.getDevice(id);
List<Parameter> onOffParams = new ArrayList<>();
onOffParams.add(new Parameter(ConfigureReportingParameter.DIRECTION, "0x00"));
onOffParams.add(new Parameter(ConfigureReportingParameter.MIN_REPORTING_INTERVAL, "0x0000"));
onOffParams.add(new Parameter(ConfigureReportingParameter.MAX_REPORTING_INTERVAL, "0x012C")); // 5 minutes
try {
    CompletableFuture<String> futureResult = device.configureReporting("onOff", onOffParams).get().getCommandResult();
    String result = futureResult.get(30, TimeUnit.SECONDS);
    System.out.println("result: " + result);
} catch (Exception e) {
    throw new CompletionException(e);
}

...

Gets the round-trip latency from the Device to the Gateway.

This is a non-blocking call.

Will complete exceptionally on all errors.

Parameters

None.

Returns

Return Type

Description

Optional<CommandData>

An optional CommandData object, which contains a CompletableFuture<String>

A CompletableFuture<String> of the future result, as well as a cached version of the result since the last call.

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

language	javatext

GatewayClient{
gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gw.getDevice(id);
device.ping().ifPresent(data -> {
    data.getCommandResult().thenAccept( pingResult -> System.out.println(pingResult) );
});
...

leaveNetwork()

Usage

Request the device to leave the network.

Parameters

None.

Returns

None.

Examples

Code Block

language	java

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

...

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",	 "status":{"value":[0]},           // byte value: 0 = success, non-zero = failure
  "latency":46,                     // in 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

language	java

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

language	java

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 unicast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_unicast",
	"message":
		{
			"nodeId":"0x1234",
			"endpointId":"0x01",
			"localEndpoint":"0x01",		// optional, will onlydefault be read if responseOptions requires itto 0x01
			"commandIdclusterId":"0x000x0006",
			"payloadresponseOptions":"0x00010304050x02", 	// optional, canwill omit if there'sdefault to no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

Code Block

language	text
title	zcl multicast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_multicast",
	"message":
		{
			"groupId":"0x0001",
			"localEndpoint":"0x01",		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 default to 0x01 only be read if responseOptions requires it
			"clusterIdcommandId":"0x00060x00",
			"radiuspayload":"0x000x0001030405" 				// optional, willcan defaultomit toif 0x00 (max radius)
			"nonMemberRadius":"0x07",   // optional, will default to 0x07 (infinite non-member-radius)
			"responseOptions":"0x02", 	// optional, will default to no response
			"frameControl":"0x00",		// there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

Code Block

language	text
title	zcl multicast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_multicast",
	"message":
		{
			"groupId":"0x0001",
			"localEndpoint":"0x01",		// optional, will default to ZCL General Command, Client-to-Server0x01
			"clusterId":"0x0006",
			"manufacturerCoderadius":"0x00", 				// optional, will onlydefault beto read0x00 if frameControl requires it
(max radius)
			"transactionNumnonMemberRadius":"0x000x07",	   // optional, will onlydefault beto read0x07 if responseOptions requires it
(infinite non-member-radius)
			"commandIdresponseOptions":"0x000x02",
			"payload":"0x0001030405" 	// optional, canwill default omitto ifno there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

Code Block

language	text
title	zcl broadcast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_broadcast",
	"message":
		{
			"broadcastAddress":"0xFD",
			"endpoint":"0x01",
			"localEndpoint":"0x01",		// optional, will default to 0x01
			"clusterId":"0x0006response
			"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",
			"radiuspayload":"0x000x0001030405"			 	// optional, willcan defaultomit toif 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 only be read if frameControl requires it
			"transactionNum":"0x00",there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

Code Block

language	text
title	zcl broadcast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_broadcast",
	"message":
		{
			"broadcastAddress":"0xFD",
			"endpoint":"0x01",
			"localEndpoint":"0x01",		// optional, will onlydefault be read if responseOptions requires itto 0x01
			"commandIdclusterId":"0x000x0006",
			"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 unicast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zdo_unicast",
	"message":
		{
			"nodeId":"0x1234",
			"responseOptions":"0x02", 	// optional, will default to no response0x00 (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 only be read if 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
		}
}

...

Code Block

language	text
title	zdo broadcast unicast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zdo_broadcastunicast",
	"message":
		{
			"broadcastAddressnodeId":"0xFD0x1234",
			"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
		}
}

...

Protocol Message Response Specification

Code Block

language	text
title	zcl response or zcl passthrough message 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		{
			"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",
       "manufacturerCodeprotocolVersion":"0x00003",
            "transactionNum"messageType":"0x7Czcl_response",  // other valid value is zcl_passthrough_message
     "commandIdmessage":"0x01",
        {
    "payload        "sourceNode":"0x014363000xCB13",
        }
}

Code Block

language	text
title	zdo response protocol message

{     "gatewayApiVersionsourceEndpoint":"2.0.40x01",
    "protocolName        "localEndpoint":"zigbee0x01",
    "protocolVersion        "clusterId":"30x0006",
    "messageType        "encryption":"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

language	java

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

language	java

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

language	java

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

language	java

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();

Page Comparison

Versions Compared

Old Version 40

New Version Current

Key

Sub-Classes

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

leaveNetwork()

Usage

Parameters

Returns

Examples

sendProtocolMessage(String json)

Usage

Parameters

Protocol Message Specification

Throws

Examples

leaveNetwork()

Usage

Parameters

Returns

Examples

sendProtocolMessage(String json)

Usage

Parameters

Protocol Message Specification

Protocol Message Response Specification

Returns

Protocol Message Response Specification

Examples

Examples

Upgrade API

startOtaUpgrade()

Usage

Parameters

Returns

Examples

abortOtaUpgrade()

Usage

Parameters

Returns

Examples