...
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 listenershandlers, and perform firmware upgrades of the underlying network interface (i.e. module). It also offers some network management methods.
...
Code Block | ||
---|---|---|
| ||
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 DeviceEventListener DeviceEventHandler that will be called when DeviceEvents are received.
...
Name | Type | Description |
---|---|---|
c | ConnectionInfo | Represents a network interface that the GatewayClient can connect to. |
listenerhandler | DeviceEventListenerDeviceEventHandler | An instance of a class that implements the DeviceEventListener DeviceEventHandler interface (or a lambda that does the same). |
...
A newly constructed GatewayClient object connected to the network interface described by the ConnectionInfo object, that will call the registered DeviceEventListener DeviceEventHandler when a DeviceEvent is received.
...
Will return an exception if the client cannot connect to, or configure, the network interface.
Example
Code Block | ||
---|---|---|
| ||
// ExampleThis ofexample ashows lambdahow implementationto ofpass thein DeviceEventListenera parameter.class //that Willimplements simplyDeviceEventHandler printto the eventGatewayClient thatconstructor ispublic receivedclass fromSampleDeviceEventHandler theimplements DeviceDeviceEventHandler with{ the given ID. GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"), @Override public void onDeviceEvent(DeviceEvent event) { (event) -> {// Write your event handling code here 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
...
Example
...
GatewayClient gw = new GatewayClient( new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"), new SampleDeviceEventHandler() ); |
Code Block | ||
---|---|---|
| ||
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
...
Example
Code Block | ||
---|---|---|
| ||
// 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"));, ... for (ConnectionInfo c : gw.getConnectionInfo()) {(event) -> { // Write your event handling code here System.out.println("ConnectedDevice to portEvent: " + cevent.getValuegetStatus()); } |
getApiVersion()
Usage
Gets the version of the API.
Parameters
None.
Returns
...
Example
Code Block | ||
---|---|---|
| ||
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
String version = gw.getApiVersion(); |
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
...
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
Name | Type | Description |
---|---|---|
c | ConnectionInfo | Represents a network interface that the GatewayClient can connect to. |
handler | DeviceEventHandler | An instance of a class that implements the DeviceEventListener DeviceEventHandler interface (or a lambda that does the same). |
configFilePath |
Returns
None.
Example
Code Block | ||
---|---|---|
| ||
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
...
Returns
None.
Example
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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 devicesString | Path 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
Code Block |
---|
// This is an example of a custom configuration file that will configure a RapidConnect zigbee module with the appropriate 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" />
</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 Type | Description |
---|---|
Boolean | True if the system shut down gracefully; false otherwise. |
Example
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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 Type | Description |
---|---|
String | The version number. |
Example
Code Block | ||
---|---|---|
| ||
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
Name | Type | Description |
---|---|---|
handler | DeviceEventHandler | An instance of a class that implements the DeviceEventHandler interface (or a lambda that does the same). |
Returns
None.
Example
Code Block |
---|
// 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()); |
Code Block | ||
---|---|---|
| ||
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
Name | Type | Description |
---|---|---|
handler | DeviceEventHandler | An instance of a class that implements the DeviceEventHandler interface (or a lambda that does the same). |
Returns
None.
Example
Code Block | ||
---|---|---|
| ||
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 Type | Description |
---|---|
boolean | Returns true if any registered handlers were removed; otherwise returns false. |
Example
Code Block | ||
---|---|---|
| ||
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
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
Code Block | ||
---|---|---|
| ||
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 Type | Description |
---|---|
Collection<Device> | A collection of all the known Devices on the network that match the filter used. |
Example
Code Block | ||
---|---|---|
| ||
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)); |
...
getDevices(); |
getDevice(String id)
Usage
Get a list of all known devices on the network.
Parameters
Nonethe 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 | |
---|---|---|
Collection<Device> | A collection of all the known Devices on the networkDevice | 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
Code Block | ||
---|---|---|
| ||
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... Collection<Device>Device devicesd = gw.listDevices(getDevice("0123456789"); |
...
getGatewayDevices(
...
)
Usage
Get the device with the corresponding IDDevice 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
...
Parameters
None.
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 Collection<Device> | A collection of all the known GatewayClient Devices (i.e. the ID was not uniqueDevices associated with the network interface the GatewayClient has been initialized with, as opposed to remote devices on the network). |
Example
Code Block | ||
---|---|---|
| ||
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... DeviceCollection<Device> dgateways = gw.getDevicegetGatewayDevices("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.
...
- 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 | |
---|---|---|
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
...
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 | ||
---|---|---|
| ||
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
...
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 | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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, 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<NetworkStatus> | A CompletableFuture that will contain the network statuscontain the network status. NETWORK_UP if the command succeeded (or a network was already formed); otherwise NETWORK_COMMAND_FAILED. |
Example
Code Block | ||
---|---|---|
| ||
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... for (ConnectionInfo c : gw.getConnectionInfo()) { gw.getNetworkStatuscreateNetwork(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<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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... for (ConnectionInfo c : gw.getConnectionInfo()) { gw.scanForDevices(c, 30); } |
...