...
| Code Block |
|---|
|
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
| Name | Type | Description |
|---|
| c | ConnectionInfo | ConnectionInfo of the network interface being upgraded (see getConnectionInfo() API). |
Returns
| Return Type | Description |
|---|
| boolean | Will return true if a currently running upgrade process was found and a termination request was sent; otherwise, will return false. |
Example
| Code Block |
|---|
|
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.
...
- 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. |
...
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());
}
); |
...
getNetworkInfo(ConnectionInfo c)
Usage
Returns any relevant network information associated with 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<NetworkInformationn> | A CompletableFuture that will contain a NeworkInformation object. |
Example
| Code Block |
|---|
|
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
| Name | Type | Description |
|---|
| c | ConnectionInfo | ConnectionInfo of the network interface of interest (see getConnectionInfo() API). |
Returns
| Return Type | Description |
|---|
| 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
| Code Block |
|---|
|
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
| 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<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
| 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<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 |
|---|
|
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<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 |
|---|
|
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
| Name | Type | Description |
|---|
| json | String | A JSON string formatted according the the protocol message specification (see below) |
...
| Code Block |
|---|
| language | text |
|---|
| title | 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 Type | Description |
|---|
| CompletableFuture<String> | A JSON string formatted according to the protocol message response specification (see below) |
...