Overview

This page describes how to develop against the Gateway API. It goes over the basics of initializing a GatewayClient object, and interacting with Device references.

Initializing GatewayClient

Initialize a GatewayClient by passing in a ConnectionInfo object, which contains details about what the connection type is (i.e. a zigbee uart port) and a string describing where to connect to it.

In the following example, we also pass in a lambda that will handle device events by simply printing them out. In a real application, you can replace this with your own event handling method, or an object that implements the DeviceEventListener interface.

Initializing GatewayClient

// example of a lambda implementation of the DeviceEventListener parameter.
final GatewayClient gw = new GatewayClient(new ConnectionInfo(ConnectionType.ZIGBEE_UART, "/dev/ttyS1"),
    (event) -> {
        System.out.println("Device Event: " + event.getStatus());
        System.out.println("Device: " + event.getDevice().getID());
    }
);

Once constructed, the GatewayClient will automatically connect to the device, configure it as a Combined Interface, and form a network. If it can't connect to or configure the device, it will throw a GatewayConnectionException.

Scanning for Devices

To join a device to the network, you first have to open the permit join window on the GatewayClient.

The following example shows how to call "scanForDevices" on all known connections for a duration of 30 seconds. It also implements a callback displaying the status of the command. The expected result should be "NETWORK_OPEN".

Scanning for Devices (i.e. opening the permit join window)

for (ConnectionInfo c: gw.getConnectionInfo()) {
    gw.scanForDevices(c, 30).thenAccept( status -> {
        System.out.println("Status for connection " + c.getValue() + " is " + status);
    });
}

Once the permit join window is open, you can initiate the pairing process from a secondary (i.e. remote) device.

Note: You can close the permit join window by calling "scanForDevices" with 0 as the "duration" parameter.

Interacting with Devices

When a device joins the network, you should see a DeviceEvent. For example, the lambda we passed into GatewayClient should print something like the following:

Device Event: ADD
Device ID: 00244600000f1472_1

Getting Properties

getProperties()

You can use the Device API to request properties of the connected device.

For example, to automatically discover the properties of a device the first time the GatewayClient becomes aware of it, you can run something like the following code from the DeviceEventListener callback:

The first time 'getProperties' is called, the system will perform a discovery of the remote device's properties over the network. This may take some time; however, any subsequent call will return the last known value immediately. For more details, see the API documentation for getProperties().

Discovering Properties

if (event.getStatus() == DeviceEventStatus.ADD) {
    final Collection<Property> properties = event.getDevice().getProperties();
    for (Property p : properties) {
        System.out.println("name: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
    }
}

getProperty()

You can also get specific properties using the getProperty() method. For example, to get the "OnOff" property from a LightDevice, you could do something like the following:

Getting a Property

final Property p = device.getProperty("OnOff").getFuture().get(5, TimeUnit.SECONDS);
System.out.println("name: " + p.getName() + ", value: " + p.getValue());

Updating Properties

You can update a Device Property by providing the name and value.

For example, to update the "OnOff" property, you could do something like the following:

Updating a Property

Property property = new Property("OnOff, "boolean", "true");
gw.getDevice(id).updateProperty(property);

LightDevice

The Gateway API will return a specific class for certain devices. Specific device classes, such as LightDevice, will have their own convenience methods that allow you to skip using the getProperty/updateProperty API's.

For example, for a LightDevice, you could interact with it as follows:

LightDevice API

final Device d = gw.getDevice(id);
if (d instanceof LightDevice) {
    final LightDevice light = (LightDevice) d;
    light.off();
    light.on();
	light.readLevel();
	light.moveToLevel(50);
} else {
    System.out.println("device is not a light");
}

See the LightDevice API for more info.

ThermostatDevice

The Gateway API will return a specific class for certain devices. Specific device classes, such as ThermostatDevice, will have their own convenience methods that allow you to skip using the getProperty/updateProperty API's.

For example, for a ThermostatDevice, you could interact with it as follows:

ThermostatDevice API

final Device d = gw.getDevice(id);
if (d instanceof ThermostatDevice) {
	final ThermostatDevice device = (ThermostatDevice) d;
	device.readMode();
	device.changeMode(SystemMode.AUTO);
} else {
	System.out.println("device is not a thermostat");
}

See the ThermostatDevice API for more info.

Listening for Device Property Updates

You can be notified when a Property on a Device changes by registering a "Property Update Listener". In Java, this can be any object that implements the "Consumer" interface, or a lambda.

For example, to automatically register an update listener the first time the GatewayClient becomes aware of a device, you can run something like the following code from the DeviceEventListener callback:

Adding a Property Update Listener

if (event.getStatus() == DeviceEventStatus.ADD) {
    final Device d = event.getDevice();
    final String deviceId = d.getID();
    d.addPropertyUpdateListener(p -> {
        System.out.println("Property update triggered for device: " + deviceId);
        System.out.println("Property: " + p.getName() + ", value: " + p.getValue() + ", type: " + p.getType());
    });
}

The above example will simply print out the Device ID, as well as the Property name, value, and type, whenever the Property changes.

Shutdown

To perform a graceful shut down of the GatewayClient, allowing for all subsystems to save any critical data and release system resources (such as file handles, open ports, user threads), you must call the shutdown() method. Since the GatewayClient creates user threads, not performing a shutdown may keep the JVM running even after your application has exited.

Shutting down the GatewayClient

...
gw.shutdown();
...

See the GatewayClient API for more details.

Conclusion

This programming guide has shown how to initialize a GatewayClient, join devices, get their properties, and interact with them in a simple way.

To explore further, please see the API documentation.

Programming Guide