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 listeners, and perform firmware upgrades of the underlying network interface (i.e. module). It also offers some network management methods.

Constructors, Shutdown, and Connection Info API

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

Name	Type	Description
c	ConnectionInfo	Represents 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, DeviceEventListener listener)

Usage

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

Parameters

Name	Type	Description
c	ConnectionInfo	Represents a network interface that the GatewayClient can connect to.
listener	DeviceEventListener	An instance of a class that implements the DeviceEventListener 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 DeviceEventListener 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

// Example of a lambda implementation of the DeviceEventListener parameter.
// 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) -> {
        System.out.println("Device Event: " + event.getStatus());
        System.out.println("Device: " + event.getDevice().getID()); 
    }
);

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 Type	Description
Boolean	True 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 Type	Description
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());    
}

Listeners API

addDeviceEventListener(DeviceEventListener listener)

Usage

Allows a class to register itself to receive DeviceEvents.

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

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

Parameters

Name	Type	Description
listener	DeviceEventListener	An instance of a class that implements the DeviceEventListener interface (or a lambda that does the same).

Returns

None.

Example

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

removeDeviceEventListener(DeviceEventListener listener)

Usage

Removes a previously registered listener.

Parameters

Name	Type	Description
listener	DeviceEventListener	An instance of a class that implements the DeviceEventListener interface (or a lambda that does the same).

Returns

None.

Example

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
DeviceEventListener l = new SampleDeviceEventListener();
gw.addDeviceEventListener(l);
...
gw.removeDeviceEventListener(l);
...

removeAllDeviceEventListeners()

Usage

Removes all previously registered listeners.

Parameters

None.

Returns

None.

Example

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

Devices API

listDevices(Predicate<Device> filter)

Usage

Get a filtered list of known devices on the network.

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

Parameters

Name	Type	Description
filter	Predicate<Device>	A Predicate that can be used to query for certain types of devices.

Returns

Return Type	Description
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 a list of all the lights on the network
Collection<Device> devices = gw.listDevices(d -> d.getDeviceType().equals(LightDevice.DEVICE_TYPE));

listDevices()

Usage

Get a list of all known devices on the network.

Parameters

None.

Returns

Return Type	Description
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.listDevices();

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

Name	Type	Description
id	String	A unique identifier associated with the Device.

Returns

Return Type	Description
Device	Device 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");

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.

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

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

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

Returns

Return Type	Description
CompletableFuture<NetworkStatus>	A CompletableFuture that will contain the network status.

Example

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

createNetwork(ConnectionInfo c)

Usage

Forms a network on the specified network interface.

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

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

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

A CompletableFuture that will contain the network status.

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

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

A CompletableFuture that will contain the network status.

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