Overview
The GatewayClient represents a connection to a network interface, such as a zigbee module. It allows a user to query for, and interact with, remote network devices without knowing anything about the underlying network or communication protocols.
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 Connection Info API
GatewayClient(ConnectionInfo)
Usage
Creates a GatewayClient object that represents a single network interface.
Will attempt to automatically form a network on the given interface.
Parameters
| Type | Description |
|---|---|
| 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.
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
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
GatewayClient(ConnectionInfo, DeviceEventListener)
Usage
Creates a GatewayClient object that represents a single network interface, with an attached DeviceEventListener that will be called when DeviceEvents are received.
Parameters
| Type | Description |
|---|---|
| ConnectionInfo | Represents a network interface that the GatewayClient can connect to. |
| 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.
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
// Example of a lambda implementation of the DeviceEventListener parameter.
// 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"),
(event) -> {
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
| Return Type | Description |
|---|---|
| Boolean | True if the system shut down gracefully; false otherwise. |
Example
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
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
for (ConnectionInfo c : gw.getConnectionInfo()) {
System.out.println("Connected to port: " + c.getValue());
}
Listeners API
addDeviceEventListener(DeviceEventListener)
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
| Type | Description |
|---|---|
| DeviceEventListener | An instance of a class that implements the DeviceEventListener interface (or a lambda that does the same). |
Returns
None.
Example
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)
Usage
Removes a previously registered listener.
Parameters
| Type | Description |
|---|---|
| DeviceEventListener | An instance of a class that implements the DeviceEventListener interface (or a lambda that does the same). |
Returns
None.
Example
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
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... gw.removeAllDeviceEventListeners();
Devices API
listDevices(Predicate<Device>)
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
| Type | Description |
|---|---|
| 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
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
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... Collection<Device> devices = gw.listDevices();
getDevice(String)
Usage
Gets the device with the corresponding id.
Assumes that id is unique, and there should only be one device per id.
* * @param id of the device * @return
Parameters
| Type | Description |
|---|---|
| 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
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device d = gw.getDevice("0123456789");