Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This is a non-blocking call.

Will complete exceptionally on all errors.

Parameters

None.

Returns

Return TypeDescription
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
languagejavatext
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
languagejava
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
languagetext
titlezcl 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
languagejava
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
languagejava
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

NameTypeDescription
jsonStringA JSON string formatted according the the protocol message specification (see below)

Protocol Message Specification

Code Block
languagetext
titlezcl 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
languagetext
titlezcl 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
languagetext
titlezdo 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
languagetext
titlezdo 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
languagetext
titlezdo 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
		}
}

...


Code Block

...

language

...

Protocol Message Response Specification

{
Code Block
languagetext
titlezcl response or zcl passthrough message
text

...

titlezdo 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 TypeDescription
CompletableFuture<String>A JSON string formatted according to the protocol message response specification (see below)

Protocol Message Response Specification

Code Block
languagetext
titlezcl 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
languagetext
titlezdo 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
languagetext
titledefault 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
languagejava
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
languagetext
titledefault 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
languagejava
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
languagejava
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
languagejava
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();