Will return an exception if the client cannot connect to, or configure, the network interface.

Example

...

This

...

is

...

an

...

example

...

of

...

a

...

custom

...

configuration

...

file

...

that

...

will

...

configure

...

a

...

RapidConnect

...

zigbee

...

module

...

with

...

custom clusters. This can be used to define custom manufacturer specific clusters, or define which client clusters should pass through zigbee commands to be handled by GatewayClient callbacks.

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<deviceConfig>
    <name>Combined Interface Coordinator</name>

    <deviceType>
        <reducedFunctionDevice>false</reducedFunctionDevice>
        <sleepy>false</sleepy>
    </deviceType>

    <endpoint id="1" profileId="0x0104" deviceId="0x0007" deviceVersion="1">
        <serverClusters>
            <cluster id="0x0000" />
            <cluster id="0x0003" />
            <cluster id="0x0006" passthroughAll="true"/> <!-- on/off -->
            <cluster id="0x0008" passthroughAll="true"/> <!-- level control -->
            <cluster id="0x000A">
                <attribute id="0x0002" type="0x2b" readable="true" writeable="true" reportable="false" />
                <attribute id="0x0003" type="0x23" readable="true" writeable="true" reportable="false" />
                <attribute id="0x0004" type="0x23" readable="true" writeable="true" reportable="false" />
                <attribute id="0x0005" type="0x2b" readable="true" writeable="true" reportable="false" />
                <attribute id="0x0006" type="0x23" readable="true" writeable="false" reportable="false" />
                <attribute id="0x0007" type="0x23" readable="true" writeable="false" reportable="false" />
            </cluster>
            <cluster id="0x0019" />
        </serverClusters>
        <clientClusters>
            <cluster id="0x0000" />
            <cluster id="0x0003" />
            <cluster id="0x0004" />
            <cluster id="0x0005" />
            <cluster id="0x0006" />
            <cluster id="0x0008" />
            <cluster id="0x0101" />
            <cluster id="0x0201" />
            <cluster id="0x0202" />
            <cluster id="0x0500"> <!-- ias zone -->
                <command id="0x00" passthrough="true"/> <!-- zone status change notification -->
                <command id="0x01" passthrough="true"/> <!-- zone enroll request -->
            </cluster>
            <cluster id="0x0b04" />
        </clientClusters>    <cluster  </endpoint>
</deviceConfig>id="0xFE11" passthroughAll="true"/> <!-- custom cluster example -->
        </clientClusters>
    </endpoint>
</deviceConfig>

shutdown()

Usage

Performs a graceful shut down of the GatewayClient, allowing for all subsystems to save any critical data and release system resources, such as file handles, open ports, user threads, etc.

...

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Collection<Device> gateways = gw.getGatewayDevices();

Upgrade API

...

abortUpgrade(ConnectionInfo c

...

)

Usage

Performs Cancels a firmware upgrade of the network interface (i.e. module) represented by the given ConnectionInfo object.

Progress is conveyed via a user-provided ResultConsumer<SerialUploadResult> callback. The callback is called more than once until completion of the upgrade, or if an error occurs.

The callback is called from a dedicated thread.

Notes:

...

process that is currently running.

Will return true if a currently running upgrade process was found and a termination request was sent; otherwise, will return false.

This method is non-blocking

...

and is

...

thread-safe.

Parameters

file

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface being upgraded (see getConnectionInfo() API).

Returns

...

Returns

...

Progress is conveyed via a user-provided ResultConsumer<SerialUploadResult> callback. The callback is called more than once until completion of the upgrade, or if an error occurs.

If there is an attempt to upgrade to the same ConnectionInfo while an upgrade is already in progress, then that attempt will fail, the ResultConsumer callback will be called with an error, and the CompletableFuture shall return a Status.FAILED immediately.

Example

Code Block

language	java

public void doSerialUpgrade() throws InterruptedException, ExecutionException, TimeoutException, IOException {
	// setup
	final GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
	final File upgradeFile = new File("/path/to/file");

	// start the upgrade
	final Collection<ConnectionInfo> connections = gw.getConnectionInfo();
	for (ConnectionInfo c : connections) {
		if (c.getType() == ConnectionType.ZIGBEE_UART) {
			final Status status = gw.upgradeFirmware(c, upgradeFile, serialCallback).get(UPGRADE_TIMEOUT_MINUTES, TimeUnit.MINUTES);
			System.out.println("Status: " + status);
		}
	}
}
    
public final static ResultConsumer<SerialUploadResult> serialCallback = ResultConsumer.createResultConsumer(
    (result) -> {
        SerialUploadResult r = (SerialUploadResult)result;
        System.out.println("Progress: " + r.getProgress());
    },
    (throwable) -> {
        System.err.println("Serial upload failed: " + throwable.getMessage());
     }
);

Network API

getNetworkInfo(ConnectionInfo c)

Usage

Returns any relevant network information associated with the specified network interface.

Parameters

...

Returns

...

Example

...

language	java

Return Type	Description
boolean	Will return true if a currently running upgrade process was found and a termination request was sent; otherwise, will return false.

Example

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));

...

for (ConnectionInfo c: gw.getConnectionInfo()) {
    gw.abortUpgrade(c);
}

upgradeFirmware(ConnectionInfo c, File file, ResultConsumer<SerialUploadResult> callback)

Usage

Performs a firmware upgrade of the network interface (i.e. module) represented by the given ConnectionInfo object.

Progress is conveyed via a user-provided ResultConsumer<SerialUploadResult> callback. The callback is called more than once until completion of the upgrade, or if an error occurs.

The callback is called from a dedicated thread.

Notes:

If there is an attempt to upgrade to the same ConnectionInfo while an upgrade is already in progress, then that attempt will fail, the ResultConsumer callback will be called with an error, and the CompletableFuture shall return a Status.FAILED immediately.
This method is non-blocking.
This method is not thread-safe.

Parameters

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface being upgraded (see getConnectionInfo() API).
file	File	Upgrade file for the specified network interface.
callback	ResultConsumer<SerialUploadResult>	User-provided callback in order to receive notifications regarding upgrade progress.

Returns

Return Type	Description
CompletableFuture<Status>	A CompletableFuture that will contain the status of the upgrade result.

Progress is conveyed via a user-provided ResultConsumer<SerialUploadResult> callback. The callback is called more than once until completion of the upgrade, or if an error occurs.

If there is an attempt to upgrade to the same ConnectionInfo while an upgrade is already in progress, then that attempt will fail, the ResultConsumer callback will be called with an error, and the CompletableFuture shall return a Status.FAILED immediately.

Example

Code Block

language	java

public void doSerialUpgrade() throws InterruptedException, ExecutionException, TimeoutException, IOException {
	// setup
	final GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
	final File upgradeFile = new File("/path/to/file");

	// start the upgrade
	final Collection<ConnectionInfo> connections = gw.getConnectionInfo();
	for (ConnectionInfo c : gw.getConnectionInfo(connections)) {
	gw.getNetworkInfo(c);
}

createNetwork(ConnectionInfo c)

Usage

Forms a network on the specified network interface, automatically choosing the best channel to form on.

Note that it isn't strictly necessary to use this method, as the GatewayClient will attempt to automatically form a network when first initialized.

Parameters

...

Returns

...

A CompletableFuture that will contain a NetworkInformation object.

The NetworkInformation.status field will be NETWORK_UP if the command succeeded (or a network was already formed); otherwise NETWORK_COMMAND_FAILED.

Example

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
	gw.createNetwork(c);
}

createNetwork(ConnectionInfo c, List<Integer> channels)

Usage

Forms a network on the specified network interface, attempting to form on the best channel from the provided list of channels.

Note that it isn't strictly necessary to use this method, as the GatewayClient will attempt to automatically form a network when first initialized.

Parameters

...

Returns

...

A CompletableFuture that will contain a NetworkInformation object.

...

	if (c.getType() == ConnectionType.ZIGBEE_UART) {
			final Status status = gw.upgradeFirmware(c, upgradeFile, serialCallback).get(UPGRADE_TIMEOUT_MINUTES, TimeUnit.MINUTES);
			System.out.println("Status: " + status);
		}
	}
}
    
public final static ResultConsumer<SerialUploadResult> serialCallback = ResultConsumer.createResultConsumer(
    (result) -> {
        SerialUploadResult r = (SerialUploadResult)result;
        System.out.println("Progress: " + r.getProgress());
    },
    (throwable) -> {
        System.err.println("Serial upload failed: " + throwable.getMessage());
     }
);

Network API

getNetworkInfo(ConnectionInfo c)

Usage

Returns any relevant network information associated with the specified network interface.

Parameters

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface of interest (see getConnectionInfo() API).

Returns

Return Type	Description
CompletableFuture<NetworkInformationn>	A CompletableFuture that will contain a NeworkInformation object.

Example

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
	gw.createNetworkgetNetworkInfo(c);
}

...

createNetwork(ConnectionInfo c)

Usage

Dissolves the Forms a network on the specified network interface.

Parameters

...

, automatically choosing the best channel to form on.

Note that it isn't strictly necessary to use this method, as the GatewayClient will attempt to automatically form a network when first initialized.

Parameters

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface of interest (see getConnectionInfo() API).

Returns

Return Type

Description

CompletableFuture<NetworkInformation>

A CompletableFuture that will contain a NetworkInformation object.

The NetworkInformation.status field will be NETWORKbe NETWORK_DOWN UP if the command succeeded (or a network was already downformed); otherwise , NETWORK_COMMAND_FAILED.

Example

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
	gw.dissolveNetworkcreateNetwork(c);
}

...

createNetwork(ConnectionInfo c,

...

List<Integer> channels)

Usage

Opens the permit join window Forms a network on the specified network interface so that devices who are in pairing mode can join the network.

Parameters

...

, attempting to form on the best channel from the provided list of channels.

Note that it isn't strictly necessary to use this method, as the GatewayClient will attempt to automatically form a network when first initialized.

Parameters

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface of interest (see getConnectionInfo() API).
durationchannels	intList<Integer>	The amount of time, between 0-254 seconds, to open the network permit join window forA list of channels to attempt to form on. Will scan channels in order, and form on the first one that meets quality thresholds.

Returns

Return Type

Description

CompletableFuture<NetworkInformation>

A CompletableFuture that will contain a NetworkInformation object.

The NetworkInformation.status field will be NETWORKbe NETWORK_OPEN UP if the command succeeded (or a network was already formed); otherwise NETWORK_COMMAND_FAILED otherwise.

Example

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... for (ConnectionInfo c : gw.getConnectionInfo()) { gw.scanForDevices(c, 30); }

Code Block

language	java

	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
	gw.createNetwork(c);
}

dissolveNetwork(ConnectionInfo c)

Usage

Dissolves the network on the specified network interface.

Parameters

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface of interest (see getConnectionInfo() API).

Returns

Return Type

Description

CompletableFuture<NetworkInformation>

A CompletableFuture that will contain a NetworkInformation object.

The NetworkInformation.status field will be NETWORK_DOWN if the command succeeded (or network was already down); otherwise, NETWORK_COMMAND_FAILED.

Example

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
	gw.dissolveNetwork(c);
}

scanForDevices(ConnectionInfo c, int duration)

Usage

Opens the permit join window on the specified network interface so that devices who are in pairing mode can join the network.

Parameters

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface of interest (see getConnectionInfo() API).
duration	int	The amount of time, between 0-254 seconds, to open the network permit join window for.

Returns

Return Type

Description

CompletableFuture<NetworkInformation>

A CompletableFuture that will contain a NetworkInformation object.

The NetworkInformation.status field will be NETWORK_OPEN if the command succeeded; NETWORK_COMMAND_FAILED otherwise.

Example

Code Block

language	java

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
	gw.scanForDevices(c, 30);
}

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 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
		}
}

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 0x01
			"clusterId":"0x0006",
			"radius":"0x00"				// optional, will default to 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 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	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	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 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	text
title	zdo 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 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",
    "protocolVersion":"3",
    "messageType":"zcl_response",  // 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

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();
    
    gw.sendProtocolMessage(message.toJson())
          .thenAccept(jsonResponse -> System.out.println(jsonResponse));
}

Page Comparison

Versions Compared

Old Version 33

New Version Current

Key

Example

shutdown()

Usage

Upgrade API

abortUpgrade(ConnectionInfo c

)

Usage

Parameters

Returns

Returns

Example

Network API

getNetworkInfo(ConnectionInfo c)

Usage

Parameters

Returns

Example

Example

upgradeFirmware(ConnectionInfo c, File file, ResultConsumer<SerialUploadResult> callback)

Usage

Parameters

Returns

Example

createNetwork(ConnectionInfo c)

Usage

Parameters

Returns

Example

createNetwork(ConnectionInfo c, List<Integer> channels)

Usage

Parameters

Returns

Network API

getNetworkInfo(ConnectionInfo c)

Usage

Parameters

Returns

Example

createNetwork(ConnectionInfo c)

Usage

Parameters

Parameters

Returns

Example

createNetwork(ConnectionInfo c,

List<Integer> channels)

Usage

Parameters

Parameters

Returns

Example

dissolveNetwork(ConnectionInfo c)

Usage

Parameters

Returns

Example

scanForDevices(ConnectionInfo c, int duration)

Usage

Parameters

Returns

Example

sendProtocolMessage(String json)

Usage

Parameters

Protocol Message Specification

Returns

Protocol Message Response Specification

Examples