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(Collection<ConnectionInfo> connectionInfoList,
DeviceEventHandler handler)
Creates a GatewayClient that represents an aggregate of many network interfaces, each
represented by its own ConnectionInfo object.
|
GatewayClient(Collection<ConnectionInfo> connectionInfoList,
DeviceEventHandler handler,
String configFilePath)
Creates a GatewayClient that represents an aggregate of many network interfaces, each
represented by its own ConnectionInfo object.
|
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 . |
Optional<Group> |
createGroup(int groupID,
String groupName)
|
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 |
deregisterAllGroupEventHandler()
Deregister all registered groupEventHandler.
|
boolean |
deregisterGroupEventHandler(GroupEventHandler groupEventHandler)
Removes a previously registered groupEventHandler.
|
boolean |
deregisterOtaFile(String otaFilePath,
ConnectionInfo connectionInfo)
Deregisters an OTA file on the gateway if an OTA server exists.
|
boolean |
deregisterOtaProgressHandler(Consumer<UpgradeProgress> callback)
Deregisters the OTA upgrade progress handler, which stops displaying the progress of the upgrade.
|
boolean |
deregisterReceivedZigBeeMessageListener(ConnectionInfo connectionInfo,
Consumer<ZigBeeFrame> listener)
De-registers a sent frame listener
|
boolean |
deregisterSendZigBeeMessageListener(ConnectionInfo connectionInfo,
Consumer<ZigBeeFrame> listener)
De-registers a sent frame listener
|
CompletableFuture<NetworkInformation> |
dissolveNetwork(ConnectionInfo c)
Dissolves the network on the specified network interface.
|
CompletableFuture<Collection<Group>> |
getAllGroups()
Get all
Group objects. |
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 |
Optional<Group> |
getGroup(int id)
Get the
Group object with the associated id . |
InternalOtaHandler |
getInternalOtaHandler() |
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 |
registerGroupEventHandler(GroupEventHandler groupEventHandler)
Allows a class to register itself to receive
GroupEvent . |
boolean |
registerOtaFile(String otaFilePath,
ConnectionInfo connectionInfo)
Registers an OTA file on the gateway if an OTA server exists.
|
boolean |
registerOtaProgressHandler(Consumer<UpgradeProgress> callback)
Registers the OTA upgrade progress handler, which displays the progress when an upgrade starts.
|
boolean |
registerReceivedZigBeeMessageListener(ConnectionInfo connectionInfo,
Consumer<ZigBeeFrame> listener)
Registers a received frame listener
|
boolean |
registerSendZigBeeMessageListener(ConnectionInfo connectionInfo,
Consumer<ZigBeeFrame> listener)
Registers a frame listener to listen in on sent frames
|
boolean |
removeAllDeviceEventHandlers()
Removes all registered handlers.
|
boolean |
removeDeviceEventHandler(DeviceEventHandler handler)
Removes a previously registered handler.
|
CompletableFuture<Boolean> |
removeGroup(Group group)
Remove the
Group object. |
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.
|
byte |
sendFrame(ConnectionInfo connectionInfo,
ZigBeeFrame frame)
Sends a raw zigbee frame to the device
|
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 when a device is added or removedconfigFilePath
- 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 GatewayClient(Collection<ConnectionInfo> connectionInfoList, DeviceEventHandler handler) throws GatewayConnectionException
This constructor will attempt to connect to each network interface represented by its respective ConnectionInfo object.
The method will successfully return only if the client was able to connect to all network interfaces specified in the list.
connectionInfoList
- A list of ConnectionInfo objects each representing a network
interface.handler
- A DeviceEventHandler that wil lbe called when a device is added or removedGatewayConnectionException
- If there were any problems connecting to, or configuring,
any of the specified network interfaces represented by the ConnectionInfo object list.public GatewayClient(Collection<ConnectionInfo> connectionInfoList, DeviceEventHandler handler, String configFilePath) throws GatewayConnectionException
This constructor will attempt to connect to each network interface represented by its respective ConnectionInfo object.
The method will successfully return only if the client was able to connect to all network interfaces specified in the list.
connectionInfoList
- A list of ConnectionInfo objects each representing a network
interface.handler
- A DeviceEventHandler that wil lbe called when a device is added or removedconfigFilePath
- the location of a file that should be used to configure the network
interface represented by connectionInfo.GatewayConnectionException
- If there were any problems connecting to, or configuring,
any of the specified network interfaces represented by the ConnectionInfo object list.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 InternalOtaHandler getInternalOtaHandler()
public 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 OTA file path provided is valid; 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 boolean registerOtaProgressHandler(Consumer<UpgradeProgress> callback) throws NullPointerException
callback
- Upgrade progress consumer, which must not be null.true
OTA upgrade progress handler is registered successfully; false
otherwise.NullPointerException
- if supplied callback
parameter is null.public boolean deregisterOtaProgressHandler(Consumer<UpgradeProgress> callback) throws NullPointerException
callback
- Upgrade progress consumer, which must not be null.true
OTA upgrade progress handler is deregistered successfully; false
otherwise.NullPointerException
- if supplied callback
parameter is null.public Optional<Group> createGroup(int groupID, String groupName)
groupID
- Group ID.groupName
- Group name.public CompletableFuture<Boolean> removeGroup(Group group)
Group
object.
Note: The group will be removed if all devices are removed successfully from the group.
If one or more devices failed to be removed, the group will not be removed and it will contain only the failed
devices.group
- Group object to be removed.CompletableFuture
object. It will contain True if the group is removed successfully; false otherwise.public CompletableFuture<Collection<Group>> getAllGroups()
Group
objects.CompletableFuture
object. It will contain a Collection of Group objects if exists.public Optional<Group> getGroup(int id)
Group
object with the associated id
.id
- Group ID.public boolean registerGroupEventHandler(GroupEventHandler groupEventHandler)
GroupEvent
.
If a groupEventHandler is already registered, calling this method will have no effect (i.e. duplicate handlers are ignored).
The groupEventHandler is called from a dedicated thread.
groupEventHandler
- An instance of a class that implements the GroupEventHandler interface.public boolean deregisterGroupEventHandler(GroupEventHandler groupEventHandler)
groupEventHandler
- The instance of the class that was previously registered with the GatewayClient
.public boolean deregisterAllGroupEventHandler()
public byte sendFrame(ConnectionInfo connectionInfo, ZigBeeFrame frame)
connectionInfo
- The locally connected device connection information the client is listening in onframe
- ZigBee FrameIllegalArgumentException
- if passed in connectionInfo is invalidNullPointerException
- if connectionInfo, and frame is nullpublic boolean registerSendZigBeeMessageListener(ConnectionInfo connectionInfo, Consumer<ZigBeeFrame> listener)
connectionInfo
- The locally connected device connection information that the listener should listen onlistener
- the listener to listen in on a zigbee frametrue
if the listener has been successfully registered, false
otherwiseNullPointerException
- if info, and listener are nullpublic boolean deregisterSendZigBeeMessageListener(ConnectionInfo connectionInfo, Consumer<ZigBeeFrame> listener)
connectionInfo
- The locally connected device connection information the client is listening in onlistener
- the listener to listen for zigbee frame eventsTrue
if the listener has been successfully registered, false
otherwiseNullPointerException
- if info and listener are nullpublic boolean registerReceivedZigBeeMessageListener(ConnectionInfo connectionInfo, Consumer<ZigBeeFrame> listener)
connectionInfo
- The locally connected device connection information the client is listening in onlistener
- the listener to listen for zigbee frame eventsTrue
if the listener has been successfully registered, false
otherwiseNullPointerException
- if info and listener are nullpublic boolean deregisterReceivedZigBeeMessageListener(ConnectionInfo connectionInfo, Consumer<ZigBeeFrame> listener)
connectionInfo
- The locally connected device connection information the client is listening in onlistener
- the listener to listen for zigbee frame eventsTrue
if the listener has been successfully registered, false
otherwiseNullPointerException
- if info and listener are nullCopyright © 2021. All rights reserved.