...

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

...

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

Properties API

...

getManufacturerName()

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 devicethe 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 which returns a CompletableFuture of a Collection of Property objects.

Parameters

None.

Returns

Examples

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

...

Device device = gatewaygw.getDevice(id);
CompletableFuture<Collection<Property>> properties =
device.getPropertiesgetManufacturerName();.thenAccept( name -> System.out.println(name)          
// 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 back

getCachedProperties()

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.

...

);
...

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

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

Examples

GatewayClient gatewaygw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gatewaygw.getDevice(id);
Collection<Property>
collection = device.getCachedPropertiesgetModelNumber();

for (Property p : collection) {
    .thenAccept( modelNum -> System.out.println(p.toString(modelNum) );
}

...

...

Properties API

getProperties()

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 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 the requested Property objects.

Parameters

...

None.

Returns

Returns

Examples

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

...

Device device = gateway.getDevice(id);
CompletableFuture<Property>CompletableFuture<Collection<Property>> futurePropertyproperties = device.getPropertygetProperties(propertyName);
 // This is an example of blocking on the future and waiting
for// ado result.some Property property = futureProperty.get(30, TimeUnit.SECONDS);
System.out.println(p.toString());

// One could also provide code thatextra (asynchronous) handling on the properties, once they've been discovered.
properties.thenAccept( collection -> {
    // This code will be called asynchronouslyfrom oncea thethread CompletableFuturemanaged hasby finishedgateway 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

...

Returns

...

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

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 back

getCachedProperties()

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

Examples

GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
Optional<Property>Collection<Property> optionalcollection = device.getCachedPropertygetCachedProperties(propertyName);

iffor (optional.isPresent()) {
    Property p = optional.get();: collection) {
    System.out.println(p.toString());
}

...

getProperty(String propertyName)

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 devicethe 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 a Collection of the requested Property objects.

Parameters

...

Returns

Returns

Examples

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

...

Device device = gateway.getDevice(id);
CompletableFuture<Collection<Property>>CompletableFuture<Property> propertiesfutureProperty = device.getProtocolPropertiesgetProperty(propertyName);

// This is an example of blocking on the future and waiting //for doa someresult.
extraProperty (asynchronous)property handling on the properties, once they've been discovered.
properties.thenAccept( collection -> {
    // This code = futureProperty.get(30, TimeUnit.SECONDS);
System.out.println(p.toString());

// One could also provide code that will be called fromasynchronously aonce threadthe managedCompletableFuture byhas gatewayfinished
apifutureProperty.thenAccept( p ->   // 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 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

...

A Collection of Property objects containing the last known value for that Property.

Examples

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

Returns

Examples

GatewayClient gateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gateway.getDevice(id);
Collection<Property>Optional<Property> propertiesoptional = ddevice.getCachedProtocolPropertiesgetCachedProperty(propertyName);
forif (optional.isPresent()) {
    Property p : properties) {= optional.get();
    System.out.println(p.toString());
}

...

getProtocolProperties()

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

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

Examples

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

...

Device device = gateway.getDevice(id);

CompletableFuture<Collection<Property>> properties = device.discoverAllPropertiesgetProtocolProperties();
 // asynchronously print out the values once discovery is complete   
// 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("Discovered: " + p.toString());
    }
});

updateProperty(Property property)

Usage

Updates the Property associated with this device.

Parameters

...

...

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

Examples

GatewayClient gwgateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// turn a light device on
final Device d = gwDevice device = gateway.getDevice(id);
PropertyCollection<Property> propertyproperties = new Property("OnOff, "boolean", "true");
d.updateProperty(property).getFuture().whenComplete( (result, throwable) -> {
    if (throwable != null) {
    d.getCachedProtocolProperties();
for (Property p : properties) {
    System.out.println("error: " + throwable.getMessage()p.toString);

   } 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

...

}

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

Throws

...

Examples

GatewayClient gwgateway = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device sourceDevicedevice = gwgateway.getDevice(sourceIdid);
String
CompletableFuture<Collection<Property>> destinationDeviceIdproperties = sourceDevicedevice.getConnectedGatewayIddiscoverAllProperties().get();
sourceDevice.bindDevice(destinationDeviceId, property)
			.get()
	        .getCommandResult()
	        .whenComplete((result, error)
// asynchronously print out the values once discovery is complete.
properties.thenAccept( collection -> {
	    for (Property p      if (error != null: collection) {
	
               System.out.println("error calling bindDiscovered: " + errorp.getMessagetoString());
	            } else {
	            	System.out.println("bind device result: " + result);
	            }
			});

...

}
});

updateProperty(Property property)

Usage

Removes the binding between this device (the source) and the destination deviceUpdates the Property associated with this 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

...

Returns

Examples

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// turn a light device on
final Device sourceDeviced = gw.getDevice(sourceIdid);
StringProperty destinationDeviceIdproperty = sourceDevice.getConnectedGatewayId().get(new Property("OnOff, "boolean", "true");
sourceDeviced.unbindDeviceupdateProperty(destinationDeviceId, property)
			.getgetFuture()
	        .getCommandResult()
	        .whenComplete(.whenComplete( (result, errorthrowable) -> {
	            if (errorthrowable != null) {
	   
            System.out.println("error calling unbind: " + errorthrowable.getMessage());
	       
    } else {if 	(result != null) {
        	System.out.println("unbind device result: " + result.getValue());
	    
       }
			});

...

Binding and Attribute Reporting API

bindDevice(String destinationDeviceId, String propertyToBind

...

)

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

Configuration Parameters:

Configuration parameters vary depending on the "DIRECTION" parameter. Currently, only one value of the DIRECTION parameter is supported:

...

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

...

...

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);
	 } catch (Exception e) {     throw new CompletionException(e }
			});
}

...

unbindDevice(String destinationDeviceId, String propertyToBind

...

)

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 effectRemoves the binding between this device (the source) and the destination device.

Parameters

...

Returns

Returns

Throws

IllegalStateException if the function is called before the Device Properties have been discovered (i.e. through getProperties()).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 devicesourceDevice = gw.getDevice(idStrsourceId);
tryString {destinationDeviceId     final String result = device.enableDefaultReporting().get(30, TimeUnit.SECONDS);= sourceDevice.getConnectedGatewayId().get();
sourceDevice.unbindDevice(destinationDeviceId, property)
	        .whenComplete((result, error) -> {
	          System.out.println("Status for command:if "(error +!= result);
} catch (IllegalStateException | InterruptedException | ExecutionException | TimeoutException e) {null) {
	                System.out.println(e"error calling unbind: " + error.getMessage());
}

Handlers API

addPropertyUpdateHandler(BiConsumer<Device, Property> handler)

Usage

Adds a Property update listener that is triggered when any Property on a Device changes.

...

	            } 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

Returns

...

Examples

...

...

Configuration Parameters:

Configuration parameters vary depending on the "DIRECTION" parameter. Currently, only one value of the DIRECTION parameter is supported:

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

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, PropertyString propertyjson) {
        // This method will getsbe called whenever a Property on a device changesan underlying protocol message is being passed through.
        // By default, client callbacks are called from a single thread managed by gateway apiGAPI.
        // 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

...

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

...

An instance or lambda that implements the BiConsumer<Device, String> interface.

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(); 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("Exception handling protocol msg: " + json + ", Exception: " + ex.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, String> interface
device.addProtocolHandler(new SampleProtocolHandler());

// example of a supplying a lambda
d.addPropertyUpdateListener( (d,json) -> {
	System.out.println("lambda property update triggered for device: " + d.getID());
    System.out.println("json: " + json);
});

removeProtocolHandler(BiConsumer<Device, String> handler)

Usage

Removes a previously added handler.

Parameters

Returns

Examples

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

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

removeAllProtocolHandlers()

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

Network API

ping()

Usage

Gets the round-trip latency from the Device to the Gateway.

This is a non-blocking call.

Will complete exceptionally on all errors.

Parameters

None.

Returns

The result is a JSON string with 5 key/value pairs if it was successful

{
  "status":{"value":[0]},           // byte final JsonObject messagevalue: 0 = jsonObject.get(ZigBeeMessageTypeAdapter.MESSAGE_KEY).getAsJsonObject();
     success, non-zero = failure
  "latency":46,                    System.out.println("protocol passthru msg: " + message.toString());

        } catch (Exception ex) {
            System.out.println("Exception handling protocol msg: " + json + ", Exception: " + ex.toString());
        }
    }
}

...

GatewayClient gateway // in ms
  "directOrIndirect":{"value":[1]}, // byte value: 0 = response received directly from target device, 1 = response received indirectly from target device
  "lastHopLQI":255,					// LQI of last responding hop
  "lastHopRSSI":-13					// RSSI (in dBm) of last responding hop
}

Throws

The CompletableFuture returned by this method will throw a TimeoutException if the request does not receive a response from the target node after 20 seconds.

Examples

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
Device device = gatewaygw.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("lambda property update triggered for device: " + d.getID());
    System.out.println("json: " + json);
});

removeProtocolHandler(BiConsumer<Device, String> handler)

Usage

...

device.ping().thenAccept( pingResult -> System.out.println(pingResult) );
...

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

sendProtocolMessage(String json)

Usage

Send a protocol-specific message using the underlying network protocol.

Parameters

...

Returns

...

Protocol Message Specification

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

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

removeAllProtocolHandlers()

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

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

sendProtocolMessage(String json)

Usage

Send a protocol-specific message to the Device using the underlying device protocol.

Parameters

...

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_unicast",
	"message":
		{
			"nodeId":"0x1234",
			"endpointId":"0x01",
			"localEndpoint":"0x01",		// optional, will default to 0x01
			"clusterId":"0x0006",
			"responseOptions":"0x02", 	// optional, will default to no response
			"encryption":"0x01", 		// optional, will default to network encryption
			"frameControl":"0x00",		// optional, will default to ZCL General Command, Client-to-Server
			"manufacturerCode":"0x00", 	// optional, will only be read if frameControl requires it
			"transactionNum":"0x00",	// optional, will only be read if responseOptions requires it
			"commandId":"0x00",
			"payload":"0x0001030405" 	// optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_unicastmulticast",
	"message":
		{
			"nodeIdgroupId":"0x12340x0001",
			"endpointId":"0x01",
			"localEndpoint":"0x01",		// optional, will default to 0x01
			"clusterId":"0x0006",
			"responseOptionsradius":"0x02", 	0x00"				// optional, will default to 0x00 (max radius)
			"nonMemberRadius":"0x07",   // optional, will default to no response0x07 (infinite non-member-radius)
			"encryptionresponseOptions":"0x010x02", 		// optional, will default to networkno encryptionresponse
			"frameControl":"0x00",		// optional, will default to ZCL General Command, Client-to-Server
			"manufacturerCode":"0x00", 	// optional, will only be read if frameControl requires it
			"transactionNum":"0x00",	// optional, will only be read if responseOptions requires it
			"commandId":"0x00",
			"payload":"0x0001030405" 	// optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

...

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zcl_multicastbroadcast",
	"message":
	"message":
		{	{
			"broadcastAddress":"0xFD",
			"groupIdendpoint":"0x00010x01",
			"localEndpoint":"0x01",		// optional, will default to 0x01
			"clusterId":"0x0006",
			"radius":"0x00"				// optional, will default to 0x00 (max radius)
			"nonMemberRadius":"0x07",   // optional, will default to 0x07 (infinite non-member-radius)
			"responseOptions":"0x02", 	// optional, will default to no response
			"frameControl":"0x00",		// optional, will default to ZCL General Command, Client-to-Server
			"manufacturerCode":"0x00", 	// optional, will only be read if frameControl requires it
			"transactionNum":"0x00",	// optional, will only be read if responseOptions requires it
			"commandId":"0x00",
			"payload":"0x0001030405" 	// optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

...

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zdo_unicast",
	"message":
		{
			"nodeId":"0x1234",
			"responseOptions":"0x02", 	// optional, will onlydefault beto readno if frameControl requires it
response
			"transactionNum":"0x00",	// optional, will only be read if responseOptions requires it
			"commandId":"0x000x0001",
			"payload":"0x0001030405" 	// optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

...

{
	"gatewayApiVersion":"2.0.4{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zdo_broadcast",
	"message":
		{
			"broadcastAddress":"0xFD",
			"protocolNameradius":"zigbee",
	"protocolVersion0x00"				// optional, will default to 0x00 (max radius)
			"responseOptions":"3",
	"messageType":"zdo_unicast",
	"message":
		{0x02", 	// optional, will default to no response
			"transactionNum":"0x00",	// optional, will only be read if responseOptions requires it
			"nodeIdcommandId":"0x12340x0001",
			"responseOptionspayload":"0x020x0001030405", 	// optional, will default to no response
			"transactionNum":"0x00",	// optional, will only be read if responseOptions requires it
			"commandId":"0x0001",
			"payload":"0x0001030405" 	// optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

{
	"gatewayApiVersion":"2.0.4",
	"protocolName":"zigbee",
	"protocolVersion":"3",
	"messageType":"zdo_broadcast",
	"message":
		{
			"broadcastAddress":"0xFD",
			"radius":"0x00"				// optional, will default to 0x00 (max radius)
			"responseOptions":"0x02", 	// optional, will default to no response
			"transactionNum":"0x00",	// optional, will only be read if responseOptions requires it
			"commandId":"0x0001",
			"payload":"0x0001030405" 	// optional, can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

Returns

...

 can omit if there's no payload. Otherwise, expect byte(s) in adherence to the zigbee spec
		}
}

Returns

Protocol Message Response Specification

{
    "gatewayApiVersion":"2.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",
    "messageType":"zcl_response",  // other valid value is zcl_passthrough_message
    "message":
        {
            "sourceNode":"0xCB13",
            "sourceEndpoint":"0x01",
            "localEndpoint":"0x01",
            "clusterId":"0x0006",
            "encryption":"0x00",
            "frameControl":"0x02",
            "manufacturerCode":"0x0000",
            "transactionNum":"0x7C",
            "commandId":"0x01",
            "payload":"0x01436300"
        }
}

{
    "gatewayApiVersion":"2.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",,
    "messageType":"zdo_response",
    "message":
        {
            "messageTypesourceNode":"zcl_response0xCB13",
  // other valid value is zcl_passthrough_message     "messagetransactionNum":"0x7C",
        {             "sourceNode"commandId":"0xCB130x0001",
            "sourceEndpointpayload":"0x010x01436300",
        }
}

{
    "localEndpointgatewayApiVersion":"0x012.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",
    "clusterIdmessageType":"0x0006default_response",
    "status":"0x00" // 0x00 is always success; anything else  "encryption":"0x00",
            "frameControl":"0x02",
            "manufacturerCode":"0x0000",
            "transactionNum":"0x7C",
            "commandId":"0x01",
            "payload":"0x01436300"
        }
}

{
    "gatewayApiVersion":"2.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",
    "messageType":"zdo_response",
    "message":
        {
            "sourceNode":"0xCB13",
            "transactionNum":"0x7C",
            "commandId":"0x0001",
            "payload":"0x01436300"
        }
}

{
    "gatewayApiVersion":"2.0.4",
    "protocolName":"zigbee",
    "protocolVersion":"3",
    "messageType":"default_response",
    "status":"0x00" // 0x00 is always success; anything else may refer to a general or specific failure
}

Examples

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// This is an example of using the Protocol Passthrough API, with a zigbee message formed as a json string.
// The zigbee message we're forming is a Zone Enroll Response Command (see ZCL Spec Section 8.2.2.3.1)
Device device = gw.getDevice(id);
Optional<Property> protocolProperty = device.getCachedProperty(PropertyNames.PROTOCOL_PROPERTY_NAME);
if (protocolProperty.isPresent()) {
    Property p = protocolProperty.get();
    JsonObject jsonObject = jsonParser.parse(p.getValue()).getAsJsonObject();
    
    ZCLUnicastMessageBuilder builder = new ZCLUnicastMessageBuilder();
    builder.setGatewayAPIVersion(GatewayClient.getApiVersion());
    builder.setProtocolName("zigbee");
    builder.setProtocolVersion(3);
    builder.setNodeID(jsonObject.get(ZigBeeMessageTypeAdapter.NODE_ID_KEY).getAsString());
    builder.setEndpointID(jsonObject.get(ZigBeeMessageTypeAdapter.ENDPOINT_ID_KEY).getAsString());
    builder.setClusterID(IAS_ZONE_CLUSTER_ID);
    builder.setResponseOptions(ZigBee.FrameConstants.RESPONSE_OPTIONS_APS_RESPONSE.toBitmap8());
    builder.setFrameControl(ZigBee.FrameConstants.FRAME_CONTROL_CLIENT_TO_SERVER_CLUSTER_CMD.toBitmap8());
    builder.setCommandID(ZONE_ENROLL_RESPONSE_ID);
    // Zone Enroll Response:
    // Field 1: 00 - enroll success
    // Field 2: 01 - zone id
    // therefore, final payload is: 0x0001 
    builder.setPayload("0x0001");
    ZCLUnicastMessage message = builder.build();
    
    device.sendProtocolMessage(message.toJson())
          .thenAccept(jsonResponse -> System.out.println(jsonResponse));
}

may refer to a general or specific failure
}

Examples

GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0"));
...
// This is an example of using the Protocol Passthrough API, with a zigbee message formed as a json string.
// The zigbee message we're forming is a Zone Enroll Response Command (see ZCL Spec Section 8.2.2.3.1)
Device device = gw.getDevice(id);
Optional<Property> protocolProperty = device.getCachedProperty(PropertyNames.PROTOCOL_PROPERTY_NAME);
if (protocolProperty.isPresent()) {
    Property p = protocolProperty.get();
    JsonObject jsonObject = jsonParser.parse(p.getValue()).getAsJsonObject();
    
    ZCLUnicastMessageBuilder builder = new ZCLUnicastMessageBuilder();
    builder.setGatewayAPIVersion(GatewayClient.getApiVersion());
    builder.setProtocolName("zigbee");
    builder.setProtocolVersion(3);
    builder.setNodeID(jsonObject.get(ZigBeeMessageTypeAdapter.NODE_ID_KEY).getAsString());
    builder.setEndpointID(jsonObject.get(ZigBeeMessageTypeAdapter.ENDPOINT_ID_KEY).getAsString());
    builder.setClusterID(IAS_ZONE_CLUSTER_ID);
    builder.setResponseOptions(ZigBee.FrameConstants.RESPONSE_OPTIONS_APS_RESPONSE.toBitmap8());
    builder.setFrameControl(ZigBee.FrameConstants.FRAME_CONTROL_CLIENT_TO_SERVER_CLUSTER_CMD.toBitmap8());
    builder.setCommandID(ZONE_ENROLL_RESPONSE_ID);
    // Zone Enroll Response:
    // Field 1: 00 - enroll success
    // Field 2: 01 - zone id
    // therefore, final payload is: 0x0001 
    builder.setPayload("0x0001");
    ZCLUnicastMessage message = builder.build();
    
    device.sendProtocolMessage(message.toJson())
          .thenAccept(jsonResponse -> System.out.println(jsonResponse));
}

Upgrade API

startOtaUpgrade()

Usage

Notifies the remote device that an OTA image is available for upgrade.

Assumes that GatewayClient.registerOtaFile(...) API has been called first to register a valid OTA upgrade file that the remote device will accept.

Notes:

• All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.
• This is a non-blocking call.
• This method is thread-safe.

Parameters

None.

Returns

None.

All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.

Examples

ConnectionInfo c = new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0");
GatewayClient gw = new GatewayClient(c);
...
gw.registerOtaFile("path/to/otaFile.ota", c);
gw.registerOtaProgressHandler( progress -> 
    System.out.println("DeviceId: " + progress.getId() + ", Progress: " + progress.getProgress() + " %")
);
...
Device device = gw.getDevice(id);
device.startOtaUpgrade();
...

abortOtaUpgrade()

Usage

Signals the remote device that it should stop any on-going OTA upgrade, and stops serving OTA upgrade files to that device.

Notes:

• All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.
• This is a non-blocking call.
• This method is thread-safe.

Parameters

None.

Returns

None.

All status messages and progress updates associated with the upgrade will be relayed through the callback that was registered using the GatewayClient.registerOtaProgressHandler(...) API.

Examples

ConnectionInfo c = new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyUSB0");
GatewayClient gw = new GatewayClient(c);
...
gw.registerOtaFile("path/to/otaFile.ota", c);
gw.registerOtaProgressHandler( progress -> 
    System.out.println("DeviceId: " + progress.getId() + ", Progress: " + progress.getProgress() + " %")
);
...
Device device = gw.getDevice(id);
device.startOtaUpgrade();
...
device.abortOtaUpgrade();