GatewayClient

Owned by Saman Sartipi (Deactivated)
Last updated: Nov 05, 2019 by Saman Sartipi (Deactivated)
13 min read

Overview

The GatewayClient represents a connection to a network interface, such as a zigbee module. It allows a user to query for, and interact with, remote network devices without knowing anything about the underlying network or communication protocols.

The GatewayClient API offers methods to construct and shutdown the GatewayClient, grab the connection information of the underlying network interface, interact with Devices, as well as add/remove event handlers, and perform firmware upgrades of the underlying network interface (i.e. module). It also offers some network management methods.

Constructors, Shutdown, and miscellaneous info

GatewayClient(ConnectionInfo c)

Usage

Creates a GatewayClient object that represents a single network interface.

Will attempt to automatically form a network on the given interface.

Parameters

NameTypeDescription
cConnectionInfoRepresents a network interface that the GatewayClient can connect to.

Returns

A newly constructed GatewayClient object connected to the network interface described by the ConnectionInfo object.

Will attempt to form a network on the network interface.

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

Example

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

GatewayClient(ConnectionInfo c, DeviceEventHandler handler)

Usage

Creates a GatewayClient object that represents a single network interface, with an attached DeviceEventHandler that will be called when DeviceEvents are received.

Parameters

NameTypeDescription
cConnectionInfoRepresents a network interface that the GatewayClient can connect to.
handlerDeviceEventHandlerAn instance of a class that implements the DeviceEventHandler interface (or a lambda that does the same).

Returns

A newly constructed GatewayClient object connected to the network interface described by the ConnectionInfo object, that will call the registered DeviceEventHandler when a DeviceEvent is received.

Will attempt to form a network on the network interface.

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

Example

// This example shows how to pass in a class that implements DeviceEventHandler to the GatewayClient constructor
public class SampleDeviceEventHandler implements DeviceEventHandler {
    @Override
    public void onDeviceEvent(DeviceEvent event) {
        // Write your event handling code here
        System.out.println("Device Event: " + event.getStatus());
        System.out.println("Device: " + event.getDevice().getID()); 
    }
}

...

GatewayClient gw = new GatewayClient( new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"), new SampleDeviceEventHandler() );
// This example shows how to use a lambda in place of the DeviceEventHandler implementation.
// Will simply print the event that is received from the Device with the given ID.
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"),
    (event) -> {
        // Write your event handling code here
        System.out.println("Device Event: " + event.getStatus());
        System.out.println("Device: " + event.getDevice().getID()); 
    }
);

GatewayClient(ConnectionInfo c, DeviceEventHandler handler, String configFilePath)

Usage

Creates a GatewayClient object that represents a single network interface, with an attached DeviceEventHandler that will be called when DeviceEvents are received, and a path to a configuration file containing a the desired configuration of the network interface.

For example, in the case of a RapidConnect zigbee module, the custom configuration file would be an XML file that contains clusters and attributes that you want the zigbee module to be configured with.

Parameters

NameTypeDescription
cConnectionInfoRepresents a network interface that the GatewayClient can connect to.
handlerDeviceEventHandlerAn instance of a class that implements the DeviceEventHandler interface (or a lambda that does the same).
configFilePathStringPath on the filesystem where a custom configuration file can be found.

Returns

A newly constructed GatewayClient object connected to the network interface described by the ConnectionInfo object, that will call the registered DeviceEventHandler when a DeviceEvent is received, and configured using the custom configuration file located at configFilePath.

Will attempt to form a network on the network interface.

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.

<?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" />
            <cluster 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.

This is a blocking call and is not thread-safe.

Parameters

None.

Returns

Return TypeDescription
BooleanTrue if the system shut down gracefully; false otherwise.

Example

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

getConnectionInfo()

Usage

Gets a list of ConnectionInfo descriptors that the GatewayClient knows about.

Parameters

None.

Returns

Return TypeDescription
Collection<ConnetionInfo>A Collection that contains one ConnectionInfo object per network interface that the GatewayClient knows about.

Example

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
    System.out.println("Connected to port: " + c.getValue());    
}

getApiVersion()

Usage

Gets the version of the API.

Parameters

None.

Returns

Return TypeDescription
StringThe version number.

Example

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


Handler API

addDeviceEventHandler(DeviceEventHandler handler)

Usage

Allows a class to register itself to receive DeviceEvents.

If a handler object is already registered, calling this method will have no effect (i.e. duplicate handler objects are ignored).

Handlers are called from a dedicated thread, in the sequence that they were registered.

Parameters

NameTypeDescription
handlerDeviceEventHandlerAn instance of a class that implements the DeviceEventHandler interface (or a lambda that does the same).

Returns

None.

Example

// This example shows how to pass in a class that implements DeviceEventHandler
public class SampleDeviceEventHandler implements DeviceEventHandler {
    @Override
    public void onDeviceEvent(DeviceEvent event) {
        // Write your event handling code here
        System.out.println("Device Event: " + event.getStatus());
        System.out.println("Device: " + event.getDevice().getID()); 
    }
}

...

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
gw.addDeviceEventHandler(new SampleDeviceEventHandler());
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
gw.addDeviceEventHandler(
    (event) -> {
        // do something with event
        System.out.println("Device Event: " + event.getStatus());
        System.out.println("Device: " + event.getDevice().getID()); 
    }
);

removeDeviceEventHandler(DeviceEventHandler handler)

Usage

Removes a previously registered handler.

Parameters

NameTypeDescription
handlerDeviceEventHandlerAn instance of a class that implements the DeviceEventHandler interface (or a lambda that does the same).

Returns

None.

Example

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
DeviceEventHandler handler = new SampleDeviceEventHandler();
gw.addDeviceEventListener(handler);
...
gw.removeDeviceEventListener(handler);
...

removeAllDeviceEventHandlers()

Usage

Removes all previously registered handlers.

Parameters

None.

Returns

Return TypeDescription
booleanReturns true if any registered handlers were removed; otherwise returns false.

Example

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


Devices API

getDevices(Predicate<Device> filter)

Usage

Get a filtered list of known devices on the network. Will not return 

The method takes a Predicate, which is used to filter the device list.

Parameters

NameTypeDescription
filterPredicate<Device>A Predicate that can be used to query for certain types of devices.

Returns

Return TypeDescription
Collection<Device>A collection of all the known Devices on the network that match the filter used.

Example

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// get all the lights and sensors on the network
Collection<Device> devices = gw.getDevices(d -> d.getDeviceType().equals(LightDevice.DEVICE_TYPE));
Collection<Device> sensors = gw.getDevices(d -> d.getDeviceType().equalsIgnoreCase("occupancy sensor"));

getDevices()

Usage

Get a list of all known devices on the network.

Parameters

None.

Returns

Return TypeDescription
Collection<Device>A collection of all the known Devices on the network.

Example

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

getDevice(String id)

Usage

Get the device with the corresponding ID.

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

Parameters

NameTypeDescription
idStringA unique identifier associated with the Device.

Returns

Return TypeDescription
DeviceDevice associated with the ID; otherwise null on all errors, including if the ID was not found, or if there were duplicate Devices found (i.e. the ID was not unique).

Example

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

getGatewayDevices()

Usage

Get the Device associated with a network interface that the GatewayClient has been initialized with.

For example, this would return the Device object associated with the zigbee module the GatewayClient has been constructed with, so that you could get its properties and interact with it using the Device API.

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

Parameters

None.

Returns

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

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

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

Returns

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

Example

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

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

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

Returns

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

Example

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

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_UP if the command succeeded (or a network was already formed); otherwise NETWORK_COMMAND_FAILED.

Example

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

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

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

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

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

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


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

Protocol Message Response Specification

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"
        }
}
zdo response protocol message
{
    "gatewayApiVersion":"2.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",
    "messageType":"zdo_response",
    "message":
        {
            "sourceNode":"0xCB13",
            "transactionNum":"0x7C",
            "commandId":"0x0001",
            "payload":"0x01436300"
        }
}
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

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

Legal Notices

Copyright © 2020 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.