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

...

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

language	javatext

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

...

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 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":"0x00there'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-Server
0x01
			"manufacturerCodeclusterId":"0x000x0006",
			"radius":"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", 	// 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	zcl broadcast protocol message

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"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 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":"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, 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	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));
}

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

Versions Compared

Old Version 42

New Version Current

Key

Sub-Classes

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

Upgrade API

startOtaUpgrade()

Usage

Parameters

Returns

Examples

abortOtaUpgrade()

Usage

Parameters

Returns

Examples

Page Comparison

Versions Compared

Old Version 42

New Version Current

Key

Sub-Classes

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

Upgrade API

startOtaUpgrade()

Usage

Parameters

Returns

Examples

abortOtaUpgrade()

Usage

Parameters

Returns

Examples