...
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 miscellaneous info
GatewayClient(ConnectionInfo c)
...
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.
...
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.
...
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(); ... |
...
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(); |
Listeners API
addDeviceEventListener(DeviceEventListener listener)
Usage
Allows a class to register itself to receive DeviceEvents.
...
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
| 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
| 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
| 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(); |
...
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
| 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)); |
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
| Code Block | ||
|---|---|---|
| ||
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
| Code Block | ||
|---|---|---|
| ||
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device d = gw.getDevice("0123456789"); |
...
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. |
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());
}
); |
...
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.
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
| 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);
} |
...