Overview
The Device class represents a Device on the network.
Certain device types will have their own specific device class implementations (such as LightDevice). All other devices will be an instance of the DefaultDevice, which implements the methods in the Device class interface.
Sub-Classes
Device Identification API
getID()
Usage
Gets the unique identifier for this device.
Parameters
None.
Returns
| Return Type | Description |
|---|---|
| String | A unique identifier for the device. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"),
(event) -> {
System.out.println("Device Event: " + event.getStatus());
Device d = event.getDevice();
System.out.println("Device: " + d.getID());
}
);
getDeviceType()
Usage
Get the DeviceType associated with the Device. The DeviceType specifies the device at a logical level (i.e. Light, Thermostat, etc).
Typically, sub-classes of the Device class will have a member called "DEVICE_TYPE" which identifies the device, and this method will return that member.
Parameters
None.
Returns
| Return Type | Description |
|---|---|
| DeviceType | A class describing the device at a logical level (i.e. a light, thermostat, etc). |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... // use DeviceType to filter for all the lights on the network Collection<Device> lights = gw.listDevices( d -> d.getDeviceType().equals(LightDevice.DEVICE_TYPE) ); ...
Properties API
getProperties()
Usage
Gets all currently known Property objects associated with this device. Only sub-classes of Device will have Property objects. Other devices must use the getRawProtocolProperties() method.
The first call to this function is blocking, and will go out to the underlying network to retrieve all the values for the remote device.
Subsequent calls will return the last cached value for that Property, without going out to the underlying network to obtain it. Cached values can change when they are read, written, or reported.
Parameters
None.
Returns
| Return Type | Description |
|---|---|
| Result | A Result object which contains a Collection of Property objects containing the most recently known value for that Property, as well as a status indicating whether a retry is required (for example, because not all properties were discovered during the first call). This allows users to implement their own retry-policy as needed. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device d = gw.getDevice(id);
final Collection<Property> properties = d.getProperties();
for (Property p : properties) {
System.out.println("name: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
}
getProperty(String propertyName)
Usage
Gets the Property with the associated propertyName.
This call will request the latest value of the Property from the device on the network.
Parameters
| Name | Type | Description |
|---|---|---|
| propertyName | String | The name associated with the Property. For example, the name returned from Property.getName(). |
Returns
| Return Type | Description |
|---|---|
| Device.PropertyCommand | Represents a request to read or write a Property. Contains a CompletableFuture<Property> and a cached Property. The CompletableFuture<Property> represents a request over the network to read/write the Property. Will be null if Property doesn't exist, and will return exceptionally on any other errors. The cached Property contains the last known value, or empty if none/doesn't exist. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device d = gw.getDevice(id);
final CompletableFuture<Property> p = d.getProperty(propertyName).getFuture();
try {
final Property fProp = p.get(5, TimeUnit.SECONDS);
System.out.println("name: " + fProp.getName() + ", value: " + fProp.getValue());
} catch (InterruptedException | ExecutionException | TimeoutException e) {}
updateProperty(Property property)
Usage
Updates the Property associated with this device.
Parameters
| Name | Type | Description |
|---|---|---|
| property | Property | An object containing the name and value of the Property to update. |
Returns
| Return Type | Description |
|---|---|
| Device.PropertyCommand | Represents a request to read or write a Property. Contains a CompletableFuture<Property> and a cached Property. The CompletableFuture<Property> represents a request over the network to read/write the Property. Will be null if Property doesn't exist, and will return exceptionally on any other errors. The cached Property contains the last known value, or empty if none/doesn't exist. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// turn a light device on
final Device d = gw.getDevice(id);
Property property = new Property("OnOff, "boolean", "true");
d.updateProperty(property).getFuture().whenComplete( (result, throwable) -> {
if (throwable != null) {
System.out.println("error: " + throwable.getMessage());
System.out.println("suggestion: ensure you are forming the correct JSON request, with property key:value pairs");
} else if (result != null) {
System.out.println("result: " + result.getValue());
}
});
getRawProtocolProperties()
Usage
Get the properties of the device in terms of the underlying protocol.
For example, for zigbee devices, this will return clusters and attributes.
Parameters
None.
Returns
| Return Type | Description |
|---|---|
| Collection<Property> | A Collection of Property objects for the device. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device d = gw.getDevice(id);
final Collection<Property> properties = d.getRawProtocolProperties();
for (Property p : properties) {
System.out.println("name: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
}
Binding and Attribute Reporting API
bindDevice(String destinationDeviceId, String propertyToBind)
Usage
Creates a binding between this device (the source) and a destination device, on the specified Property.
A binding allows Devices to be aware of each other, for the purposes of sending data or commands between themselves based on their own internal logic. A good example of this is binding a Light Switch to a Light. Once a binding exists, the Light Switch will automatically send on/off commands to any bound Lights.
Note that if the Properties of a Device haven't yet been discovered, the bind will fail. It is assumed that the properties of a Device have been discovered (using a call like getProperties for example) before being able to bind to a specific Property.
Parameters
| Name | Type | Description |
|---|---|---|
| destinationDeviceId | String | The ID of the destination device that we want to bind to. |
| propertyToBind | String | The name of the Property to bind on. For example, OnOff. |
Returns
| Return Type | Description |
|---|---|
| Optional<CommandData> | An optional CommandData object, which contains a CompletableFuture<String> of the future result, as well as a cached version of the result since the last call. The result can contain error codes or messages. Usually, it will return a simple "success" if successful. |
Throws
InvalidInputException if the supplied parameters are incorrect, refer to objects that don't exist or properties that can't be bound or don't exist because a discovery has not taken place yet.
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device sourceDevice = gw.getDevice(sourceId);
sourceDevice.bindDevice(destinationId, property)
.get()
.getCommandResult()
.whenComplete((result, error) -> {
if (error != null) {
System.out.println("error calling bind: " + error.getMessage());
} else {
System.out.println("bind device result: " + result);
}
});
unbindDevice(String destinationDeviceId, String propertyToBind)
Usage
Removes the binding between this device (the source) and the destination device.
Parameters
| Name | Type | Description |
|---|---|---|
| destinationDeviceId | String | The ID of the destination device that we want to bind to. |
| propertyToBind | String | The name of the Property to bind on. For example, OnOff. |
Returns
| Return Type | Description |
|---|---|
| Optional<CommandData> | An optional CommandData object, which contains a CompletableFuture<String> of the future result, as well as a cached version of the result since the last call. The result can contain error codes or messages. Usually, it will return a simple "success" if successful. |
Throws
InvalidInputException if the supplied parameters are incorrect, refer to objects that don't exist or properties that can't be bound or don't exist because a discovery has not taken place yet.
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device sourceDevice = gw.getDevice(sourceId);
sourceDevice.unbindDevice(destinationId, property)
.get()
.getCommandResult()
.whenComplete((result, error) -> {
if (error != null) {
System.out.println("error calling unbind: " + error.getMessage());
} else {
System.out.println("unbind device result: " + result);
}
});
configureReporting(String propertyToBind, List<Parameter> parameters)
Usage
Configures reporting a specified Property on this device. Reports are generally sent to the destination device that has a binding (see bind() method) on the same Property being configured using the configureReporting() method.
Parameters
| Name | Type | Description |
|---|---|---|
| propertyToBind | String | The name of the Property to bind on. For example, OnOff. |
| parameters | List<Parameter> | A list of Parameter objects representing various configuration options. See below for a list of configuration parameters that are currently supported. |
Configuration Parameters:
...
Returns
| Return Type | Description |
|---|---|
| Optional<CommandData> | An optional CommandData object, which contains a CompletableFuture<String> of the future result, as well as a cached version of the result since the last call. The result can contain error codes or messages. Usually, it will return a simple "success" if successful. |
Throws
InvalidInputException if the supplied parameters are incorrect, or refer to properties or configuration parameters that don't exist or are malformed, etc.
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device device = gw.getDevice(id);
List<Parameter> onOffParams = new ArrayList<>();
onOffParams.add(new Parameter(ConfigureReportingParameter.DIRECTION, "0x00"));
onOffParams.add(new Parameter(ConfigureReportingParameter.MIN_REPORTING_INTERVAL, "0x0000"));
onOffParams.add(new Parameter(ConfigureReportingParameter.MAX_REPORTING_INTERVAL, "0x012C")); // 5 minutes
try {
CompletableFuture<String> futureResult = device.configureReporting("OnOff", onOffParams).get().getCommandResult();
String result = futureResult.get(30, TimeUnit.SECONDS);
System.out.println("result: " + result);
} catch (Exception e) {
throw new CompletionException(e);
}
enableDefaultReporting(String propertyToBind, List<Parameter> parameters)
Usage
Configures the Device to report to the GatewayClient whenever there are changes to its properties.
Depending on the Device type (i.e. LightDevice, ThermostatDevice), this method will configure different attributes for reporting. Calling this method on the DefaultDevice will have no effect.
Parameters
None.
Returns
| Return Type | Description |
|---|---|
| CompletableFuture<String> | A CompletableFuture<String> that will contain the result of the call. The result can contain error codes or messages. Usually, it will return a simple "success" if successful. |
Throws
IllegalStateException if the function is called before the Device Properties have been discovered (i.e. through getProperties()).
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device device = gw.getDevice(idStr);
try {
final String result = device.enableDefaultReporting().get(30, TimeUnit.SECONDS);
System.out.println("Status for command: " + result);
} catch (IllegalStateException | InterruptedException | ExecutionException | TimeoutException e) {
System.out.println(e.getMessage());
}
Listeners API
addPropertyUpdateListener(Consumer<Property> listener)
Usage
Adds a Property update listener that is triggered when any Property on a Device changes.
Parameters
| Name | Type | Description |
|---|---|---|
| listener | Consumer<Property> | An instance or lambda that implements the Consumer<Property> interface. |
Returns
None.
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device d = gw.getDevice(id);
d.addPropertyUpdateListener(p -> {
System.out.println("Property update triggered for device " + d.getID());
System.out.println("Property: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
});
removePropertyUpdateListener(Consumer<Property> listener)
Usage
Removes a previously added listener.
Parameters
| Name | Type | Description |
|---|---|---|
| listener | Consumer<Property> | An instance that implements the Consumer<Property> interface. |
Returns
None.
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... gw.getDevice(id).removePropertyUpdateListener(myPropertyUpdateListener);
removeAllPropertyUpdateListeners()
Usage
Removes all listeners that have been previously registered.
Parameters
None.
Returns
None.
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... gw.getDevice(id).removeAllPropertyUpdateListeners();
Network API
leaveNetwork()
Usage
Request the device to leave the network.
Parameters
None.
Returns
None.
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0")); ... final Device d = gw.getDevice(id); d.leaveNetwork();