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

...

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.

...

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.

...

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 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) -> {
	        .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, 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);
}

...

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 beto read if responseOptions requires it
0x01
			"commandIdclusterId":"0x000x0006",
			"payloadresponseOptions":"0x00010304050x02", 	// optional, canwill omitdefault ifto 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",		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 defaultonly to 0x01
			"clusterId":"0x0006",be read if frameControl requires it
			"radiustransactionNum":"0x00"		,		// optional, will only be defaultread toif 0x00responseOptions (maxrequires radius)it
			"nonMemberRadiuscommandId":"0x070x00",
  // optional, will default to 0x07 (infinite non-member-radius)
			"responseOptionspayload":"0x020x0001030405", 	// optional, can willomit defaultif tothere's 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",	//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 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	zcl broadcast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_broadcast",
	"message":
		{
			"broadcastAddress":"0xFD",
			"endpoint":"0x01",
			"localEndpoint":"0x01",		0x00 (max radius)
			"nonMemberRadius":"0x07",   // optional, will default to 0x07 (infinite non-member-radius)
			"responseOptions":"0x02", 	// optional, will default to no response
			"frameControl":"0x00",		// optional, will default to 0x01
			"clusterId":"0x0006",
			"radius":"0x00"				// optional, will default to 0x00 (max radius)
			"responseOptions":"0x02", 	// optional, will default to no response
			"frameControl":"0x00",		// optional, will default to ZCL General Command, 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", 	// optional, will default to no response
			"payloadframeControl":"0x00010304050x00" ,		// optional, canwill omitdefault ifto there'sZCL 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_broadcastGeneral 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 protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zdo_unicast",
	"message":
		{
			"broadcastAddressnodeId":"0xFD0x1234",
			"radiusresponseOptions":"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 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",
            "manufacturerCode":"0x0000",
            "transactionNum":"0x7C",
            "commandId":"0x01",
            "payload":"0x01436300"
        }
}
	"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	zdo zcl response protocol or zcl passthrough message

{
    "gatewayApiVersion":"2.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",
    "messageType":"zdozcl_response",  // other valid value is zcl_passthrough_message
    "message":
        {
            "sourceNode":"0xCB13",
            "transactionNumsourceEndpoint":"0x7C0x01",
            "commandIdlocalEndpoint":"0x00010x01",
            "payloadclusterId":"0x014363000x0006",
        } }

Code Block

language	text
title	default response protocol message

{
    "gatewayApiVersionencryption":"2.0.40x00",
       "protocolName":"zigbee",     "protocolVersionframeControl":"30x02",
    "messageType":"default_response",        "statusmanufacturerCode":"0x000x0000",
// 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));
}

 "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

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 41

New Version Current

Key

Sub-Classes

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