public class GatewayClient extends Object
GatewayClient
represents an aggregation of one or more network interfaces.
It allows a user to query for, and interact with, remote network devices as if they were all part of one logical network.
It aims to abstract away all concepts of the underlying networks and their communication protocols so that users can interact with devices without having to know anything about the networks they're on.
Constructor and Description |
---|
GatewayClient(ConnectionInfo connectionInfo)
Creates a GatewayClient that represents a single network interface.
|
GatewayClient(ConnectionInfo connectionInfo,
DeviceEventHandler handler)
Creates a GatewayClient that represents a single network interface.
|
GatewayClient(ConnectionInfo connectionInfo,
DeviceEventHandler handler,
String configFilePath)
Creates a GatewayClient that represents a single network interface.
|
Modifier and Type | Method and Description |
---|---|
boolean |
abortUpgrade(ConnectionInfo connectionInfo)
Cancels a firmware upgrade process that is currently running.
|
boolean |
addDeviceEventHandler(DeviceEventHandler handler)
Allows a class to register itself to receive
DeviceEvent . |
CompletableFuture<NetworkInformation> |
createNetwork(ConnectionInfo c)
Forms a network on the specified network interface.
|
CompletableFuture<NetworkInformation> |
createNetwork(ConnectionInfo c,
List<Integer> channels)
Forms a network on the specific network interface, attempting to form on the
best channel from the provided list of channels.
|
boolean |
deregisterOtaFile(String otaFilePath,
ConnectionInfo connectionInfo)
Deregisters an OTA file on the gateway if an OTA server exists.
|
void |
deregisterOtaProgressHandler(Consumer<UpgradeProgress> callback)
Deregisters the OTA upgrade progress handler, which stops displaying the progress of the upgrade.
|
CompletableFuture<NetworkInformation> |
dissolveNetwork(ConnectionInfo c)
Dissolves the network on the specified network interface.
|
static String |
getApiVersion()
Get the API version number.
|
Collection<ConnectionInfo> |
getConnectionInfo()
Gets the list of connections that the GatewayClient knows about.
|
Device |
getDevice(String id)
Gets the device with the corresponding id.
|
Collection<Device> |
getDevices()
Returns a collection of devices from all the networks that the
GatewayClient knows about. |
Collection<Device> |
getDevices(Predicate<Device> filter)
Returns a filtered collection of devices from all the networks that the
GatewayClient knows about. |
Collection<Device> |
getGatewayDevices()
Retrieves a collection of devices in the network that represents the network interface(i.e the
ConnectionInfo
that was passed upon the initialisation of the GatewayClient |
CompletableFuture<NetworkInformation> |
getNetworkInfo(ConnectionInfo c)
Returns the network information (status, channel, and id) of the specified network interface.
|
List<String> |
getRegisteredOtaFiles(ConnectionInfo connectionInfo)
Gets a list of the OTA files registered on the OTA Server if an OTA server exists.
|
boolean |
isShutdown() |
boolean |
registerOtaFile(String otaFilePath,
ConnectionInfo connectionInfo)
Registers an OTA file on the gateway if an OTA server exists.
|
void |
registerOtaProgressHandler(Consumer<UpgradeProgress> callback)
Registers the OTA upgrade progress handler, which displays the progress when an upgrade starts.
|
boolean |
removeAllDeviceEventHandlers()
Removes all registered handlers.
|
boolean |
removeDeviceEventHandler(DeviceEventHandler handler)
Removes a previously registered handler.
|
CompletableFuture<NetworkInformation> |
scanForDevices(ConnectionInfo c,
int duration)
Opens the permit join window on the specified network interface so that devices
who are in pairing mode can join the network.
|
CompletableFuture<String> |
sendProtocolMessage(ConnectionInfo connection,
String json)
Sends a protocol-specific message (i.e.
|
boolean |
shutdown()
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, etc.
|
CompletableFuture<UpgradeStatus> |
upgradeFirmware(ConnectionInfo connectionInfo,
File upgradeFile,
ResultConsumer<UpgradeProgress> callback)
Performs a firmware upgrade of the module with the given
connectionInfo and
serialUpgradeFile . |
public GatewayClient(ConnectionInfo connectionInfo) throws GatewayConnectionException
connectionInfo
- An object that represents the network interface to try to connect to.GatewayConnectionException
- If there were any problems connecting to, or configuring,
the specified network interface represented by the ConnectionInfo object.public GatewayClient(ConnectionInfo connectionInfo, DeviceEventHandler handler) throws GatewayConnectionException
connectionInfo
- An object that represents the network interface to try to connect to.handler
- A DeviceEventHandler that will be called when
DeviceEvent
occurs.GatewayConnectionException
- If there were any problems connecting to, or configuring,
the specified network interface represented by the ConnectionInfo object.public GatewayClient(ConnectionInfo connectionInfo, DeviceEventHandler handler, String configFilePath) throws GatewayConnectionException
connectionInfo
- An object that represents the network interface to try to connect to.handler
- A DeviceEventHandler that will be called whenconfigFilePath
- the location of a file that should be used to configure the network
interface represented by connectionInfo.
DeviceEvent
occurs.GatewayConnectionException
- If there were any problems connecting to, or configuring,
the specified network interface represented by the ConnectionInfo object.public boolean shutdown()
This is a blocking call and is not thread-safe.
public boolean isShutdown()
public boolean addDeviceEventHandler(DeviceEventHandler handler)
DeviceEvent
.
If a handler is already registered, calling this method will have no effect (i.e. duplicate handlers are ignored).
The handler is called from a dedicated thread.
handler
- An instance of a class that implements the DeviceEventHandler interface.public boolean removeDeviceEventHandler(DeviceEventHandler handler)
handler
- The instance of the class that was previously registered with the GatewayClient
.public boolean removeAllDeviceEventHandlers()
public Collection<ConnectionInfo> getConnectionInfo()
public Collection<Device> getDevices(Predicate<Device> filter)
GatewayClient
knows about.
The method takes a Predicate
which is used to filter the device list.
Example:
gatewayClient.listDevices( device -> device.getID().equalsIgnoreCase(idStr) );
filter
- A Predicate that can be used to query for certain types of devices.public Collection<Device> getDevices()
GatewayClient
knows about.GatewayClient
knows about.public Collection<Device> getGatewayDevices()
ConnectionInfo
that was passed upon the initialisation of the GatewayClient
GatewayClient
knows aboutpublic Device getDevice(String id)
id
- of the devicepublic CompletableFuture<UpgradeStatus> upgradeFirmware(ConnectionInfo connectionInfo, File upgradeFile, ResultConsumer<UpgradeProgress> callback)
connectionInfo
and
serialUpgradeFile
.
Results are transmitted via the callback
. The callback
is called
more than once until completion or if an error occurs. The callback is called from a separate
thread.
Note: 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.onError(Throwable)
will be called with an error, and the CompletableFuture
shall return a UpgradeStatus.FAILED
immediately.
Note: This method is not thread-safe.
connectionInfo
- Connection information of the Module being upgraded.upgradeFile
- The file to upgrade the Module with.callback
- Result, progress, and errors are propagated here.CompletableFuture<Status>
where CompletableFuture.get()
and
CompletableFuture.get(long, TimeUnit)
return a UpgradeStatus
.
The UpgradeStatus.FAILED
almost always means something went wrong
with the serial upgrade process.IllegalArgumentException
- If connectionInfo is null, upgradeFile is null or is a directoryResultConsumer
,
CompletableFuture
public boolean abortUpgrade(ConnectionInfo connectionInfo)
connectionInfo
- The device's ConnectionInfo
that is currently performing a firmware upgradetrue
if the abort signal was sent, false
otherwise, or if no upgrade process
is currently performing on that devicepublic CompletableFuture<NetworkInformation> getNetworkInfo(ConnectionInfo c)
c
- ConnectionInfo of the specified network interface.public CompletableFuture<NetworkInformation> createNetwork(ConnectionInfo c)
c
- ConnectionInfo of the specified network interface.public CompletableFuture<NetworkInformation> createNetwork(ConnectionInfo c, List<Integer> channels)
c
- ConnectionInfo of the specified network interfacechannels
- List of channels that the network can possibly be formed on. Values must within 11 to 26.IllegalArgumentException
- if channel value is not within 11 to 26, e.g 10, 27 will result in an
IllegalArgumentExceptionpublic CompletableFuture<NetworkInformation> dissolveNetwork(ConnectionInfo c)
c
- ConnectionInfo of the specified network interface.public CompletableFuture<NetworkInformation> scanForDevices(ConnectionInfo c, int duration)
c
- ConnectionInfo of the specified network interface.duration
- The amount of time, between 0 and 254 seconds, to open the window for.public static String getApiVersion()
public CompletableFuture<String> sendProtocolMessage(ConnectionInfo connection, String json) throws InvalidInputException
connection
- The network interface from which to send the protocol specific message.json
- JSON String of the messageCompletableFuture
where the result is a json string containing the protocol-specific responseInvalidInputException
- if json is malformedCompletionException
- if something erroneous has happened during computationpublic boolean registerOtaFile(String otaFilePath, ConnectionInfo connectionInfo)
otaFilePath
- The absolute file path string to the OTA file.connectionInfo
- Connection info that represents underlying network interface.true
if registering of the OTA file was successful; false
otherwise.public List<String> getRegisteredOtaFiles(ConnectionInfo connectionInfo)
connectionInfo
- Connection info that represents underlying network interface.public boolean deregisterOtaFile(String otaFilePath, ConnectionInfo connectionInfo)
otaFilePath
- The absolute file path string to the OTA file.connectionInfo
- Connection info that represents underlying network interface.true
if deregistering of the OTA file was successful; false
otherwise.public void registerOtaProgressHandler(Consumer<UpgradeProgress> callback) throws NullPointerException
callback
- Upgrade progress consumer, which must not be null.NullPointerException
- if supplied callback
parameter is null.public void deregisterOtaProgressHandler(Consumer<UpgradeProgress> callback) throws NullPointerException
callback
- Upgrade progress consumer, which must not be null.NullPointerException
- if supplied callback
parameter is null.Copyright © 2020. All rights reserved.