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. Otherwise, on any failure, 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

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 the following code from the DeviceEventListener callback:

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

Updating Properties

You can update a Device Property as follows

Updating a Property

final Device d = gw.getDevice(idStr);
Property property = new Property(propertyId, "", writeValue);
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());
    }
});

Conclusion

...

Programming Guide