Versions Compared

Old Version 32

changes.mady.by.user Saman Sartipi

Saved on

compared with

New Version Current

changes.mady.by.user Saman Sartipi

Saved on

Key

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

...

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
languagejava
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
NameTypeDescription
cConnectionInfoConnectionInfo 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
languagejava
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

getNetworkStatus(ConnectionInfo c)

Usage

Returns the network status of the specified network interface.

Parameters

...

Returns

...

Example

...

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

Example

Code Block
languagejava
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

NameTypeDescription
cConnectionInfoConnectionInfo of the network interface being upgraded (see getConnectionInfo() API).
fileFileUpgrade file for the specified network interface.
callbackResultConsumer<SerialUploadResult>User-provided callback in order to receive notifications regarding upgrade progress.

Returns

Return TypeDescription
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
languagejava
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) {
		if (c.getType() == ConnectionType.ZIGBEE_UART) {
			final Status status = gw.getNetworkStatus(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 the network status.

NETWORK_UP if the command succeeded (or a network was already formed); otherwise NETWORK_COMMAND_FAILED.

Example

Code Block
languagejava
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.

...

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

NameTypeDescription
cConnectionInfoConnectionInfo of the network interface of interest (see getConnectionInfo() API).

Returns

channels
Return TypeDescriptionList<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

...

A CompletableFuture that will contain the network status.

NETWORK_UP if the command succeeded (or a network was already formed); otherwise NETWORK_COMMAND_FAILED.

Example

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

Example

Code Block
languagejava
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

NameTypeDescription
cConnectionInfoConnectionInfo of the network interface of interest (see getConnectionInfo() API).

Returns

Return TypeDescription
CompletableFuture<NetworkStatus>CompletableFuture<NetworkInformation>

A CompletableFuture that will contain the network statusa NetworkInformation object.

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

Example

Code Block
languagejava
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, 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

NameTypeDescription
cConnectionInfoConnectionInfo of the network interface of interest (see getConnectionInfo() API).
durationchannelsintList<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 TypeDescription
CompletableFuture<NetworkStatus>CompletableFuture<NetworkInformation>

A CompletableFuture that will contain the network statusa NetworkInformation object.

The NetworkInformation.status field will be 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
languagejava
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

NameTypeDescription
cConnectionInfoConnectionInfo of the network interface of interest (see getConnectionInfo() API).

Returns

Return TypeDescription
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
languagejava
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

NameTypeDescription
cConnectionInfoConnectionInfo of the network interface of interest (see getConnectionInfo() API).
durationintThe amount of time, between 0-254 seconds, to open the network permit join window for.

Returns

Return TypeDescription
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
languagejava
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

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

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


Code Block
languagetext
titlezcl 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
languagetext
titlezcl 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
languagetext
titlezdo 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
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":
        {
            "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",
            "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();
    
    gw.sendProtocolMessage(message.toJson())
          .thenAccept(jsonResponse -> System.out.println(jsonResponse));
}