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.

...

Assumes that id is unique, and there should only be one device per ID.

Parameters

...

None.

Returns

Return Type	Description
Collection<Device>	A collection of all the known GatewayClient Devices (i.e. Devices associated with the network interface the GatewayClient has been initialized with, as opposed to remote devices on the network).

Example

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

Cancels a firmware upgrade 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

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

Returns

Return Type	Description
Collection<Device>	A collection of all the known GatewayClient Devices (i.e. Devices associated with the network interface the GatewayClient has been initialized with, as opposed to remote devices on the network)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()) {
 Collection<Device> gateways = gw.getGatewayDevicesabortUpgrade(c);
}

Upgrade API

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.

...

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.

...

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

...

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

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

Name	Type	Description
c	ConnectionInfo	ConnectionInfo of the network interface of interest (see getConnectionInfo() API).
channels	List<Integer>	A 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 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);
}

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)

...

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)

...

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

...

Page Comparison

Versions Compared

Old Version 36

New Version Current

Key

Example

shutdown()

Usage

Parameters

None.

Returns

Example

Upgrade API

abortUpgrade(ConnectionInfo c)

Usage

Parameters

Returns

Example

Upgrade API

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

Usage

Parameters

Returns

Example

getNetworkInfo(ConnectionInfo c)

Usage

Parameters

Returns

Example

createNetwork(ConnectionInfo c)

Usage

Parameters

Returns

Example

createNetwork(ConnectionInfo c, List<Integer> channels)

Usage

Parameters

Returns

Example

dissolveNetwork(ConnectionInfo c)

Usage

Parameters

Returns

Example

scanForDevices(ConnectionInfo c, int duration)

Usage

Parameters

Returns

Example

sendProtocolMessage(String json)

Usage

Parameters

Returns