Device
- 1 Overview
- 2 Sub-Classes
- 3 Device Identification API
- 4 Properties API
- 5 Binding and Attribute Reporting API
- 6 Handlers API
- 6.1 addPropertyUpdateHandler(BiConsumer<Device, Property> handler)
- 6.2 removePropertyUpdateHandler(BiConsumer<Device, Property> handler)
- 6.3 removeAllPropertyUpdateHandlers()
- 6.4 addProtocolHandler(BiConsumer<Device, String> handler)
- 6.5 removeProtocolHandler(BiConsumer<Device, String> handler)
- 6.6 removeAllProtocolHandlers()
- 7 Network API
- 8 Upgrade API
Overview
The Device class represents a Device on the network, in a protocol agnostic way.
Specific devices will have their own implementations of the methods defined in the Device class (such as ZigbeeDevice and its subclasses, LightDevice, ThermostatDevice, etc); however, they will all share the same API defined in the Device class.
The intent is that developers should use the protocol-agnostic methods in the Device class for all their device interactions, and only use the protocol-specific methods in subclasses (such as ZigbeeDevice) if they require custom behaviours that haven't been specified or implemented in the Device class.
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. dimmable light, thermostat, etc), as well as a categorical level (i.e. lighting, hvac, etc).
Parameters
None.
Returns
Return Type | Description |
|---|---|
DeviceType | A class containing a "type" field to describe the device at a logical level (i.e. dimmable light), as well as a "category" field to describe its group (i.e. lighting). See the "Zigbee Device Descriptors" section in the Zigbee Specification References document for more details about what these identifiers would look like for zigbee devices. |
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().getType().equals("dimmable light") );
...getConnectedGatewayId()
Usage
Get the unique identifier of the Gateway that this Device is connected to.
The ID returned by this method can be used in any API that requires an identifier returned by Device.getID().
Parameters
None.
Returns
Return Type | Description |
|---|---|
Optional<String> | The unique identifier for the Gateway that this Device is connected to. The Optional will be empty if there are errors. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gw.getDevice(id);
String gatewayId = device.getConnectedGatewayId().get();
device.bindDevice(gatewayId, "zoneStatus");
...getManufacturerName()
Usage
Gets the Manufacturer Name associated with the Device. This is a device-dependant value and is usually determined at the time the device was manufactured.
Will result in a request over the network the first time it's called; however, subsequent calls will return a cached value.
This is a non-blocking call.
Parameters
None.
Returns
Return Type | Description |
|---|---|
CompletableFuture<String> | A CompletableFuture containing a String with the result. Will complete exceptionally on any errors with a RequestException. The RequestException will contain an error message and code. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gw.getDevice(id);
device.getManufacturerName().thenAccept( name -> System.out.println(name) );
...getHardwareVersion()
Usage
Gets the Hardware Version associated with the Device. This is a device-dependant value and is usually determined at the time the device was manufactured.
Will result in a request over the network the first time it's called; however, subsequent calls will return a cached value.
This is a non-blocking call.
Parameters
None.
Returns
Return Type | Description |
|---|---|
CompletableFuture<String> | A CompletableFuture containing a String with the result. Will complete exceptionally on any errors with a RequestException. The RequestException will contain an error message and code. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gw.getDevice(id);
device.getHardwareVersion().thenAccept( version -> System.out.println(version) );
...getModelNumber()
Usage
Gets the Model Number associated with the Device. This is a device-dependant value and is usually determined at the time the device was manufactured.
Will result in a request over the network the first time it's called; however, subsequent calls will return a cached value.
This is a non-blocking call.
Parameters
None.
Returns
Return Type | Description |
|---|---|
CompletableFuture<String> | A CompletableFuture containing a String with the result. Will complete exceptionally on any errors with a RequestException. The RequestException will contain an error message and code. |
Examples
GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gw.getDevice(id);
device.getModelNumber().thenAccept( modelNum -> System.out.println(modelNum) );
...Properties API
getProperties()
Usage
Gets all known Properties associated with this device. If there are no known Properties on the Device (for example, because they haven't yet been read via a call to "getProperty", or discovered via a call to "discoverAllProperties", or otherwise reported to the Gateway via a reporting mechanism, etc), then this method will return an empty Collection of Property objects.
Every call to this function will go out to the underlying network to retrieve the latest values for all known Properties on the remote device.
This is a non-blocking call which returns a CompletableFuture of a Collection of Property objects.
Parameters
None.
Returns
Return Type | Description |
|---|---|
CompletableFuture<Collection<Property>> | A CompletableFuture which contains a Collection of Property objects containing the most recently known value for that Property. The CompletableFuture will return exceptionally if not all properties could be obtained, or if a retry is required. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
CompletableFuture<Collection<Property>> properties = device.getProperties();
// do some extra (asynchronous) handling on the properties, once they've been discovered.
properties.thenAccept( collection -> {
// This code will be called from a thread managed by gateway api.
// We should avoid blocking code in this section.
for (Property p : collection) {
System.out.println(p.toString());
}
});
...
// one could also block on the CompletableFuture until it returns
Collection<Property> c = properties.get(30, TimeUnit.SECONDS); // wait (block) for up to 30 seconds to get the Collection of Property objects backgetCachedProperties()
Usage
Gets all last known (cached) Property objects associated with this device. Cached values are updated on reads, writes, and attribute reports.
Calling this function will not result in a request going out over the network.
Returns a Collection of Property objects. The returned collection will be empty if there are no known Properties on the Device because they haven't yet been read or discovered (i.e. no previous calls to getProperty(String) or discoverAllProperties() has been made).
Parameters
None.
Returns
Return Type | Description |
|---|---|
Collection<Property> | A Collection of Property objects containing the last known value for that Property. Will be empty if no device discovery has taken place (i.e. no previous calls to getProperties() have been made) |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
Collection<Property> collection = device.getCachedProperties();
for (Property p : collection) {
System.out.println(p.toString());
}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.
This is a non-blocking call which returns a CompletableFuture of the requested Property.
Parameters
Name | Type | Description |
|---|---|---|
propertyName | String | The name associated with the Property. For example, for zigbee devices, it could be any attribute name from the Zigbee Attribute Names page. |
Returns
Return Type | Description |
|---|---|
CompletableFuture<Property> | The CompletableFuture<Property> represents a request over the network to read/write the Property. Will return exceptionally on any and all errors. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
CompletableFuture<Property> futureProperty = device.getProperty(propertyName);
// This is an example of blocking on the future and waiting for a result.
Property property = futureProperty.get(30, TimeUnit.SECONDS);
System.out.println(p.toString());
// One could also provide code that will be called asynchronously once the CompletableFuture has finished
futureProperty.thenAccept( p -> System.out.println(p.toString()) );getCachedProperty(String propertyName)
Usage
Gets the Property with the associated propertyName.
This call will return the last known (cached) value of the Property. Cached values are updated on reads, writes, and attribute reports.
Returns an Optional of the requested Property. The Optional will be empty if the cached Property doesn't exist.
Parameters
Name | Type | Description |
|---|---|---|
propertyName | String | The name associated with the Property. For example, for zigbee devices, it could be any attribute name from the Zigbee Attribute Names page. |
Returns
Return Type | Description |
|---|---|
Optional<Property> | The Optional<Property> represents the Property. Will be empty if the Property doesn't exist or hasn't yet been discovered (i.e. from a previous call to getProperty / getProperties()) |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
Optional<Property> optional = device.getCachedProperty(propertyName);
if (optional.isPresent()) {
Property p = optional.get();
System.out.println(p.toString());
}getProtocolProperties()
Usage
Gets all known protocol properties from the device on the network (i.e. if it's a zigbee device, it will return the known zigbee attributes on the Device). If there are no known protocol properties on the Device (for example, because they haven't yet been read or discovered), then this method will return an empty Collection of Property objects.
Every call to this function will go out to the underlying network to retrieve all known Properties for the remote device.
This is a non-blocking call which returns a CompletableFuture of a Collection of Property objects.
Parameters
None.
Returns
Return Type | Description |
|---|---|
CompletableFuture<Collection<Property>> | A CompletableFuture which contains a Collection of Property objects containing the most recently known value for that Property. The CompletableFuture will return exceptionally if not all properties could be obtained, or if a retry is required. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
CompletableFuture<Collection<Property>> properties = device.getProtocolProperties();
// do some extra (asynchronous) handling on the properties, once they've been discovered.
properties.thenAccept( collection -> {
// This code will be called from a thread managed by gateway api.
// We should avoid blocking code in this section.
for (Property p : collection) {
System.out.println(p.toString());
}
});
...
// one could also block on the CompletableFuture until it returns
Collection<Property> c = properties.get(30, TimeUnit.SECONDS); // wait (block) for up to 30 seconds to get the Collect of Property objects backgetCachedProtocolProperties()
Usage
Gets all last known (cached) protocol level properties associated with this device. Cached values are updated on writes, reads, and attribute reports.
Calling this function will not result in a request going out over the network.
Returns a Collection of Property objects. The returned collection will be empty if no device discovery has taken place (i.e. no previous calls to getProperties() / getProtocolProperties() have been made).
Parameters
None.
Returns
Return Type | Description |
|---|---|
Collection<Property> | A Collection of Property objects containing the last known value for that Property. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
Collection<Property> properties = d.getCachedProtocolProperties();
for (Property p : properties) {
System.out.println(p.toString);
}discoverAllProperties()
Usage
Gets all Property objects, and their values, that exist on the remote device. Note that this is a potentially long-running call. See below for more information.
A request to obtain all the Property values that exist on the remote device will be sent out over the underlying network, and will result in a PropertyUpdate handler being called if the value is different than the last time the Property was read, and a handler exists for this device.
Returns a CompletableFuture of a Collection of Property objects. Once a call to this method has been made, the list of Properties and their values will be cached, and individual Properties can be accessed or refreshed using the getProperty, getCachedProperty, getProperties, getCachedProperties, and updateProperty methods.
The CompletableFuture will complete exceptionally on all errors.
Note that this is potentially a long-running call, because the remote device may have many properties, or may be a sleepy battery powered device which responds to requests over long intervals in order to preserve battery power. This call is typically not used in production applications, as system integrators typically know in advance which properties they want to interact with, and will simply use the "getProperty" and "updateProperty" methods to interact with them directly, without having to discover all the properties on the device.
Parameters
None.
Returns
Return Type | Description |
|---|---|
CompletableFuture<Collection<Property>> | A CompletableFuture of a Collection of Property objects. Will compete exceptionally on any errors. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
CompletableFuture<Collection<Property>> properties = device.discoverAllProperties();
// asynchronously print out the values once discovery is complete.
properties.thenAccept( collection -> {
for (Property p : collection) {
System.out.println("Discovered: " + p.toString());
}
});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.PropertyCommandData | 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());
} else if (result != null) {
System.out.println("result: " + result.getValue());
}
});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 |
|---|---|
CompletableFuture<String> | A CompletableFuture<String> of the future result. 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"));
...
Device sourceDevice = gw.getDevice(sourceId);
String destinationDeviceId = sourceDevice.getConnectedGatewayId().get();
sourceDevice.bindDevice(destinationDeviceId, property)
.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 |
|---|---|
CompletableFuture<String> | A CompletableFuture<String> of the future result. 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"));
...
Device sourceDevice = gw.getDevice(sourceId);
String destinationDeviceId = sourceDevice.getConnectedGatewayId().get();
sourceDevice.unbindDevice(destinationDeviceId, property)
.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.
Note: for reporting to work for zigbee devices, you must creating a binding between the remote Device and the GatewayClient (by using the bind() API first).
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:
Configuration parameters vary depending on the "DIRECTION" parameter. Currently, only one value of the DIRECTION parameter is supported:
Name | Value | Description |
|---|---|---|
ConfigureReportingParameter.DIRECTION | 0x00 | The receiver of the command should send reports to each destination, as resolved by the bindings for the cluster hosting the properties to be reported. |
ConfigureReportingParameter.MIN_REPORTING_INTERVAL | 0x0000 - 0xFFFF | The minimum interval, in seconds, between issuing reports of the specified property. |
ConfigureReportingParameter.MAX_REPORTING_INTERVAL | 0x0000 - 0xFFFF | The maximum interval, in seconds, between issuing reports of the specified property. |
ConfigureReportingParameter.REPORTABLE_CHANGE | Optional | The minimum change to the property that will result in a report being issued. This field is of variable length. For attributes with 'analog' data type (things that can be represented by integers, floats, etc.) the field has the same data type as the attribute. Discrete data types (such as boolean, arrays, strings, etc) can omit this field. |
Returns
Return Type | Description |
|---|---|
CompletableFuture<String> | A CompletableFuture<String> of the future result. 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);
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());
}Handlers API
addPropertyUpdateHandler(BiConsumer<Device, Property> handler)
Usage
Adds a Property update listener that is triggered when any Property on a Device changes.
Will reject duplicates handler instances.
Parameters
Name | Type | Description |
|---|---|---|
handler | BiConsumer<Device, Property> | An instance or lambda that implements the BiConsumer<Device, Property> interface. |
Returns
Return Type | Description |
|---|---|
boolean | Returns true if the handler was added to the list; false otherwise. |
Examples
public class SamplePropertyHandler implements BiConsumer<Device, Property> {
@Override
public void accept(Device device, Property property) {
// This method gets called whenever a Property on a device changes.
// By default, client callbacks are called from a single thread managed by gateway api.
// Therefore, avoid writing blocking code in this method, or other client callbacks
// (such as DeviceEventHandlers, or ProtocolHandlers) may be blocked.
System.out.println("Property update triggered for device: " + device.getID());
System.out.println(p.toString());
}
...
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
Device device = gateway.getDevice(id);
// example of supplying a class that implements the BiConsumer<Device, Property> interface
device.addPropertyUpdateHandler(new SamplePropertyHandler());
// example of a supplying a lambda
d.addPropertyUpdateListener(p -> {
System.out.println("lambda property update triggered for device: " + d.getID());
System.out.println(p.toString());
});removePropertyUpdateHandler(BiConsumer<Device, Property> handler)
Usage
Removes a previously added handler.
Parameters
Name | Type | Description |
|---|---|---|
handler | BiConsumer<Device, Property> | An instance that implements the BiConsumer<Device, Property> interface. |
Returns
Return Type | Description |
|---|---|
boolean | Returns true if the handler was removed; false otherwise. |
Examples
GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
SamplePropertyUpdateHandler handler = new SamplePropertyUpdateHandler();
gateway.getDevice(id).addPropertyUpdateHandler(handler);
...
// do stuff
...
gateway.getDevice(id).removePropertyUpdateHandler(handler);