Versions Compared

Key

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

...

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.

...

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

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... final Device d = gw.getDevice(id);
Code Block
Code Block
languagejava
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

text
{
  "status":{"value":[0]},           // byte value: 0 = success, non-zero = failure
  "latency":46,                     // in ms
  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
		}
}"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":
		{
			"nodeId":"0x1234",
			"groupIdendpointId":"0x00010x01",
			"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 0x07no (infinite non-member-radius)
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 no response0x07 (infinite non-member-radius)
			"frameControlresponseOptions":"0x000x02",	 	// optional, will default to ZCL 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",
	// optional, will default to no response
			"transactionNumlocalEndpoint":"0x000x01",		// optional, will onlydefault beto read if responseOptions requires it
0x01
			"commandIdclusterId":"0x00010x0006",
			"payloadradius":"0x00010304050x00" 				// optional, canwill omitdefault ifto 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",
			"radius":"0x00"				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 defaultonly tobe 0x00read (maxif radius)
			"responseOptions":"0x02", 	// optional, will default to no response
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

...

Protocol Message Response Specification

{
Code Block
languagetext
titlezcl response or zcl passthrough message
text

...

titlezdo unicast protocol message
{
	"gatewayApiVersion":"2.0.4",
    	"protocolName":"zigbee",
    	"protocolVersion":"3",
    	"messageType":"zclzdo_responseunicast",
 // 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"
        }
}
Code Block
languagetext
titlezdo response protocol message
{
    "gatewayApiVersion":"2.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",
    "messageType":"zdo_response",
    "message":
        {
            "sourceNode":"0xCB13",
            "transactionNum":"0x7C",
            "commandId":"0x0001",	"message":
		{
			"nodeId":"0x1234",
			"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
		}
}


Code Block
languagetext
titlezdo broadcast protocol message
{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zdo_broadcast",
	"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",
    "messageType":"zcl_response",  // other valid value is zcl_passthrough_message
    "message":
        {
            "payloadsourceNode":"0x014363000xCB13",
        } }
Code Block
languagetext
titledefault response protocol message
{     "gatewayApiVersionsourceEndpoint":"2.0.40x01",
     "protocolName       "localEndpoint":"zigbee0x01",
      "protocolVersion      "clusterId":"30x0006",
    "messageType        "encryption":"default_response0x00",
    "status        "frameControl":"0x000x02" // 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));
}

,
            "manufacturerCode":"0x0000",
            "transactionNum":"0x7C",
            "commandId":"0x01",
            "payload":"0x01436300"
        }
}


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