...

Certain device types will have their own specific device class implementations (such as LightDevice). All other devices will be an instance of the DefaultDeviceGenericDevice, which implements the methods in the Device class interface.

...

getProperties()

Usage

Gets all currently known Property objects associated with this device. Only sub-classes of Device Not all devices will have Property objects . Other devices must use the getRawProtocolProperties() method.The first associated with them; however, all Devices will have underlying protocol-level properties that can be accessed via the getProtocolProperties() and getCachedProtocolProperties() methods.

The first call to this method will perform a discovery of all the attributes on the device.

Every 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.

This is a non-blocking call which returns a CompletableFuture of a Collection of Property objects.

Parameters

None.

Returns

Examples

GatewayClient gwgateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));

...

final Device ddevice = gwgateway.getDevice(id);
final Collection<Property>CompletableFuture<Collection<Property>> properties = ddevice.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

...

Returns

...

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

...

Returns

...

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

...

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

...

Returns

...

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

...

// 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("name: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
    }
});

...

// 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 back

getCachedProperties()

Usage

Gets all last known (cached) Property objects 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() have been made).

Parameters

None.

Returns

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("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. If no properties has been discovered so far, it will perform a discovery on all properties.

This is a non-blocking call which returns a CompletableFuture of the requested Property.

Parameters

Returns

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("name: " + property.getName() + ", value: " + property.getValue());

// One could also provide code that will be called asynchronously once the CompletableFuture has finished
futureProperty.thenAccept( p -> System.out.println("name: " + p.getName() + ", value: " + p.getValue()) );

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 writes, reads, and attribute reports.

Returns an Optional of the requested Property. The Optional will be empty if the cached Property doesn't exist.

Parameters

Returns

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("name: " + p.getName() + ", value: " + p.getValue());
}

getProtocolProperties()

Usage

Gets all underlying protocol properties from the device on the network.

Every call to this function will go out to the underlying network to retrieve all the values for the remote device.

This is a non-blocking call which returns a CompletableFuture of a Collection of Property objects.

Parameters

None.

Returns

Examples

GatewayClient gwgateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));

...
final
Device sourceDevicedevice = gwgateway.getDevice(sourceIdid);
sourceDevice.bindDevice(destinationId, property)
			.get()
	CompletableFuture<Collection<Property>> properties = device.getProtocolProperties();
            
// do some extra .getCommandResult(asynchronous) 	handling on the properties, once they've been discovered.
properties.whenComplete(thenAccept(result, error)collection -> {
	    // This code will be called from a ifthread (error != null) {
	    managed by gateway api.
    // We should avoid blocking code in this section.
    for (Property p : collection) {
        System.out.println("error calling bindname: " + errorp.getMessagegetName()); 	+ ", value: " + p.getValue() + ",  type: "  } 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

...

Returns

...

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+ p.getType());
    }
});

...

// 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 back

getCachedProtocolProperties()

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

Examples

GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device sourceDevicedevice = gwgateway.getDevice(sourceIdid);
sourceDevice.unbindDevice(destinationId, property)
			.get()
	   Collection<Property> properties = d.getCachedProtocolProperties();
for (Property p : properties) {
    System.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

...

A list of Parameter objects representing various configuration options.

See below for a list of configuration parameters that are currently supported.

Configuration Parameters:

...

Returns

...

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

...

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);out.println("name: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
}

updateProperty(Property property)

Usage

Updates the Property associated with this device.

Parameters

Returns

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());    
    }
});

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

Returns

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

Returns

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

Configuration Parameters:

...

Returns

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

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

Returns

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("Property: " + property.getName() + ", value: " + property.getValue() + ", type: " + property.getType());
}

...

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("Property: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
});

removePropertyUpdateHandler(BiConsumer<Device, Property> handler)

Usage

Removes a previously added handler.

Parameters

Returns

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);

removeAllPropertyUpdateHandlers()

Usage

Removes all handlers that have been previously registered.

Parameters

None.

Returns

Examples

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
gw.getDevice(id).removeAllPropertyUpdateHandlers();

addProtocolHandler(BiConsumer<Device, String> handler)

Usage

Adds a Protocol Handler that is triggered when any protocol level message from the Device is being passed through to the application.

Will reject duplicate handler instances.

Parameters

Returns

Examples

public class SampleProtocolHandler implements BiConsumer<Device, String> {
    @Override
    public void accept(Device device, String json) {
        // This method will be called whenever an underlying protocol message is being passed through.
        // By default, client callbacks are called from a single thread managed by GAPI.
        // Therefore, avoid writing blocking code in this method, or other client callbacks
        // (such as DeviceEventHandlers, or PropertyUpdateHandlers) may be blocked.

        // See the ProtocolPassthrough documentation for the format of the json message,
        // or inspect the ZigBeeMessageTypeAdapter class for possible key names.
        try {
            final JsonObject jsonObject = jsonParser.parse(json).getAsJsonObject();
            final JsonObject message = jsonObject.get(ZigBeeMessageTypeAdapter.MESSAGE_KEY).getAsJsonObject();
            
            System.out.println("protocol passthru msg: " + message.toString());

        } catch (Exception ex) {
            System.out.println("StatusException handling forprotocol commandmsg: " + result);json }+ catch (IllegalStateException | InterruptedException | ExecutionException | TimeoutException e) {", Exception: " + ex.toString());
         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

...

Returns

None.

Examples

GatewayClient gw}
    }
}

...

GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
final Device d = gw.getDevice(id);
d.addPropertyUpdateListener(p.ZIGBEE_UART, "/dev/ttyUSB0"));
Device device = gateway.getDevice(id);

// example of supplying a class that implements the BiConsumer<Device, String> interface
device.addProtocolHandler(new SampleProtocolHandler());

// example of a supplying a lambda
d.addPropertyUpdateListener( (d,json) -> {
	System.out.println("Propertylambda property update triggered for device " + d.getID());
    System.out.println("Property: " + pd.getNamegetID());
+ ", value: " + p.getValue() + ", type System.out.println("json: " + p.getType(json));
});

...

removeProtocolHandler(BiConsumer<Device, String> handler)

Usage

Removes a previously added listenerhandler.

Parameters

Returns

...

Return Type	Description
boolean	Returns true if the handler was removed; false otherwise.

Examples

GatewayClient gwgateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
gw

SamplePropertyUpdateHandler handler = new SampleProtocolHandler();
gateway.getDevice(id).addProtocolHandler(handler);
...
// do stuff
...
gateway.getDevice(id).removePropertyUpdateListenerremoveProtocolHandler(myPropertyUpdateListenerhandler);

...

removeAllProtocolHandlers()

Usage

Removes all listeners handlers that have been previously registered.

Parameters

None.

Returns

...

Return Type	Description
boolean	Returns true if any handlers were removed; false otherwise.

Examples

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
gw.getDevice(id).removeAllPropertyUpdateListenersremoveAllProtocolHandlers();

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();

...